Organizations

Create organization

Create organization using Ovok’s Slim API.

MethodPath
POST/v1/slim/organization

Authentication · Access policies

Creates an organization (a zone in the Slim dashboard), optionally as a child of another 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:create (admins and super admins skip this check). Scope: The organization is created in the caller's project (from the token). A super-admin caller can pass ?projectId=<uuid> to create it in that project instead. Any other caller who passes projectId gets a 403.

Request

Query parameters

NameTypeRequiredDescription
projectIdstring (uuid)NoCreate the organization in this project. Super admins only. Must name an existing project.

Body

The body is strict: a field that is not listed here fails validation.

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 must be unique. The check is an exact name match against the organizations your token can search. With ?projectId, the check runs in that project only.
  • parentOrganizationId, when set, must name an organization in your own project. A sub-project's or parent project's organization is refused. The new zone's partOf points at it.
  • description, when non-empty, is stored as the organization's narrative text. null or an empty string stores nothing.
  • The write is atomic and takes a short write lock. A concurrent write to the same resources gets a 409.
  • A zone-created entry is added to the change history. A failure to write that entry does not fail the request.
  • The response is the created organization, in the same shape as GET /v1/slim/organization/{id}.

Example

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

Successful response

201 — Organization created successfully.

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

The body is the created organization, 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, 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:create, you set projectId without being a super admin, or the parent organization is not in your project.
409Another write holds the parent organization, or the FHIR backend reports a write conflict. Retry.
422The body or projectId fails validation, projectId names no project, or another organization has the same name.

Last updated on

On this page