Devices

Create device

Create device using Ovok’s Slim API.

MethodPath
POST/v1/slim/device

Authentication · Access policies

Creates a device in your project and, optionally, assigns it to a zone, a location and a resident in the same write.

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

Request

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. Unique within the project; another customer's serial is refused with 409.
thingsboardIdstringNoDevice identifier that telemetry is keyed by. At least 1 character. Default: a random UUID.
organizationIdstring (uuid)NoZone to assign. If locationId names a room with a zone, this must be that zone.
locationIdstring (uuid)NoLocation to assign the device to.
patientIdstring (uuid)NoResident to assign to the device.

Behaviour

  • name is stored as the device's user-friendly name and as its official device identifier (the serial). A serial already used by another customer is refused with 409; this check runs before the room-zone check.
  • thingsboardId is stored as a second identifier. When you omit it, Ovok generates a random UUID for it.
  • organizationId, locationId and patientId are optional. Each one you send is assigned in the same transaction as the create. If any part fails, nothing is written.
  • A device in a room takes the room's zone. If organizationId differs from that zone, the request is refused with 422 and nothing is created. 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, and their active out-of-bed episode is closed.
  • The device starts with status active.
  • The create is recorded in the change history.
  • The response is the same as GET /v1/slim/device/{id} for the new device.

Example

curl -X POST 'https://api.sandbox.ovok.com/v1/slim/device' \
  -H "Authorization: Bearer ${OVOK_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{"name": "Demo/1000001", "locationId": "5d2a9c64-7e1b-4830-b6f5-9a3c1e8d7b02"}'

Successful response

201 — The created 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",
  "patientId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21",
  "patientName": "demo-resident",
  "floor": "1",
  "room": "101",
  "bed": "1"
}

The body is the new device, as GET /v1/slim/device/{id} returns it.

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, or the FHIR backend refuses the write.
401Bearer token is missing, invalid or expired.
403You are not a practitioner, admin or System Owner, or you lack Device:create.
409This device serial is in use by another customer. (path: ["name"]).
422The body fails validation, a 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 send locationId and patientId for a discharged resident.

Last updated on

On this page