List recent notifications
List recent notifications using Ovok’s Slim API.
| Method | Path |
|---|---|
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
| Name | Type | Required | Description |
|---|---|---|---|
count | integer | No | The maximum number of rows to return. Minimum 1, maximum 50, default 20. |
Behaviour
- Returns at most
countrows, newest first by event time. - Warm responses use the notification projection (
warmistrue,sourceis"redis"). Cold responses read current notifications from the FHIR server (warmisfalse,sourceis"fhirStore") and start loading the projection in the background, so a later call can be warm. - The FHIR search returns
activenotifications updated within the last year. totalcounts active notifications up to the configured result cap (1,000 by default). Counts from a cold read are estimates.locationNameis 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, useGET /v1/slim/notifications/recent/ooborGET /v1/slim/notifications/recent/alarms. - Only a cold read can be shed under load, with a 503 and a
Retry-Afterheader. 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"
}| Field | Type | Description |
|---|---|---|
recent | object[] | The notifications, newest first by event time. Each element is a row, described below. |
total | integer | The number of active notifications the source knows about, clamped to 1,000 (the list result cap). An estimate on a cold read. |
warm | boolean | true 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.
| Field | Type | Description |
|---|---|---|
recent[].commId | string | The 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[].patientId | string (uuid) | The resident's Patient id. Omitted when the notification has no resident. |
recent[].patientName | string | The 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[].deviceId | string | The device identifier stamped on the notification: usually the device's name or serial, for example Demo/100AA01. Omitted when unknown. |
recent[].deviceName | string | The device's display name. Omitted when unknown. |
recent[].locationId | string (uuid) | The room's Location id. Omitted when the notification has no room. |
recent[].locationName | string | The 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[].color | string | Display 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[].details | object | Measurement details. Always present; every field inside is omitted when unknown. |
recent[].details.threshold | number | The limit that was crossed. For out-of-bed, in seconds. |
recent[].details.value | number | The measured value that crossed the limit. For out-of-bed, a duration in seconds. |
recent[].details.level | string | Severity label: high or low for a limit breach, red, yellow or attention for an alarm. |
recent[].authoredOn | string (ISO 8601 date-time) | When the notification was created, in UTC. Falls back to its last update time. |
recent[].alertCount | integer | How many alerts the notification has absorbed (at least 1). Omitted when not recorded. |
recent[].occurrenceDateTime | string (ISO 8601 date-time) | When the latest event on the notification happened, in UTC. It advances while an episode continues. |
recent[].episodeEndedAt | string (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[].effectiveTimestamp | string (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[].latestObservationTimestamp | string (ISO 8601 date-time) | When the newest reading behind the notification was taken. Omitted on older notifications; fall back to effectiveTimestamp, then authoredOn. |
recent[].alarm | object | null | The sender's alarm, for deviceAlarm and attention notifications. null for every other type, and when the sender's alarm record is incomplete. |
recent[].alarm.episodeId | string | The 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.type | string | The sender's alarm type, for example DEVICE_ALARM. |
recent[].alarm.text | string | null | The sender's alarm text, or null when it sent none. |
recent[].noteCount | integer | null | Always null on this route: bells do not count notes. |
Errors
| Status | Meaning |
|---|---|
401 | Bearer token is missing, invalid or expired. |
403 | You 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. |
422 | A query parameter fails validation. |
503 | A 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. |
504 | The FHIR search on the fallback path timed out. |
Last updated on