Update location
Update location using Ovok’s Slim API.
| Method | Path |
|---|---|
PUT | /v1/slim/location/:id |
Authentication · Access policies
Updates a location: its name, floor, room, bed and zone, the devices at it, and the resident on those devices.
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 Location:update and Device:update (admins and super admins skip this check).
Scope: The location must belong to the caller's project (from the token). Devices and residents you attach must be in your project or one of its sub-projects. The zone must be in your project, a sub-project, or the parent project.
Request
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | Yes | Location id. |
Body
The body is strict: a field that is not listed here fails validation.
| Name | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Location name. At least 1 character. Must be unique. |
floor | string | No | Floor code. Omit to keep the current one. |
room | string | No | Room code. Omit to keep the current one. |
bed | string | No | Bed code. Omit to keep the current one. |
organizationId | string | null | No | Zone to move the location to. null removes the zone. Omit to keep it. |
deviceId | string (uuid) | string[] | null | No | The full set of devices at the location. null or [] detaches all devices. Omit to keep them. |
patientId | string (uuid) | No | Resident to place on the devices. Omit it to remove every resident from the devices. |
Behaviour
nameis required and must be unique among the locations your token can search, not counting this one.floor,room,bed: an omitted field keeps its current value. If the zone, floor, room or bed changes, the new combination must not match another location's.organizationId:- omitted: the zone is unchanged.
null: clears the zone from the room, its devices and its residents.- an id: sets the zone on the room and its devices. A resident removed from a device in the same save keeps their zone.
deviceId(one id or a list):- omitted: the devices at the location are unchanged.
- a list: it becomes the full set of devices at the location. Devices not in the list are detached; new ones are attached.
nullor[]detaches all devices. - Devices added to the room take its zone; devices taken out keep their current zone.
- Devices that hold a discharged resident cannot be attached.
patientId:- an id: that resident is assigned to the devices in
deviceId, or, whendeviceIdis omitted or empty, to the single device at the location. The resident is first removed from any other device. A resident already on a target device is replaced. A discharged resident is refused. - omitted: every resident is removed from every device at the location and every device in
deviceId. To keep the current resident, send theirpatientId.
- an id: that resident is assigned to the devices in
- A resident who loses a device has their active out-of-bed notification revoked in the same write, and the device's live telemetry state is cleared afterwards.
- Device use history is updated for every device whose resident changes.
- The write is atomic and takes a short write lock. A concurrent write to the same resources, or a device reassigned by someone else while this request ran, gets a 409.
- Each change to the name, floor, room, bed or zone adds an entry to the change history. A save that changes none of them adds none. Residents who move into a new zone, or lose a device, also get an entry in their own change history.
- The response is the location after the update, in the same shape as
GET /v1/slim/location/{id}.
Example
curl -X PUT 'https://api.sandbox.ovok.com/v1/slim/location/5d2a9c64-7e1b-4830-b6f5-9a3c1e8d7b02' \
-H "Authorization: Bearer ${OVOK_TOKEN}" \
-H 'Content-Type: application/json' \
-d '{
"name": "Room 201",
"floor": "2",
"room": "201",
"bed": "A",
"organizationId": "1e6b8d30-2c4f-4a95-8d7e-b0a2c4e6f918",
"deviceId": ["8c5e7a21-4b9d-4f36-a1c8-0d2e6b9f3a54"],
"patientId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21"
}'Successful response
200 — Location updated successfully.
{
"id": "5d2a9c64-7e1b-4830-b6f5-9a3c1e8d7b02",
"name": "Room 201",
"floor": "2",
"room": "201",
"bed": "A",
"organizationId": "1e6b8d30-2c4f-4a95-8d7e-b0a2c4e6f918",
"organizationName": "Zone A",
"patientId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21",
"patientName": "demo-resident",
"deviceId": ["8c5e7a21-4b9d-4f36-a1c8-0d2e6b9f3a54"],
"deviceName": "Demo/1000001"
}The body is the location after the update, as GET /v1/slim/location/{id} returns it.
| Field | Type | Description |
|---|---|---|
id | string (uuid) | Location id. |
name | string | Location name. Empty string when the location has none. |
floor | string | Floor code. Left out when not set. |
room | string | Room code. Left out when not set. |
bed | string | Bed code. Left out when not set. |
organizationId | string (uuid) | Zone id. Left out when the location has no zone. |
organizationName | string | Zone name. Left out when the location has no zone. |
deviceId | string[] | Ids of every device at the location. Left out when there is none. |
deviceName | string | Alphabetically first name among the devices at the location. Left out when there is none. |
patientId | string (uuid) | Resident on the first device at the location that has one. Left out when there is none. |
patientName | string | That resident's name. Left out when there is none. |
Errors
| Status | Meaning |
|---|---|
400 | A referenced zone, device or resident does not exist, or 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 Location:update or Device:update, the location is outside your project, or a referenced device that you can read is outside your project scope. |
404 | No location with this id exists. |
409 | Another location in the zone already has the same floor, room and bed (the body names it in existingLocationId and existingLocationName), another write holds one of the devices, or a device was reassigned while the request ran. |
422 | The body or id fails validation, another location has the same name, deviceId names a device the caller cannot read (Device not found: <id>[, <id>]; nothing is committed), a discharged resident would be placed here, or patientId without deviceId meets a room with no device or more than one. |
Last updated on