Notifications

List recent out-of-bed notifications

List recent out-of-bed notifications using Ovok’s Slim API.

MethodPath
GET/v1/slim/notifications/recent/oob

Authentication · Access policies

Lists the newest active out-of-bed notifications for your project. Use it for an out-of-bed notification bell.

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 CommunicationRequest:read and CommunicationRequest:search (admins and super admins skip this check). Scope: The caller's project (from the token).

Request

Query parameters

NameTypeRequiredDescription
countintegerNoThe maximum number of rows to return. Minimum 1, maximum 50, default 20.

Behaviour

  • Out-of-bed is evaluated by Signals; Ovok serves one row per episode from Signals. Medical notifications are not here: read GET /v1/slim/notifications/recent/medical for those, so one event is never counted by both bells.
  • Returns at most count rows, newest first by event time.
  • Rows come from Signals episodes. The response has warm: true and source: "signals".
  • locationName is the room's current name, so a renamed room shows its new name on every row. If the caller cannot read the Location, or the lookup takes more than 2 seconds, a row keeps the name it was raised with.
  • total counts active out-of-bed episodes, capped at 1,000.
  • The row id is the Signals episode id. Use it with PATCH /v1/slim/notifications/{id}/ack; episode notes use /v1/slim/notifications/oob/{id}/notes.
  • An episode that has ended but has not been acknowledged stays active, and so stays in this bell, until someone acknowledges it with PATCH /v1/slim/notifications/{id}/ack. Its episodeEndedAt is set.
  • One in-bed reading ends an absence and clears its acknowledgement silence. The next absent reading starts a new absence with its own start and limit, whether or not the previous one was acknowledged. See How an episode behaves.
  • Signals reads wait up to 5 seconds. If Signals does not answer, the route returns 503 signals_unavailable (signals_unavailable) with retryAfterSec and Retry-After. The server can also shed a read with 503 live_reads_over_capacity (live_reads_over_capacity).

Example

curl -X GET 'https://api.sandbox.ovok.com/v1/slim/notifications/recent/oob?count=20' \
  -H "Authorization: Bearer ${OVOK_TOKEN}"

Successful response

200 — Recent out-of-bed notifications retrieved successfully.

{
  "recent": [
    {
      "commId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b11",
      "patientId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b12",
      "patientName": "demo-resident",
      "deviceId": "Demo/100AA01",
      "deviceName": "Demo/100AA01",
      "locationId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b13",
      "locationName": "Room 101",
      "color": "#E5254B",
      "trigger": "above",
      "type": "outOfBed",
      "status": "active",
      "details": {
        "threshold": 1800,
        "value": 1925,
        "level": "high"
      },
      "authoredOn": "2026-10-09T01:12:00.000Z",
      "alertCount": 4,
      "occurrenceDateTime": "2026-10-09T02:18:00.000Z",
      "effectiveTimestamp": "2026-10-09T01:12:00.000Z",
      "latestObservationTimestamp": "2026-10-09T02:18:00.000Z",
      "alarm": null,
      "noteCount": null
    },
    {
      "commId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b14",
      "patientId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b12",
      "patientName": "demo-resident",
      "deviceId": "Demo/100AA01",
      "deviceName": "Demo/100AA01",
      "locationId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b13",
      "locationName": "Room 101",
      "color": "#E5254B",
      "trigger": "above",
      "type": "outOfBed",
      "status": "active",
      "details": {
        "threshold": 1800,
        "value": 2410,
        "level": "high"
      },
      "authoredOn": "2026-10-08T22:05:00.000Z",
      "alertCount": 7,
      "occurrenceDateTime": "2026-10-08T22:50:00.000Z",
      "episodeEndedAt": "2026-10-08T22:58:00.000Z",
      "effectiveTimestamp": "2026-10-08T22:05:00.000Z",
      "latestObservationTimestamp": "2026-10-08T22:50:00.000Z",
      "alarm": null,
      "noteCount": null
    }
  ],
  "total": 2,
  "warm": true,
  "source": "signals"
}
FieldTypeDescription
recentobject[]The notifications, newest first by event time. Each element is a row, described below.
totalintegerThe number of active out-of-bed episodes counted, clamped to 1,000.
warmtrueAlways true on this route.
source"signals"Always signals: the rows come from Signals episodes.

Each row is one notification. A field described as omitted is left out of the JSON when it has no value; it is not sent as null. details, alarm and noteCount are always present.

FieldTypeDescription
recent[].commIdstringThe out-of-bed episode's Signals id. Use it to acknowledge the notification with PATCH /v1/slim/notifications/{id}/ack and for /v1/slim/notifications/oob/{id}/notes.
recent[].patientIdstring (uuid)The resident's Patient id. Omitted when the notification has no resident.
recent[].patientNamestringThe resident's label (their Resident ID): the Patient's nickname, otherwise its official given name, otherwise the name stored on the notification. Omitted when no usable name is available.
recent[].deviceIdstringThe device identifier stamped on the notification: usually the device's name or serial, for example Demo/100AA01. Omitted when unknown.
recent[].deviceNamestringThe device's display name. Omitted when unknown.
recent[].locationIdstring (uuid)The room's Location id. Omitted when the notification has no room.
recent[].locationNamestringThe room's current name, read from the Location. A row keeps the name it was raised with when the Location cannot be read. Omitted when no name is available; it is never a raw id.
recent[].colorstringDisplay colour of the alert as a hex string, for example #E5254B. Omitted when absent.
recent[].trigger"above" | "below"Whether the value went above the upper limit or below the lower limit. Omitted when the notification has no direction, such as an alarm.
recent[].type"outOfBed"The notification type. Always outOfBed on this route.
recent[].status"active"Always active on this route: only active notifications are listed.
recent[].detailsobjectMeasurement details. Always present; every field inside is omitted when unknown.
recent[].details.thresholdnumberThe limit that was crossed. For out-of-bed, in seconds.
recent[].details.valuenumberThe measured value that crossed the limit. For out-of-bed, a duration in seconds.
recent[].details.levelstringSeverity label: high or low for a limit breach, red, yellow or attention for an alarm.
recent[].authoredOnstring (ISO 8601 date-time)When the notification was created, in UTC. Falls back to its last update time.
recent[].alertCountintegerHow many alerts the notification has absorbed (at least 1). Omitted when not recorded.
recent[].occurrenceDateTimestring (ISO 8601 date-time)When the latest event on the notification happened, in UTC. It advances while an episode continues.
recent[].episodeEndedAtstring (ISO 8601 date-time)Set when an out-of-bed episode has ended. The notification stays active until someone acknowledges it. Omitted while the episode runs and on other types.
recent[].effectiveTimestampstring (ISO 8601 date-time)The stable start of the episode: for out-of-bed, the moment the resident left the bed. It does not change as occurrenceDateTime advances. Omitted on older notifications; fall back to authoredOn.
recent[].latestObservationTimestampstring (ISO 8601 date-time)When the newest reading behind the notification was taken. Omitted on older notifications; fall back to effectiveTimestamp, then authoredOn.
recent[].alarmobject | nullThe sender's alarm, for deviceAlarm and attention notifications. null for every other type, and when the sender's alarm record is incomplete.
recent[].alarm.episodeIdstringThe sender's own id for the alarm, so it can match an acknowledgement to its record.
recent[].alarm.severity"RED" | "YELLOW" | "ATTENTION"The severity as the sender coded it. ATTENTION is an attention press.
recent[].alarm.typestringThe sender's alarm type, for example DEVICE_ALARM.
recent[].alarm.textstring | nullThe sender's alarm text, or null when it sent none.
recent[].noteCountnullAlways null on this route; Signals owns the episode notes.

Errors

StatusMeaning
401Bearer token is missing, invalid or expired.
403You are not a practitioner, admin or System Owner, you lack CommunicationRequest:read or CommunicationRequest:search, your session has no project, or you cannot access the project.
422A query parameter fails validation.
503Signals did not answer within 5 seconds (error: "signals_unavailable" (signals_unavailable)), or the server shed the read (error: "live_reads_over_capacity" (live_reads_over_capacity)). The body carries retryAfterSec and the Retry-After header carries the same delay in seconds. Retry after it.

Last updated on

On this page