Create organization
Create organization using Ovok’s Slim API.
| Method | Path |
|---|---|
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
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string (uuid) | No | Create 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.
| 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
namemust 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'spartOfpoints at it.description, when non-empty, is stored as the organization's narrative text.nullor 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.
| 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
| Status | Meaning |
|---|---|
400 | The parent organization does not exist, or the FHIR backend refuses the write. |
401 | Bearer token is missing, invalid or expired. |
403 | You 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. |
409 | Another write holds the parent organization, or the FHIR backend reports a write conflict. Retry. |
422 | The body or projectId fails validation, projectId names no project, or another organization has the same name. |
Last updated on