Patients

Create patient

Create patient using Ovok’s Slim API.

MethodPath
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

NameTypeRequiredDescription
projectIdstring (uuid)NoCreate 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.

NameTypeRequiredDescription
nameobject[]YesThe 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"YesKind of name.
name[].givenstring[]NoGiven names, in order. At least 1 entry when sent. Each entry is a non-empty string.
name[].familystringNoFamily name. Non-empty when sent.
gender"male" | "female" | "other" | "unknown"NoAdministrative gender.
birthDatestring (YYYY-MM-DD)NoDate of birth.
deviceIdstring (uuid) | string[]NoOne device id or a list of ids to assign the resident to. null means no device.
locationIdstring (uuid)NoRoom (location) to place the resident in.
organizationIdstring (uuid)NoZone to place the resident in. Send it with locationId or deviceId.
admissionDatestring (ISO 8601 date-time)NoAdmission time. Defaults to now. Must not be later than the start of the current day.

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). 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.

FieldTypeDescription
idstring (uuid)Patient id.
nameobject[]The resident's names. A name stored without a use is returned as official.
name[].use"official" | "nickname" | "maiden"Kind of name.
name[].givenstring[]Given names. Empty array when none.
name[].familystringFamily name. Empty string when none.
gender"male" | "female" | "other" | "unknown"Left out when not set.
birthDatestring (YYYY-MM-DD)Left out when not set.
deviceIdstring (uuid) | nullThe resident's device. null when the resident has no device. When there are several, the most recently updated one.
organizationIdstring (uuid)Zone of that device's room. Left out when there is none.
locationIdstring (uuid)Room of that device. Left out when there is none.
floorstringFloor of the room. Left out when not set.
roomstringRoom name or number. Left out when not set.
bedstringBed. Left out when not set.
residentState"active" | "discharged-recent" | "discharged" | "archived"Resident state.
admissionDatestringAdmission time as stored. Left out when not set.
dischargeDatestringDischarge time as stored. Left out when not set.

Errors

StatusMeaning
400the FHIR backend refuses the write.
401Bearer token is missing, invalid or expired.
403You 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.
409The 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.
422The 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"]).
503Signals enrollment failed (signals_mint_failed). The patient create is rolled back; see Behaviour for retry details.

Last updated on

On this page