Locations

Update location

Update location using Ovok’s Slim API.

MethodPath
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

NameTypeRequiredDescription
idstring (uuid)YesLocation id.

Body

The body is strict: a field that is not listed here fails validation.

NameTypeRequiredDescription
namestringYesLocation name. At least 1 character. Must be unique.
floorstringNoFloor code. Omit to keep the current one.
roomstringNoRoom code. Omit to keep the current one.
bedstringNoBed code. Omit to keep the current one.
organizationIdstring | nullNoZone to move the location to. null removes the zone. Omit to keep it.
deviceIdstring (uuid) | string[] | nullNoThe full set of devices at the location. null or [] detaches all devices. Omit to keep them.
patientIdstring (uuid)NoResident to place on the devices. Omit it to remove every resident from the devices.

Behaviour

  • name is 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. null or [] 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, when deviceId is 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 their patientId.
  • 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.

FieldTypeDescription
idstring (uuid)Location id.
namestringLocation name. Empty string when the location has none.
floorstringFloor code. Left out when not set.
roomstringRoom code. Left out when not set.
bedstringBed code. Left out when not set.
organizationIdstring (uuid)Zone id. Left out when the location has no zone.
organizationNamestringZone name. Left out when the location has no zone.
deviceIdstring[]Ids of every device at the location. Left out when there is none.
deviceNamestringAlphabetically first name among the devices at the location. Left out when there is none.
patientIdstring (uuid)Resident on the first device at the location that has one. Left out when there is none.
patientNamestringThat resident's name. Left out when there is none.

Errors

StatusMeaning
400A referenced zone, device or resident does not exist, or the FHIR backend refuses the write.
401Bearer token is missing, invalid or expired.
403You 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.
404No location with this id exists.
409Another 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.
422The 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

On this page