# Create patient

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

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

[Authentication](/authentication) · [Access policies](/access-policies)

Creates a resident (patient), optionally placed on devices, in a room and in a zone, and registers them with Signals.

**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 `Patient:create`, plus `Device:update` when `deviceId` is set (admins and super admins skip this check).
**Scope:** The resident 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. Devices, rooms and zones you reference must be in your project, its parent project, or one of its sub-projects.

## Request [#request]

### Query parameters [#query-parameters]

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string (uuid)` | No | Create the resident 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` | `object[]` | Yes | The resident's names. At least 1 entry. Must contain a `nickname` entry with a non-blank first `given` value (the Resident ID). |
| `name[].use` | `"official"` \| `"nickname"` \| `"maiden"` | Yes | Kind of name. |
| `name[].given` | `string[]` | No | Given names, in order. At least 1 entry when sent. Each entry is a non-empty string. |
| `name[].family` | `string` | No | Family name. Non-empty when sent. |
| `gender` | `"male"` \| `"female"` \| `"other"` \| `"unknown"` | No | Administrative gender. |
| `birthDate` | `string (YYYY-MM-DD)` | No | Date of birth. |
| `deviceId` | `string (uuid)` \| `string[]` | No | One device id or a list of ids to assign the resident to. `null` means no device. |
| `locationId` | `string (uuid)` | No | Room (location) to place the resident in. |
| `organizationId` | `string (uuid)` | No | Zone to place the resident in. Send it with `locationId` or `deviceId`. |
| `admissionDate` | `string (ISO 8601 date-time)` | No | Admission time. Defaults to now. Must not be later than the start of the current day. |

## Behaviour [#behaviour]

- `name` must contain an entry with `use: "nickname"` and a non-blank first `given` value. This is the Resident ID.
- Ovok stores `name[].given[]` and `name[].family` after trimming whitespace.
- The Resident ID must be unique in the project, compared as in `POST /v1/slim/patient/check-name-exists`.
- `admissionDate` defaults to now. It cannot be later than the start of the current day.
- The resident is created as `active`, and an `EpisodeOfCare` is opened for the admission.
- Placement:
  - `deviceId` (one id or a list): the resident is assigned to those devices. A device that already has a resident is reassigned to the new one.
  - `locationId` with `deviceId`: those devices are also moved to the room.
  - `locationId` without `deviceId`: the resident is assigned to the room's device. The room must have exactly one device.
  - `organizationId`: the resident is placed in the zone. When `deviceId` is set, those devices and their rooms move to the zone too.
  - Without `organizationId`, the resident takes the zone of their device: the room's zone when the device is in a room, otherwise the device's own zone.
- The resident is registered with Signals in the same request. If that fails, everything this request wrote is rolled back and you get a 503 with `error: "signals_mint_failed"` ([`signals_mint_failed`](/errors/signals-mint-failed)). You can retry.
- The write is atomic and locks the Resident ID and the devices, so two concurrent creates of the same Resident ID leave one resident.
- Change-history entries are added for each assignment.
- The response is the created resident, in the same shape as `GET /v1/slim/patient/{id}`.

## Example [#example]

```bash
curl -X POST 'https://api.sandbox.ovok.com/v1/slim/patient' \
  -H "Authorization: Bearer ${OVOK_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": [
      { "use": "nickname", "given": ["demo-resident"] },
      { "use": "official", "given": ["Anna"], "family": "Beispiel" }
    ],
    "gender": "male",
    "birthDate": "1940-05-01",
    "deviceId": "8c5e7a21-4b9d-4f36-a1c8-0d2e6b9f3a54",
    "locationId": "5d2a9c64-7e1b-4830-b6f5-9a3c1e8d7b02",
    "organizationId": "1e6b8d30-2c4f-4a95-8d7e-b0a2c4e6f918"
  }'
```

## Successful response [#successful-response]

`201` — Patient created successfully.

```json
{
  "id": "a9f4c2e8-1b6d-4d73-8e05-7c3b5a1d9f20",
  "name": [
    { "use": "nickname", "given": ["demo-resident"], "family": "" },
    { "use": "official", "given": ["Anna"], "family": "Beispiel" }
  ],
  "gender": "male",
  "birthDate": "1940-05-01",
  "deviceId": "8c5e7a21-4b9d-4f36-a1c8-0d2e6b9f3a54",
  "organizationId": "1e6b8d30-2c4f-4a95-8d7e-b0a2c4e6f918",
  "locationId": "5d2a9c64-7e1b-4830-b6f5-9a3c1e8d7b02",
  "floor": "1",
  "room": "101",
  "bed": "A",
  "residentState": "active",
  "admissionDate": "2026-10-09T00:00:00.000Z"
}
```

The body is the resident as `GET /v1/slim/patient/{id}` returns it.

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` | Patient id. |
| `name` | `object[]` | The resident's names. A name stored without a `use` is returned as `official`. |
| `name[].use` | `"official"` \| `"nickname"` \| `"maiden"` | Kind of name. |
| `name[].given` | `string[]` | Given names. Empty array when none. |
| `name[].family` | `string` | Family name. Empty string when none. |
| `gender` | `"male"` \| `"female"` \| `"other"` \| `"unknown"` | Left out when not set. |
| `birthDate` | `string (YYYY-MM-DD)` | Left out when not set. |
| `deviceId` | `string (uuid) \| null` | The resident's device. `null` when the resident has no device. When there are several, the most recently updated one. |
| `organizationId` | `string (uuid)` | Zone of that device's room. Left out when there is none. |
| `locationId` | `string (uuid)` | Room of that device. Left out when there is none. |
| `floor` | `string` | Floor of the room. Left out when not set. |
| `room` | `string` | Room name or number. Left out when not set. |
| `bed` | `string` | Bed. Left out when not set. |
| `residentState` | `"active"` \| `"discharged-recent"` \| `"discharged"` \| `"archived"` | Resident state. |
| `admissionDate` | `string` | Admission time as stored. Left out when not set. |
| `dischargeDate` | `string` | Discharge time as stored. Left out when not set. |

## Errors [#errors]

| Status | Meaning |
| --- | --- |
| [`400`](/errors/malformed-request) | 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 `Patient:create` (or `Device:update` when `deviceId` is set), you set `projectId` without being a super admin, your session has no project, or a referenced device, location or zone does not exist or is outside your project, its parent or its sub-projects. |
| [`409`](/errors/conflict) | The project is moving to another Signals tenant, another write holds the Resident ID or one of the devices, or a device was reassigned while the request ran. Retry. |
| [`422`](/errors/validation-failed) | The body or `projectId` fails validation, `projectId` names no project, the body has no Resident ID (`nickname` with a non-blank first `given`), the Resident ID is already in use, `locationId` without `deviceId` names a room with no device or more than one, the devices belong to different zones (`path: ["deviceId"]`), or `organizationId` is sent without `locationId` or `deviceId` (`path: ["organizationId"]`). |
| [`503`](/errors/service-unavailable) | Signals enrollment failed ([`signals_mint_failed`](/errors/signals-mint-failed)). The patient create is rolled back; see Behaviour for retry details. |
