Notifications

List recent medical notifications

List recent medical notifications using Ovok’s Slim API.

MethodPath
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

NameTypeRequiredDescription
countintegerNoThe 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's episode.status is OPEN. An episode leaves the bell when it closes, whether or not anyone acknowledged it. Closed episodes stay in GET /v1/slim/notifications/medical, where they can still be acknowledged with POST /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, including episode.firedBand. noteCount is always null here: bells do not count notes.
  • nextCursor is set when the page is full, so more open, unacknowledged episodes may exist. A bell can ignore it. This route takes no cursor; to page further, use GET /v1/slim/notifications/medical with status=OPEN and acknowledged=false.
  • A resident who cannot be resolved into your project is left out, so a page can hold fewer than count rows.
  • 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 200 with its last good page if that page is no more than 10 minutes old; it is cut to count and 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 returns 503 signals_unavailable (signals_unavailable). The paged GET /v1/slim/notifications/medical does not use this fallback and returns 503.
  • A 503 with signals_unavailable means Signals could not be reached and no kept page was available; retry after retryAfterSec. 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
}
FieldTypeDescription
itemsobject[]The open, unacknowledged episodes, newest first. Each element is a row, described below.
nextCursorstring | nullAn 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.

FieldTypeDescription
items[].episodeobjectThe Signals episode with its aggregates, passed through as Signals reported it. One episode is a run of readings outside the band.
items[].episode.idstringThe episode id. Use it with GET /v1/slim/notifications/medical/{episodeId} and POST /v1/slim/notifications/medical/{episodeId}/ack.
items[].episode.patientIdstringThe resident's id at Signals. It equals carehub.patientId for residents created recently; use carehub.patientId with other Ovok routes.
items[].episode.codestringThe 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.systemstring | nullThe code system of code, for example http://loinc.org.
items[].episode.displaystring | nullDisplay text for code, when Signals has one.
items[].episode.status"OPEN"Always OPEN on this route: only open episodes are listed.
items[].episode.openedAtstring (ISO 8601 date-time)When the episode opened.
items[].episode.closedAtstring (ISO 8601 date-time) | nullAlways null on this route: the episode is open.
items[].episode.closeReasonnullAlways 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.lastSampleAtstring (ISO 8601 date-time) | nullWhen the newest reading was folded in. On an open episode it shows how fresh the data is.
items[].episode.durationMsnumber | nullThe episode length in milliseconds, as Signals reports it.
items[].episode.observationCountnumber | nullHow many readings were folded into the episode.
items[].episode.firingCountnumber | nullHow many of those readings were outside the band.
items[].episode.minValuenumber | nullThe lowest reading in the episode.
items[].episode.maxValuenumber | nullThe highest reading in the episode.
items[].episode.avgValuenumber | nullThe average reading in the episode.
items[].episode.lastValuenumber | nullThe newest reading folded in. On a recovered episode this is the recovery reading.
items[].episode.peakValuenumber | nullThe peak reading of the episode.
items[].episode.peakAtstring (ISO 8601 date-time) | nullWhen the peak reading was recorded.
items[].episode.lastFiringValuenumber | nullThe 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.lastFiringAtstring (ISO 8601 date-time) | nullWhen the last reading outside the band was recorded.
items[].episode.lastObservationIdstring | nullThe 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.firedBandobject | nullThe 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.minnumber | nullThe lower limit, or null when the band has no lower limit.
items[].episode.firedBand.maxnumber | nullThe upper limit, or null when the band has no upper limit.
items[].episode.firedBand.triggerVersionnumber | nullThe version of the resident's threshold rule the band belongs to.
items[].carehubobjectThe 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.patientIdstring (uuid)The resident's Ovok Patient.id. Use it for the patient filter and for other Slim routes.
items[].carehub.patientNamestring | nullThe resident's label (their Resident ID): the Patient's nickname, otherwise its official given name, otherwise the first name on file.
items[].carehub.locationIdstring (uuid) | nullThe room's Location id.
items[].carehub.locationNamestring | nullThe room's name.
items[].carehub.roomstring | nullThe room label, from the Location's type codings.
items[].carehub.bedstring | nullThe bed label, from the Location's type codings.
items[].carehub.floorstring | nullThe floor label, from the Location's type codings.
items[].carehub.deviceIdstring | nullThe device serial that the Slim device routes use.
items[].carehub.deviceMedplumIdstring (uuid) | nullThe device's FHIR Device.id.
items[].carehub.deviceNamestring | nullThe device's display name.
items[].carehub.organizationIdstring (uuid) | nullThe zone's id. A zone is the device's managing Organization.
items[].carehub.organizationNamestring | nullThe zone's name.
items[].acknowledgementobject | nullAlways null on this route: only unacknowledged episodes are listed.
items[].acknowledgement.acknowledgedAtstring (ISO 8601 date-time)When the episode was acknowledged.
items[].acknowledgement.acknowledgedBystring | nullOvok'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.acknowledgedActorobject | nullWho acknowledged. null for acknowledgements made before Ovok sent an actor, and when the session had no profile.
items[].acknowledgement.acknowledgedActor.referencestringThe caller's profile reference, normally Practitioner/{id}. Admin and service sessions can carry another profile type.
items[].acknowledgement.acknowledgedActor.displaystring | nullThe caller's display name, captured when the episode was acknowledged.
items[].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 Patient:read, Device:read or Location:read, your session has no project, or you cannot access the project.
422A query parameter fails validation.
503No 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

On this page