Devices

Update device

Update device using Ovok’s Slim API.

MethodPath
PUT/v1/slim/device/:id

Authentication · Access policies

Updates a device's name and identifier, and assigns or unassigns its zone, location and resident.

Auth: bearer token. The caller must be a practitioner, an admin or a System Owner, and needs Device:update. Scope: the device must belong to the caller's project (from the token).

Request

Path parameters

NameTypeRequiredDescription
idstring (uuid)YesDevice id.

Body

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

NameTypeRequiredDescription
namestringYesDevice serial and user-friendly name. At least 1 character. A serial used by another customer is refused with 409.
thingsboardIdstringNoDevice identifier that telemetry is keyed by. At least 1 character. Omit to keep it.
organizationIdstring (uuid) | nullNoZone to assign. null unassigns. When the device has a room, this must match the room's zone. Omit to keep it.
locationIdstring (uuid) | nullNoLocation to assign. null unassigns. Omit to keep it.
patientIdstring (uuid) | nullNoResident to assign. null unassigns. Omit to keep it.

Behaviour

  • name is required. Renaming moves the device serial: readings sent under the old serial no longer reach it. Until the first reading under the new serial, the renamed device has no live values. Ovok keeps lastSeen; the live row id, device.identifier and /v1/slim/device/live/telemetry key become the new serial.
  • thingsboardId can be set once. A device that already has a different one refuses the change with 400.
  • For organizationId, locationId and patientId: omit the field to leave it unchanged, send null to unassign, or send a UUID to assign.
  • A device in a room takes the room's zone. If organizationId differs from that zone (the room in this request, or its current room when locationId is omitted), the request is refused with 422 and nothing changes. A device without a room, or in a room without a zone, can use any zone. A zone change applies only to the device.
  • Assigning a resident moves them: the resident is removed from every other device they hold. The resident who was on this device before loses it. Each resident who loses a device has their active out-of-bed episode closed in the same transaction.
  • All changes are written in one transaction. If any part fails, nothing is written.
  • Sending values the device already has is not an error, and writes nothing.
  • Resident assignment changes, renames, zone changes and room moves are recorded in the change history. A change of thingsboardId is not.
  • The response is the same as GET /v1/slim/device/{id} after the update.

Example

curl -X PUT 'https://api.sandbox.ovok.com/v1/slim/device/8c5e7a21-4b9d-4f36-a1c8-0d2e6b9f3a54' \
  -H "Authorization: Bearer ${OVOK_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{"name": "Demo/1000001", "patientId": null}'

Successful response

200 — The updated device.

{
  "id": "8c5e7a21-4b9d-4f36-a1c8-0d2e6b9f3a54",
  "name": "Demo/1000001",
  "status": "active",
  "statusReason": [],
  "thingsboardId": "Demo/1000001",
  "organizationId": "1e6b8d30-2c4f-4a95-8d7e-b0a2c4e6f918",
  "organizationName": "Zone A",
  "locationId": "5d2a9c64-7e1b-4830-b6f5-9a3c1e8d7b02",
  "locationName": "Room 101 Bed 1",
  "patientName": null,
  "floor": "1",
  "room": "101",
  "bed": "1"
}

The body is the device after the update, as GET /v1/slim/device/{id} returns it. The example shows the device after patientId was set to null.

FieldTypeDescription
idstring (uuid)Device id.
namestringDevice name. Empty string when it has none.
status"active" | "inactive" | "entered-in-error" | "unknown"Connection status. Left out when unknown.
statusReasonobject[]Why the platform marked the device, when it did. Empty array when nothing was recorded.
statusReason[].codestringReason code, such as no-assigned-resident. Stable. Render from this.
statusReason[].displaystring | nullA sentence for the code. null for a code that has none.
thingsboardIdstringDevice identifier that telemetry is keyed by. Left out when the device has none.
organizationIdstring (uuid)Zone id. Left out when there is none.
organizationNamestring | nullZone name.
locationIdstring (uuid)Location id. Left out when there is none.
locationNamestring | nullLocation name.
patientIdstring (uuid)Resident id. Left out when there is none.
patientNamestring | nullThe resident's full display name.
floorstringFloor code of the location. Left out when not set.
roomstringRoom code of the location. Left out when not set.
bedstringBed code of the location. Left out when not set.

Errors

StatusMeaning
400A zone, location or resident in the body does not exist, thingsboardId differs from the one the device already has, 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 Device:update, your session has no project, or the device is not in your project.
404No device with this id exists.
409You change patientId or locationId while your project is moving to another Signals tenant. Retry when the move is done.
409This device serial is in use by another customer. (path: ["name"]). This check runs before the zone validation.
422The body fails validation, another device in this project already uses the serial (including a DeviceID identifier equal to name), the zone does not match the room's zone (path: ["organizationId"]), or you assign a location to a discharged resident.

Last updated on

On this page