Create organization

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.

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.

Errors

Status	Meaning
400	The parent organization does not exist, or Medplum 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 Medplum reports a write conflict. Retry.
422	The body or projectId fails validation, projectId names no project, or another organization has the same name.