Patients

Update patient

Update patient using Ovok’s Slim API.

MethodPath
PUT/v1/slim/patient/:id

Authentication · Access policies

Updates a resident (patient): names, gender, birth date, placement on devices, room and zone, and resident state (discharge or reactivation).

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:update, plus Device:update when the request changes which devices the resident is on (admins and super admins skip this check). Scope: The resident must belong to the caller's project (from the token). Devices, rooms and zones you reference must be in your project, its parent project, or one of its sub-projects.

Request

Path parameters

NameTypeRequiredDescription
idstring (uuid)YesPatient id.

Body

Fields that are not listed here, such as id, floor, room, bed and admissionDate, are ignored. A GET /v1/slim/patient/{id} response is accepted as is.

NameTypeRequiredDescription
nameobject[]YesReplaces all names. At least 1 entry. Must contain a nickname entry with a non-blank first given value.
name[].use"official" | "nickname" | "maiden"YesKind of name.
name[].givenstring[]NoGiven names, in order.
name[].familystringNoFamily name. "" is accepted.
gender"male" | "female" | "other" | "unknown" | ""NoAdministrative gender. Omit or send "" to clear.
birthDatestring (YYYY-MM-DD) | ""NoDate of birth. Omit or send "" to clear.
locationIdstring (uuid) | ""NoRoom to place the resident in. Omit or send "" to remove the resident from all devices.
deviceIdstring (uuid) | string[] | null | ""NoDevice ids to place the resident on. When locationId is set, this must be a non-empty id or list; null, "" or [] is refused. Omit or clear locationId to remove placement.
organizationIdstring (uuid) | ""NoZone to place the resident in. When omitted, the resident takes the zone of their device: the room's zone, otherwise the device's own zone.
residentState"active" | "discharged" | "discharged-recent" | "archived"Nodischarged discharges an active resident. active reactivates a discharged one. Other values change nothing.
dischargeDatestringNoDischarge time, stored as sent. Use ISO 8601. Defaults to now when discharging.

Behaviour

The body is a full replacement of the editable fields, designed so that the result of GET /v1/slim/patient/{id} can be sent back unchanged. Fields the update does not declare, such as id, floor or admissionDate, are ignored.

  • name replaces all of the resident's names. It must contain a nickname entry with a non-blank first given value. If the nickname changes, it must be unique in the project.
  • Ovok stores name[].given[] and name[].family after trimming whitespace.
  • gender and birthDate are replaced. Omitting them, or sending "", clears them.
  • Placement depends on locationId:
    • locationId omitted or "": the resident is removed from all of their devices, and deviceId and organizationId are ignored. Send the current locationId to keep the placement.
    • locationId with deviceId: the resident is placed on those devices, and the devices move to the room. The resident leaves any other device. A resident already on one of those devices is replaced.
    • locationId without deviceId: the resident is placed on the room's device. The room must have exactly one device.
    • organizationId, when it differs from the current zone, moves the resident's devices, with their rooms and residents, into that zone.
    • A resident cannot be saved on devices from different zones (422, path: ["deviceId"]), unless the assignment already exactly matches those zones.
    • 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.
  • residentState:
    • discharged on an active resident: the resident is tagged discharged, dischargeDate is stored (default: now), the EpisodeOfCare is finished, and the resident is removed from all devices. locationId must be omitted or "".
    • discharged on a resident already discharged: only a different dischargeDate has an effect; it corrects the stored date.
    • active on a discharged resident: the resident is reactivated, the latest EpisodeOfCare is reopened and dischargeDate is removed.
    • Other values, or the current state, change nothing.
  • Any resident who loses a device in this request has their active out-of-bed notification revoked in the same write, and the device's live telemetry state is cleared afterwards.
  • Archived residents cannot be updated.
  • The write is atomic and takes a short write lock on the resident, the devices and, on a rename, the new Resident ID.
  • Change-history entries are added for each changed field and assignment.
  • The response is the resident after the update, in the same shape as GET /v1/slim/patient/{id}.

Example

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

Successful response

200 — Patient updated successfully.

{
  "id": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21",
  "name": [
    { "use": "nickname", "given": ["demo-resident"], "family": "" }
  ],
  "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-01T08:00:00.000Z"
}

The body is the resident after the update, 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:update (or Device:update when the device assignment changes), the patient is outside your project, or a referenced device, location or zone does not exist or is outside your project, its parent or its sub-projects.
404No patient with this id exists.
409The project is moving to another Signals tenant, another write holds the patient, a device or the new Resident ID, or a device was reassigned while the request ran. Retry.
422The body or id fails validation, the body has no Resident ID, the new Resident ID is already in use, the patient is archived, a discharge also sets locationId, a discharged resident is placed in a room, locationId is set with an empty deviceId (path: ["deviceId"]), the devices belong to different zones (path: ["deviceId"]), or locationId without deviceId names a room with no device or more than one.

Last updated on

On this page