# Update organization

Canonical page: https://docs.ovok.com/slim-apis/organization/update-organization

| Method | Path |
| --- | --- |
| `PUT` | `/v1/slim/organization/:id` |

[Authentication](/authentication) · [Access policies](/access-policies)

Updates an organization's (zone's) name, description and parent zone.

**Auth:** Bearer token. The caller must be a practitioner, an admin, a super admin, or hold the "System Owner" access policy. The access policy must grant `Organization:update` (admins and super admins skip this check).
**Scope:** The organization must belong to the caller's project (from the token). Organizations in a parent project or a sub-project are refused.

## Request [#request]

### Path parameters [#path-parameters]

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string (uuid)` | Yes | Organization (zone) id. |

### Body [#body]

The body is strict: a field that is not listed here fails validation. Omit `parentOrganizationId` to make the zone top-level.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Yes | Zone name. At least 1 character. Must be unique. |
| `parentOrganizationId` | `string (uuid)` | No | Parent zone. Must be in your project. |
| `description` | `string` \| `null` | No | Narrative text for the zone. |

## Behaviour [#behaviour]

- `name` is required and must be unique among the organizations your token can search, not counting this one.
- `parentOrganizationId` sets the parent zone. It must name an organization in your own project. **Omitting it removes the current parent**, which makes the zone top-level.
- `description`, when non-empty, replaces the narrative text. Omitting it, or sending `null` or an empty string, leaves the existing description unchanged.
- The write is atomic and takes a short write lock. A concurrent write to the same resources gets a 409.
- A rename adds a zone-renamed entry to the change history. A save that does not change the name adds none. A failure to write the entry does not fail the request.
- The response is the organization after the update, in the same shape as `GET /v1/slim/organization/{id}`.

## Example [#example]

```bash
curl -X PUT 'https://api.sandbox.ovok.com/v1/slim/organization/3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21' \
  -H "Authorization: Bearer ${OVOK_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Ward A",
    "parentOrganizationId": "1e6b8d30-2c4f-4a95-8d7e-b0a2c4e6f918",
    "description": "Ground floor"
  }'
```

## Successful response [#successful-response]

`200` — Organization updated successfully.

```json
{
  "id": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21",
  "name": "Ward A",
  "parentOrganizationId": "1e6b8d30-2c4f-4a95-8d7e-b0a2c4e6f918",
  "description": "Ground floor"
}
```

The body is the organization after the update, as `GET /v1/slim/organization/{id}` returns it.

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` | Organization (zone) id. |
| `name` | `string` | Zone name. Empty string when the organization has no name. |
| `parentOrganizationId` | `string (uuid)` | Id of the parent zone. Left out for a top-level zone. |
| `description` | `string` | Narrative text without its XHTML wrapper. Left out when there is none. |

## Errors [#errors]

| Status | Meaning |
| --- | --- |
| [`400`](/errors/malformed-request) | The parent organization does not exist, the new parent would create a cycle in the zone tree, or the FHIR backend refuses the write. |
| [`401`](/errors/unauthenticated) | Bearer token is missing, invalid or expired. |
| [`403`](/errors/forbidden) | You are not a practitioner, admin or System Owner, you lack `Organization:update`, the organization does not exist or is outside your project, or the parent organization is not in your project. |
| [`409`](/errors/conflict) | Another write holds the organization or its parent, or the FHIR backend reports a write [`conflict`](/errors/conflict). Retry. |
| [`422`](/errors/validation-failed) | The body or `id` fails validation, or another organization has the same name. |
