Notifications

List medical notifications

List medical notifications using Ovok’s Slim API.

MethodPath
GET/v1/slim/notifications/medical

Authentication · Access policies

Lists your project's medical notifications (heart rate, respiratory rate and other vital-sign alerts), newest first, one page at a time. Medical episodes are decided by Signals; Ovok reads them from Signals, adds the resident context, and never re-derives a clinical value.

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
status"OPEN" | "CLOSED"NoOnly episodes in this state. Both when omitted.
sincestring (ISO 8601 date-time)NoOnly episodes opened at or after this instant. A UTC instant ending in Z.
acknowledgedstringNotrue, 1 or yes (any case) for acknowledged episodes only. Any other value, such as false, for unacknowledged only. Both when omitted.
patientstringNoOnly this resident's episodes: an Ovok Patient.id, the carehub.patientId a row returns. Maximum 64 characters. It does not widen the project scope.
codesstringNoOnly these vitals: LOINC codes, comma separated, at most 32, no spaces, for example 8867-4,9279-1. PI is perfusion index. Signals applies the filter. Omit for every medical code.
limitintegerNoThe page size. Minimum 1, maximum 200, default 50.
cursorstringNoThe previous page's nextCursor, passed back unchanged. Opaque; maximum 500 characters.

Behaviour

  • One row per episode, not per reading: a run of readings outside the band is one episode. Its closeReason values are listed in How an episode behaves.
  • Each row has three blocks. episode is the Signals episode with its aggregates. carehub is the resident context Signals does not hold: resident, room and bed, device, zone. Its fields are null when the resident has no device assigned. acknowledgement is null until someone acknowledges the episode.
  • Use episode.id with GET /v1/slim/notifications/medical/{episodeId} to get the full value history.
  • episode.firedBand is the band the episode was judged under: the band Signals recorded when it fired, or else the band rebuilt from Signals' configuration history at the episode's trigger version. It is not the resident's current band, so editing a threshold does not change past rows. min and max are each nullable (a band can be one-sided). firedBand is null when the band cannot be established; that never fails the read.
  • Filters: status (OPEN or CLOSED, both when omitted), since (episodes opened at or after this ISO 8601 instant), acknowledged (true, 1 or yes for acknowledged only; any other value for unacknowledged only; both when omitted).
  • patient narrows the feed to one resident, by Ovok Patient.id (the carehub.patientId a row returns). It does not change the project scope. A resident who cannot be resolved, or who is in another project, answers 404 rather than an unfiltered page.
  • codes narrows the feed to these LOINC codes, comma separated, at most 32 (for example 8867-4,9279-1). Perfusion index is PI. Signals applies the filter. Out-of-bed is never in this feed. A malformed list fails validation.
  • Paging: limit is 1 to 200 (default 50). Pass the previous page's nextCursor as cursor. Page until nextCursor is null, not until a short page arrives: rows whose resident cannot be resolved into your project are dropped after Signals counted them. Treat the cursor as opaque.
  • noteCount counts the notes left on each episode. It is null for a row whose count could not be established.
  • 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 page is empty.
  • Out-of-bed is served by GET /v1/slim/notifications/oob.
  • Ovok waits up to 5 seconds for Signals. A 503 signals_unavailable (signals_unavailable) means Signals did not answer in time; it is not an empty result. Retry after retryAfterSec. Under load the read can also be shed with a 503 (live_reads_over_capacity).

Example

curl -X GET 'https://api.sandbox.ovok.com/v1/slim/notifications/medical?status=OPEN&codes=8867-4,9279-1&limit=50' \
  -H "Authorization: Bearer ${OVOK_TOKEN}"

Successful response

200 — A page of 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": 0
    }
  ],
  "nextCursor": "c2FtcGxlLWN1cnNvcg"
}
FieldTypeDescription
itemsobject[]The page of episodes, newest first. Each element is a row, described below.
nextCursorstring | nullAn opaque cursor for the next page, or null on the last page. Page until it is null, not until a short page arrives.

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" | "CLOSED"Whether the episode is still running.
items[].episode.openedAtstring (ISO 8601 date-time)When the episode opened.
items[].episode.closedAtstring (ISO 8601 date-time) | nullWhen it closed. null while it is open.
items[].episode.closeReason"RECOVERED" | "TIMEOUT" | "ACKNOWLEDGED" | "CROSSED" | "THRESHOLD_CHANGED" | "AWAY" | "STALE" | "MANUAL" | nullWhy it closed; null while open. See How an episode behaves for each meaning.
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 | nullnull until someone acknowledges the episode.
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 | nullThe number of notes on this episode. null when the count could not be established.

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.
404The patient filter names a resident who cannot be resolved or is not in your project.
422A query parameter fails validation, for example an unknown status, a since that is not a UTC instant, a codes list that is malformed or longer than 32, a limit outside 1 to 200, or a patient or cursor that is too long.
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. This is not an empty result: retry after the delay.

Last updated on

On this page