OVOK DOCS
Get startedOvokSignalsSDKsGuidesAPI referenceDeveloper resources
SlimSlim/Device

List live device rows

  • Sandbox: available
  • Staging: available
  • Production: unknown
GET
/v1/slim/device/live

Lists live device rows for the dashboard's monitoring views: each device with its resident, location, zone, current telemetry and alerts.

Auth: bearer token. The caller must be a practitioner, an admin or a System Owner, and needs search and read on Patient, Device, Location, Observation and Organization. Scope: the caller's project (from the token).

Behaviour

  • By default only devices with a resident assigned are returned. Set includeUnassigned=true to include devices without a resident.
  • organizationId takes a zone id, assigned or unassigned. A zone id also matches devices in its child zones.
  • deviceId restricts the result to one device, matched against the device identifier.
  • effectiveSleepStatus filters on the device's current sleep status.
  • search matches resident nickname and name, location name, zone name, and device name, identifier and serial. The resident, location and zone names match fuzzily; the device fields match only as a case-insensitive substring, so a full device name finds that device alone.
  • orderBy is ASC or DESC in any case, default ASC.
  • residentState is accepted but ignored.
  • A row's patient carries the resident's id, name, meta and extension only, not the whole FHIR Patient.
  • Telemetry is read fresh on every request. The device structure is cached and refreshed when you write through the Slim routes.
  • page is zero-based. count defaults to 20, maximum 100.
  • For polling only the telemetry and alerts, use GET /v1/slim/device/live/telemetry with the same query.
  • The route returns 503 when the server is at capacity for live reads or the device list cannot be built. Retry shortly.

Example

curl -X GET 'https://api.sandbox.ovok.com/v1/slim/device/live?page=0&count=20&sortBy=locationName&orderBy=ASC' \  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'

Authorization

bearer
headerAuthorizationBearer <JWT>

Query Parameters

page?string
Default"0"
count?string
Default"20"
sortBy?string
Default"locationName"
Value in"locationName""patientName""patientNickname""organizationName""effectiveHeartRate""effectiveRespiratoryRate""effectiveSleepStatus""admissionDate""dischargeDate"
orderBy?string
Default"ASC"
Value in"ASC""DESC"
search?string
Length1 <= length
deviceId?string

Restrict results to a single device (matched against the device identifier).

Length1 <= length
organizationId?|
effectiveSleepStatus?string
Value in"disconnected""connected""awake""away""asleep"
residentState?string
Value in"active""discharged-recent""discharged""archived"
includeUnassigned?string

Response Body

One page of live device rows.

application/json
  1. response
total*number
Range0 <= value
page*number
Range0 <= value
count*number
Range1 <= value
resources*array<>
Example Request
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/device/live'
Example Response
{  "total": 0,  "page": 0,  "count": 1,  "resources": [    {      "device": {        "resourceType": "Device",        "id": "string"      },      "patient": {        "resourceType": "Patient",        "id": "string",        "name": [          {            "use": "string",            "text": "string",            "family": "string",            "given": [              "string"            ],            "prefix": [              "string"            ],            "suffix": [              "string"            ]          }        ],        "meta": {},        "extension": [          {            "url": "string"          }        ]      },      "location": {        "id": "string",        "name": "string"      },      "organization": {        "id": "string",        "name": "string"      },      "telemetry": {        "active": {          "value": "string",          "ts": 0        },        "effectiveHeartRate": {          "value": "string",          "ts": 0        },        "effectiveRespiratoryRate": {          "value": "string",          "ts": 0        },        "effectiveSleepStatus": {          "value": "string",          "ts": 0        },        "lastMeasurementTime": {          "value": "string",          "ts": 0        },        "lastActivityTime": {          "value": "string",          "ts": 0        },        "name": {          "value": "string",          "ts": 0        },        "effectiveOxygenSaturation": {          "value": "string",          "ts": 0        },        "effectivePulseRate": {          "value": "string",          "ts": 0        },        "effectiveSystolicBloodPressure": {          "value": "string",          "ts": 0        },        "effectiveDiastolicBloodPressure": {          "value": "string",          "ts": 0        },        "effectiveHeartRateVariability": {          "value": "string",          "ts": 0        },        "effectivePerfusionIndex": {          "value": "string",          "ts": 0        },        "effectiveBodyTemperature": {          "value": "string",          "ts": 0        },        "roomTemperature": {          "value": "string",          "ts": 0        },        "humidity": {          "value": "string",          "ts": 0        },        "soundLevel": {          "value": "string",          "ts": 0        },        "infrared": {          "value": "string",          "ts": 0        },        "illuminance": {          "value": "string",          "ts": 0        },        "airQualityIndex": {          "value": "string",          "ts": 0        },        "tvoc": {          "value": "string",          "ts": 0        },        "eco2": {          "value": "string",          "ts": 0        }      },      "alerts": {        "heartRate": {          "alert": true,          "value": {            "property1": null,            "property2": null          },          "message": {            "property1": null,            "property2": null          },          "communicationRequestId": "string",          "observationId": "string",          "color": "string",          "state": "alert",          "updatedAt": "string"        },        "respiratoryRate": {          "alert": true,          "value": {            "property1": null,            "property2": null          },          "message": {            "property1": null,            "property2": null          },          "communicationRequestId": "string",          "observationId": "string",          "color": "string",          "state": "alert",          "updatedAt": "string"        },        "outOfBed": {          "outOfBed": true,          "communicationRequestId": "string",          "sinceTime": "string"        }      },      "calculatedFields": {        "deviceName": "string",        "statusReason": [          {            "code": "string",            "display": "string"          }        ],        "locationName": "string",        "patientName": "string",        "patientNickname": "string",        "organizationName": "string",        "residentState": "active",        "effectiveSleepStatus": "string",        "active": true,        "admissionDate": "string",        "dischargeDate": "string"      }    }  ]}

Create device POST

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). ## Behaviour - `name` is stored, trimmed, as the device's user-friendly name and as its official device identifier. - A `name` whose serial a device of your project already holds is refused with 422, in any spelling: spaces around it or its `/`, other case, with or without the manufacturer prefix ingest gives the serial (`Sleepiz/30QD24001`, `sleepiz/30qd24001` and `30QD24001` hold one serial). Ingest finds a device by its serial, so one serial belongs to one device. - A `name` whose serial a device of another customer already holds is refused with 409, in the same spellings. Ingest routes readings by serial, and cannot tell two customers' devices with one serial apart. - `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 is in the room's zone. An `organizationId` that differs from the zone of the device's room (the room you send, or the one it is in) answers 422 with `path: ["organizationId"]` and changes nothing: move the room to that zone, or the device to a room in it. A device with no room, or in a room with no zone, takes any zone. A zone change re-zones only the device, never its room, the room's other devices or a resident. - Assigning a resident moves them: the resident is removed from every other device they hold, and their active out-of-bed episode is closed. - Assigning a resident who is not active (`discharged`, `discharged-recent` or `archived`) is refused with 422 and nothing is created: reactivate them first. - 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 ```bash curl -X POST 'https://api.sandbox.ovok.com/v1/slim/device' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \ -H 'Content-Type: application/json' \ -d '{"name": "Sleepiz/3001000", "locationId": "c3499c27-2973-0a7f-807e-fb8676a92dcb"}' ```

List live telemetry and alerts by device GET

Returns the telemetry and alerts for one page of live devices, keyed by device. Use it to poll the values on a page you already loaded with `GET /v1/slim/device/live`. **Auth:** bearer token. The caller must be a practitioner, an admin or a System Owner, and needs `search` and `read` on `Patient`, `Device`, `Location`, `Observation` and `Organization`. **Scope:** the caller's project (from the token). ## Behaviour - Takes the same query parameters as `GET /v1/slim/device/live` and selects the same page of devices in the same order. - `telemetry` and `alerts` are keyed by the device identifier (for example `Sleepiz/3001000`), not by the Device resource id. - `alerts` has an entry for every device on the page. `telemetry` has an entry only for devices with telemetry. - Each telemetry entry carries the room readings `roomTemperature` (°C), `humidity` (%), `soundLevel` (dB), `infrared`, `illuminance` (lux), `airQualityIndex`, `tvoc` (ppb) and `eco2` (ppm) as `{ value, ts }`. They are `null` until the device reports one, and again when it has sent none for 30 minutes. They do not depend on whether the resident is in bed. - `total`, `page` and `count` describe the page, as on `/live`. - Telemetry is read fresh on every request. - The route returns 503 when the server is at capacity for live reads or the device list cannot be built. Retry shortly. ## Example ```bash curl -X GET 'https://api.sandbox.ovok.com/v1/slim/device/live/telemetry?page=0&count=20' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ```