Skip to main content

Create patient

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.

Behaviour​

  • name must contain an entry with use: "nickname" and a non-blank first given value. This is the Resident ID.
  • 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.
  • 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". 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": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21",
    "locationId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21",
    "organizationId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21"
  }'

Successful response​

201 — Patient created successfully.

Errors​

StatusMeaning
400Medplum 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, or locationId without deviceId names a room with no device or more than one.
503Signals enrollment failed (signals_mint_failed). The patient create is rolled back; see Behaviour for retry details.