# Create organization

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

| Method | Path |
| --- | --- |
| `POST` | `/v1/slim/organization` |

[Authentication](/authentication) · [Access policies](/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 [#request]

### Query parameters [#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 [#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 [#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 [#example]

```bash
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 [#successful-response]

`201` — Organization created successfully.

```json
{
  "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 [#errors]

| Status | Meaning |
| --- | --- |
| [`400`](/errors/malformed-request) | The parent organization does not exist, 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:create`, you set `projectId` without being a super admin, or the parent organization is not in your project. |
| [`409`](/errors/conflict) | Another write holds the parent organization, or the FHIR backend reports a write [`conflict`](/errors/conflict). Retry. |
| [`422`](/errors/validation-failed) | The body or `projectId` fails validation, `projectId` names no project, or another organization has the same name. |
