Notifications

List out-of-bed notifications

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

MethodPath
GET/v1/slim/notifications/oob

Authentication · Access policies

Lists your project's out-of-bed notifications, filtered and paged. Signals evaluates out-of-bed; Ovok serves one row per episode from Signals. Medical notifications are not here; read GET /v1/slim/notifications/medical for those.

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, CommunicationRequest:search and Observation:read (admins and super admins skip this check). Scope: The caller's project (from the token). The project query parameter is accepted but ignored.

Request

Query parameters

NameTypeRequiredDescription
status"active" | "completed" | "cancelled" | "draft" | "on-hold" | "revoked" | "unknown" | "entered-in-error"Noactive lists new episodes and completed lists reviewed episodes. Omit it to list both. revoked lists episodes closed by hand. There is no all value.
patientstringNoOnly this resident's notifications. A Patient id, or Patient/{id}.
devicestringNoOnly this device's notifications. A Device id, Device/{id}, or the device's identifier value (for example Demo/100AA01). A Device id that does not exist returns an empty page, not an unfiltered one.
startDatestring (ISO 8601 date-time)NoInclusive lower bound on the episode's last firing time, a UTC instant ending in Z. Defaults to one year back for active episodes and 30 days back for reviewed episodes. When status is omitted, each half uses its own default.
endDatestring (ISO 8601 date-time)NoInclusive upper bound on the episode's last firing time, a UTC instant ending in Z. No default. Must not be before startDate.
pageintegerNoThe zero-based page number. Minimum 0, default 0.
countintegerNoThe page size. Minimum 1, maximum 100, default 25.
projectstringNoAccepted and ignored. The project always comes from the token.

Any other parameter, including type, is ignored.

Behaviour

  • The notification type is fixed to out-of-bed; there is no type parameter. Prefer this route over the deprecated GET /v1/slim/notifications?type=outOfBed.
  • active lists new episodes and completed lists reviewed episodes. With no status, the route merges both lists newest first; each row keeps its own status. A manually closed unacknowledged episode is revoked: it appears in neither list, so request status=revoked. An unacknowledged STALE episode stays active with episodeEndedAt set. There is no status=all.
  • One row per out-of-bed episode, not per reading: the resident's open episode is updated in place.
  • 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.
  • Sort order: newest first by event time (occurrenceDateTime, then authoredOn, then id).
  • patient takes a Patient id or Patient/{id}. device takes a Device id, Device/{id}, or the device's identifier value. A Device id that does not exist returns an empty page rather than an unfiltered one.
  • startDate and endDate bind to the episode's last firing time for every status. They are inclusive UTC instants; a startDate after endDate fails validation.
  • Paging: page starts at 0 and count is 1 to 100 (default 25). total is the sum of the matching lists, capped at 1,000; with no status, it is the combined active and completed count. truncated reports result-cap when rows were cut at 1,000.
  • noteCount is always null on this route; Signals owns out-of-bed episode notes.
  • The row id is the Signals episode id. Acknowledge it with PATCH /v1/slim/notifications/{id}/ack; episode notes use /v1/slim/notifications/oob/{id}/notes.
  • 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/oob?status=active&page=0&count=25' \
  -H "Authorization: Bearer ${OVOK_TOKEN}"

Successful response

200 — Out-of-bed notifications retrieved successfully.

{
  "total": 2,
  "page": 0,
  "count": 25,
  "truncated": null,
  "resources": [
    {
      "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": 1
    },
    {
      "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": 0
    }
  ]
}
FieldTypeDescription
totalintegerNumber of matching rows, capped at 1,000. When status is omitted, this is the sum of the active and completed lists before the cap.
pageintegerThe page number you asked for.
countintegerThe page size you asked for.
truncatedobject | nullnull when nothing was withheld. Otherwise the server stopped looking, and this says why.
truncated.reason"result-cap"More rows exist beyond the 1,000-result cap.
truncated.limitintegerThe cap or scan limit that was reached.
resourcesobject[]The page of rows, newest first by the episode's last firing time. Each element is a row, described below.

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
resources[].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.
resources[].patientIdstring (uuid)The resident's Patient id. Omitted when the notification has no resident.
resources[].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.
resources[].deviceIdstringThe device identifier stamped on the notification: usually the device's name or serial, for example Demo/100AA01. Omitted when unknown.
resources[].deviceNamestringThe device's display name. Omitted when unknown.
resources[].locationIdstring (uuid)The room's Location id. Omitted when the notification has no room.
resources[].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.
resources[].colorstringDisplay colour of the alert as a hex string, for example #E5254B. Omitted when absent.
resources[].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.
resources[].type"outOfBed"The notification type. Always outOfBed on this route.
resources[].status"active" | "completed" | "cancelled" | "on-hold" | "draft" | "revoked" | "entered-in-error" | "unknown"The notification's status. active until someone acknowledges it, then completed. The other values are standard FHIR request statuses.
resources[].detailsobjectMeasurement details. Always present; every field inside is omitted when unknown.
resources[].details.thresholdnumberThe limit that was crossed. For out-of-bed, in seconds.
resources[].details.valuenumberThe measured value that crossed the limit. For out-of-bed, a duration in seconds.
resources[].details.levelstringSeverity label: high or low for a limit breach, red, yellow or attention for an alarm.
resources[].authoredOnstring (ISO 8601 date-time)When the notification was created, in UTC. Falls back to its last update time.
resources[].alertCountintegerHow many alerts the notification has absorbed (at least 1). Omitted when not recorded.
resources[].occurrenceDateTimestring (ISO 8601 date-time)When the latest event on the notification happened, in UTC. It advances while an episode continues.
resources[].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.
resources[].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.
resources[].latestObservationTimestampstring (ISO 8601 date-time)When the newest reading behind the notification was taken. Omitted on older notifications; fall back to effectiveTimestamp, then authoredOn.
resources[].alarmobject | nullThe sender's alarm, for deviceAlarm and attention notifications. null for every other type, and when the sender's alarm record is incomplete.
resources[].alarm.episodeIdstringThe sender's own id for the alarm, so it can match an acknowledgement to its record.
resources[].alarm.severity"RED" | "YELLOW" | "ATTENTION"The severity as the sender coded it. ATTENTION is an attention press.
resources[].alarm.typestringThe sender's alarm type, for example DEVICE_ALARM.
resources[].alarm.textstring | nullThe sender's alarm text, or null when it sent none.
resources[].noteCountnullAlways null on this route.

Errors

StatusMeaning
401Bearer token is missing, invalid or expired.
403You are not a practitioner, admin or System Owner, you lack CommunicationRequest:read, CommunicationRequest:search or Observation:read, your session has no project, you cannot access the project, or the device filter names a Device you cannot read.
422A query parameter fails validation, for example a count outside 1 to 100, a negative page, a startDate or endDate that is not a UTC instant, or a startDate after endDate.
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