Organizations

Update organization

Update organization using Ovok’s Slim API.

MethodPath
PUT/v1/slim/organization/:id

Authentication · 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

Path parameters

NameTypeRequiredDescription
idstring (uuid)YesOrganization (zone) id.

Body

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

NameTypeRequiredDescription
namestringYesZone name. At least 1 character. Must be unique.
parentOrganizationIdstring (uuid)NoParent zone. Must be in your project.
descriptionstring | nullNoNarrative text for the zone.

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

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

200 — Organization updated successfully.

{
  "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.

FieldTypeDescription
idstring (uuid)Organization (zone) id.
namestringZone name. Empty string when the organization has no name.
parentOrganizationIdstring (uuid)Id of the parent zone. Left out for a top-level zone.
descriptionstringNarrative text without its XHTML wrapper. Left out when there is none.

Errors

StatusMeaning
400The parent organization does not exist, the new parent would create a cycle in the zone tree, or the FHIR backend refuses the write.
401Bearer token is missing, invalid or expired.
403You 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.
409Another write holds the organization or its parent, or the FHIR backend reports a write conflict. Retry.
422The body or id fails validation, or another organization has the same name.

Last updated on

On this page