Update Organisation

/organisations/{id}

Updates an organisation by its ID.

Request parameters

{
  "name": "Acme Inc.",
  "status": "ACTIVE",
  "features": [
    [
      "CHAT",
      "MEDIPLAN"
    ]
  ],
  "metadata": {
    "title": "Welcome to your benefits page",
    "schema": "light",
    "setupStage": null,
    "billingContactEmail": "billing@acme.com"
  }
}

Responses

{
  "id": "019e4c12-0e1b-7bca-97ed-7f64a5a267f9",
  "name": "Acme Inc.",
  "status": "ACTIVE",
  "features": [
    "CHAT",
    "MEDIPLAN"
  ],
  "deletedAt": null,
  "metadata": {
    "title": "Welcome to your benefits page",
    "schema": "light",
    "setupStage": null
  }
}

{
  "error": "Request body is empty or contains malformed JSON."
}

{
  "errors": {
    "status": [
      "Status \"PENDING\" is invalid."
    ],
    "features": [
      "Feature \"POPUP\" is invalid.",
      "Feature \"FAQ\" is invalid."
    ],
    "name": [
      "This name is already in use."
    ]
  }
}

Fields That Cannot Be Updated

initialAdminEmail is accepted only when creating an organisation. Including it in a PATCH payload returns 422 — it is rejected rather than ignored, so a caller attempting to reassign an administrator gets a clear error instead of a silent no-op. There is currently no endpoint that reassigns an organisation's administrator.

How to Create, Update, and Delete Metadata

When updating an organisation via a PATCH request, the metadata object is treated as an absolute replacement of the existing metadata. The API determines whether to create, update, or delete keys based on what is included in the payload versus what currently exists in the database.

To leave metadata completely untouched: Omit the metadata field from your JSON payload entirely.
To delete all metadata: Send an empty object: "metadata": {}.
To create a new key: Include a key in the object that does not currently exist for the organisation.
To update an existing key: Include the existing key in the object with the new string value (or null).
To delete specific existing keys: Omit the key from the object. Any existing key that is not explicitly included in your metadata payload will be deleted.

Example Scenario

Assume the organisation currently has the following metadata:

{
  "billingTier": "enterprise",
  "accountManager": "john_doe",
  "legacyNotes": "Do not delete"
}

If you send the following PATCH request body:

{
  "metadata": {
    "billingTier": "startup",
    "supportLevel": "premium"
  }
}

The result will be:

billingTier is updated from "enterprise" to "startup".
supportLevel is created because it did not exist before.
accountManager and legacyNotes is deleted because it was omitted from the payload.

01 September 2026