List recent medical notifications
List recent medical notifications using Ovok’s Slim API.
| Method | Path |
|---|---|
GET | /v1/slim/notifications/recent/medical |
Authentication · Access policies
Lists the newest open, unacknowledged medical notifications for your project. Use it for a medical notification bell. Medical episodes are decided by Signals; Ovok reads them from Signals and adds the resident context.
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 Patient:read, Device:read and Location:read (admins and super admins skip this check).
Scope: The caller's project (from the token), applied on both sides: Signals filters on the resident's project stamp, and Ovok checks each resolved resident against your project.
Request
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
count | integer | No | The maximum number of rows to return. Minimum 1, maximum 50, default 20. |
There is no status, acknowledged or cursor parameter: the filter is fixed by the server, and any other parameter is ignored.
Behaviour
- The filter is fixed by the server: open, unacknowledged episodes, newest first, at most
count(1 to 50, default 20). Every row'sepisode.statusisOPEN. An episode leaves the bell when it closes, whether or not anyone acknowledged it. Closed episodes stay inGET /v1/slim/notifications/medical, where they can still be acknowledged withPOST /v1/slim/notifications/medical/{episodeId}/ack. - An open episode is listed however many newer episodes have closed since it opened.
- Rows have the same shape as
GET /v1/slim/notifications/medical, includingepisode.firedBand.noteCountis alwaysnullhere: bells do not count notes. nextCursoris set when the page is full, so more open, unacknowledged episodes may exist. A bell can ignore it. This route takes nocursor; to page further, useGET /v1/slim/notifications/medicalwithstatus=OPENandacknowledged=false.- A resident who cannot be resolved into your project is left out, so a page can hold fewer than
countrows. - A resident with no Signals project stamp matches no project and does not appear.
- When the project's Signals tenant has episodic alerts switched off, the list is empty.
- Ovok waits up to 5 seconds for Signals. When Signals is unavailable, this bell can return
200with its last good page if that page is no more than 10 minutes old; it is cut tocountand has no stale-page marker. Rows can therefore be up to 10 minutes old during an outage. An acknowledgement removes the kept page. If no kept page is available, the bell returns503 signals_unavailable(signals_unavailable). The pagedGET /v1/slim/notifications/medicaldoes not use this fallback and returns 503. - A 503 with
signals_unavailablemeans Signals could not be reached and no kept page was available; retry afterretryAfterSec. Under load the read can also be shed with a 503 (live_reads_over_capacity). - Out-of-bed is not here; read
GET /v1/slim/notifications/recent/oob.
Example
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/notifications/recent/medical?count=20' \
-H "Authorization: Bearer ${OVOK_TOKEN}"Successful response
200 — The newest open, unacknowledged medical notifications.
{
"items": [
{
"episode": {
"id": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21",
"patientId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b22",
"code": "8867-4",
"system": "http://loinc.org",
"display": null,
"status": "OPEN",
"openedAt": "2026-10-09T07:40:12.000Z",
"closedAt": null,
"closeReason": null,
"lastSampleAt": "2026-10-09T08:05:12.000Z",
"durationMs": 1500000,
"observationCount": 6,
"firingCount": 6,
"minValue": 118,
"maxValue": 134,
"avgValue": 125.5,
"lastValue": 131,
"peakValue": 134,
"peakAt": "2026-10-09T07:55:12.000Z",
"lastFiringValue": 131,
"lastFiringAt": "2026-10-09T08:05:12.000Z",
"lastObservationId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b41",
"firedBand": {
"min": 50,
"max": 110,
"triggerVersion": 2
}
},
"carehub": {
"patientId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b22",
"patientName": "demo-resident",
"locationId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b23",
"locationName": "Room 101",
"room": "101",
"bed": "A",
"floor": "1",
"deviceId": "DEMO-0001",
"deviceMedplumId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b24",
"deviceName": "Demo Bed Sensor",
"organizationId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b25",
"organizationName": "Demo Care Home"
},
"acknowledgement": null,
"noteCount": null
}
],
"nextCursor": null
}| Field | Type | Description |
|---|---|---|
items | object[] | The open, unacknowledged episodes, newest first. Each element is a row, described below. |
nextCursor | string | null | An opaque cursor, set when more episodes may exist beyond count. null otherwise. This route cannot take it back; a bell can ignore it. |
Each row has three blocks (episode, carehub, acknowledgement) and a noteCount. A nullable field is always present, as null when it has no value.
| Field | Type | Description |
|---|---|---|
items[].episode | object | The Signals episode with its aggregates, passed through as Signals reported it. One episode is a run of readings outside the band. |
items[].episode.id | string | The episode id. Use it with GET /v1/slim/notifications/medical/{episodeId} and POST /v1/slim/notifications/medical/{episodeId}/ack. |
items[].episode.patientId | string | The resident's id at Signals. It equals carehub.patientId for residents created recently; use carehub.patientId with other Ovok routes. |
items[].episode.code | string | The vital the episode is about: a LOINC code such as 8867-4 (heart rate) or 9279-1 (respiratory rate), or PI for perfusion index. |
items[].episode.system | string | null | The code system of code, for example http://loinc.org. |
items[].episode.display | string | null | Display text for code, when Signals has one. |
items[].episode.status | "OPEN" | Always OPEN on this route: only open episodes are listed. |
items[].episode.openedAt | string (ISO 8601 date-time) | When the episode opened. |
items[].episode.closedAt | string (ISO 8601 date-time) | null | Always null on this route: the episode is open. |
items[].episode.closeReason | null | Always null on this route because the listed episodes are open. Closed episodes use RECOVERED, TIMEOUT, ACKNOWLEDGED, CROSSED, THRESHOLD_CHANGED, AWAY, STALE, or MANUAL; see How an episode behaves for their meanings. |
items[].episode.lastSampleAt | string (ISO 8601 date-time) | null | When the newest reading was folded in. On an open episode it shows how fresh the data is. |
items[].episode.durationMs | number | null | The episode length in milliseconds, as Signals reports it. |
items[].episode.observationCount | number | null | How many readings were folded into the episode. |
items[].episode.firingCount | number | null | How many of those readings were outside the band. |
items[].episode.minValue | number | null | The lowest reading in the episode. |
items[].episode.maxValue | number | null | The highest reading in the episode. |
items[].episode.avgValue | number | null | The average reading in the episode. |
items[].episode.lastValue | number | null | The newest reading folded in. On a recovered episode this is the recovery reading. |
items[].episode.peakValue | number | null | The peak reading of the episode. |
items[].episode.peakAt | string (ISO 8601 date-time) | null | When the peak reading was recorded. |
items[].episode.lastFiringValue | number | null | The last reading outside the band. This is the value a closed episode should headline. null for episodes stored before Signals tracked it; use peakValue then. |
items[].episode.lastFiringAt | string (ISO 8601 date-time) | null | When the last reading outside the band was recorded. |
items[].episode.lastObservationId | string | null | The id of the last evaluated reading folded in. On a recovered episode, the reading that closed it. Match it against values[].observationId on the detail route. |
items[].episode.firedBand | object | null | The band the episode was judged under: the band Signals recorded when it fired, or else the band rebuilt from its configuration history. It is not the resident's current band, so editing a threshold does not change past episodes. null when the band cannot be established; that never fails the read. |
items[].episode.firedBand.min | number | null | The lower limit, or null when the band has no lower limit. |
items[].episode.firedBand.max | number | null | The upper limit, or null when the band has no upper limit. |
items[].episode.firedBand.triggerVersion | number | null | The version of the resident's threshold rule the band belongs to. |
items[].carehub | object | The resident context Signals does not hold. Every field except carehub.patientId is null when the resident has no device assigned or the context could not be read. |
items[].carehub.patientId | string (uuid) | The resident's Ovok Patient.id. Use it for the patient filter and for other Slim routes. |
items[].carehub.patientName | string | null | The resident's label (their Resident ID): the Patient's nickname, otherwise its official given name, otherwise the first name on file. |
items[].carehub.locationId | string (uuid) | null | The room's Location id. |
items[].carehub.locationName | string | null | The room's name. |
items[].carehub.room | string | null | The room label, from the Location's type codings. |
items[].carehub.bed | string | null | The bed label, from the Location's type codings. |
items[].carehub.floor | string | null | The floor label, from the Location's type codings. |
items[].carehub.deviceId | string | null | The device serial that the Slim device routes use. |
items[].carehub.deviceMedplumId | string (uuid) | null | The device's FHIR Device.id. |
items[].carehub.deviceName | string | null | The device's display name. |
items[].carehub.organizationId | string (uuid) | null | The zone's id. A zone is the device's managing Organization. |
items[].carehub.organizationName | string | null | The zone's name. |
items[].acknowledgement | object | null | Always null on this route: only unacknowledged episodes are listed. |
items[].acknowledgement.acknowledgedAt | string (ISO 8601 date-time) | When the episode was acknowledged. |
items[].acknowledgement.acknowledgedBy | string | null | Ovok's client id at Signals. It is the same value for every acknowledgement made through Ovok. It is not a person: do not show it as a name. |
items[].acknowledgement.acknowledgedActor | object | null | Who acknowledged. null for acknowledgements made before Ovok sent an actor, and when the session had no profile. |
items[].acknowledgement.acknowledgedActor.reference | string | The caller's profile reference, normally Practitioner/{id}. Admin and service sessions can carry another profile type. |
items[].acknowledgement.acknowledgedActor.display | string | null | The caller's display name, captured when the episode was acknowledged. |
items[].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 Patient:read, Device:read or Location:read, your session has no project, or you cannot access the project. |
422 | A query parameter fails validation. |
503 | No kept page was available during a Signals outage (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. This is not an empty result: retry after the delay. |
Last updated on