Notifications

List recent notifications

List recent notifications using Ovok’s Slim API.

MethodPath
GET/v1/slim/notifications/recent

Authentication · Access policies

Lists the newest active notifications stored as CommunicationRequests for your project, of every type (such as out-of-bed, device alarms and attention presses). Use it for a notification bell. For filtered or paged history, use the out-of-bed and alarm feeds.

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

  • Returns at most count rows, newest first by event time.
  • Warm responses use the notification projection (warm is true, source is "redis"). Cold responses read current notifications from the FHIR server (warm is false, source is "fhirStore") and start loading the projection in the background, so a later call can be warm.
  • The FHIR search returns active notifications updated within the last year.
  • total counts active notifications up to the configured result cap (1,000 by default). Counts from a cold read are estimates.
  • 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.
  • Rows whose notification type cannot be resolved are left out.
  • Medical notifications (heart rate, respiratory rate and other vitals) are decided by Signals and served by GET /v1/slim/notifications/recent/medical. To show one type only, use GET /v1/slim/notifications/recent/oob or GET /v1/slim/notifications/recent/alarms.
  • Only a cold read can be shed under load, with a 503 and a Retry-After header. A warm read is never shed.

Example

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

Successful response

200 — Recent notifications retrieved successfully.

{
  "recent": [
    {
      "commId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b31",
      "patientId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b62",
      "patientName": "demo-resident-2",
      "deviceId": "Demo/200BB02",
      "deviceName": "Demo/200BB02",
      "locationId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b63",
      "locationName": "Room 102",
      "color": "#F5A524",
      "type": "deviceAlarm",
      "status": "active",
      "details": {
        "level": "yellow"
      },
      "authoredOn": "2026-10-09T02:20:00.000Z",
      "alertCount": 1,
      "occurrenceDateTime": "2026-10-09T02:20:00.000Z",
      "effectiveTimestamp": "2026-10-09T02:20:00.000Z",
      "latestObservationTimestamp": "2026-10-09T02:20:00.000Z",
      "alarm": {
        "episodeId": "evt_2041",
        "severity": "YELLOW",
        "type": "DEVICE_ALARM",
        "text": "Check sensor"
      },
      "noteCount": null
    },
    {
      "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
    }
  ],
  "total": 2,
  "warm": true,
  "source": "redis"
}
FieldTypeDescription
recentobject[]The notifications, newest first by event time. Each element is a row, described below.
totalintegerThe number of active notifications the source knows about, clamped to 1,000 (the list result cap). An estimate on a cold read.
warmbooleantrue when the warm projection served the request, false for a cold read.
source"redis" | "fhirStore""redis" when the warm projection served the request, "fhirStore" when the rows were read from the FHIR server.

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 CommunicationRequest id, or for an out-of-bed row the Signals episode id. Use it to acknowledge the notification with PATCH /v1/slim/notifications/{id}/ack.
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" | "deviceAlarm" | "attention" | "hr" | "br"The notification type. outOfBed is a bed exit. deviceAlarm and attention are alarms and attention presses decided by the sending system. hr and br are legacy types: new heart rate and respiratory rate alerts are medical notifications, served by the medical routes.
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[].noteCountinteger | nullAlways null on this route: bells do not count 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.
503A cold read was shed because the server is at capacity. The body carries error set to live_reads_over_capacity and retryAfterSec, and the Retry-After header carries the same delay in seconds. Retry after it.
504The FHIR search on the fallback path timed out.

Last updated on

On this page