Create patient
Create patient using Ovok’s Slim API.
| Method | Path |
|---|---|
POST | /v1/slim/patient |
Authentication · 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
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
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
namemust contain an entry withuse: "nickname"and a non-blank firstgivenvalue. This is the Resident ID.- Ovok stores
name[].given[]andname[].familyafter trimming whitespace. - The Resident ID must be unique in the project, compared as in
POST /v1/slim/patient/check-name-exists. admissionDatedefaults to now. It cannot be later than the start of the current day.- The resident is created as
active, and anEpisodeOfCareis 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.locationIdwithdeviceId: those devices are also moved to the room.locationIdwithoutdeviceId: the resident is assigned to the room's device. The room must have exactly one device.organizationId: the resident is placed in the zone. WhendeviceIdis 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). 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
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
201 — Patient created successfully.
{
"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
| Status | Meaning |
|---|---|
400 | 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 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 | 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 | 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 | Signals enrollment failed (signals_mint_failed). The patient create is rolled back; see Behaviour for retry details. |
Last updated on