Devices
Update device
Update device using Ovok’s Slim API.
| Method | Path |
|---|---|
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
| Name | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | Yes | Device id. |
Body
The body is strict: a field that is not listed here fails validation.
| Name | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Device serial and user-friendly name. At least 1 character. A serial used by another customer is refused with 409. |
thingsboardId | string | No | Device identifier that telemetry is keyed by. At least 1 character. Omit to keep it. |
organizationId | string (uuid) | null | No | Zone to assign. null unassigns. When the device has a room, this must match the room's zone. Omit to keep it. |
locationId | string (uuid) | null | No | Location to assign. null unassigns. Omit to keep it. |
patientId | string (uuid) | null | No | Resident to assign. null unassigns. Omit to keep it. |
Behaviour
nameis 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 keepslastSeen; the live rowid,device.identifierand/v1/slim/device/live/telemetrykey become the new serial.thingsboardIdcan be set once. A device that already has a different one refuses the change with 400.- For
organizationId,locationIdandpatientId: omit the field to leave it unchanged, sendnullto unassign, or send a UUID to assign. - A device in a room takes the room's zone. If
organizationIddiffers from that zone (the room in this request, or its current room whenlocationIdis omitted), the request is refused with422and 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
thingsboardIdis 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.
| Field | Type | Description |
|---|---|---|
id | string (uuid) | Device id. |
name | string | Device name. Empty string when it has none. |
status | "active" | "inactive" | "entered-in-error" | "unknown" | Connection status. Left out when unknown. |
statusReason | object[] | Why the platform marked the device, when it did. Empty array when nothing was recorded. |
statusReason[].code | string | Reason code, such as no-assigned-resident. Stable. Render from this. |
statusReason[].display | string | null | A sentence for the code. null for a code that has none. |
thingsboardId | string | Device identifier that telemetry is keyed by. Left out when the device has none. |
organizationId | string (uuid) | Zone id. Left out when there is none. |
organizationName | string | null | Zone name. |
locationId | string (uuid) | Location id. Left out when there is none. |
locationName | string | null | Location name. |
patientId | string (uuid) | Resident id. Left out when there is none. |
patientName | string | null | The resident's full display name. |
floor | string | Floor code of the location. Left out when not set. |
room | string | Room code of the location. Left out when not set. |
bed | string | Bed code of the location. Left out when not set. |
Errors
| Status | Meaning |
|---|---|
400 | A 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. |
401 | Bearer token is missing, invalid or expired. |
403 | You 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. |
404 | No device with this id exists. |
409 | You change patientId or locationId while your project is moving to another Signals tenant. Retry when the move is done. |
409 | This device serial is in use by another customer. (path: ["name"]). This check runs before the zone validation. |
422 | The 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