Notifications

Get medical notification

Get medical notification using Ovok’s Slim API.

MethodPath
GET/v1/slim/notifications/medical/:episodeId

Authentication · Access policies

Returns one medical notification with its counted readings, addressed by the episode.id a feed row carries. Signals decides medical alerts and provides the episode.

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 matches it against the resident's project stamp, and Ovok checks the resolved resident against your project.

Request

Path parameters

NameTypeRequiredDescription
episodeIdstringYesThe Signals episode id: the episode.id a feed row carries. Not checked for format here; an id that does not exist answers 404.

Behaviour

  • Ovok waits up to 5 seconds for Signals. A 503 signals_unavailable (signals_unavailable) is not an empty result; retry after retryAfterSec.
  • episode is the Signals episode as Signals returned it: status, open and close times, close reason, aggregates, and values. The values list contains only readings the episode counted: each firing reading and the reading that recovered it. It omits history rows (batch-data, statistics, and presence-batch), non-readings (including 0, -1, missing values and values at or below 0), and the absent reading that closed an AWAY episode. Episodes stored before migration 60 list readings as they did before. Clients should not render a "0 bpm" or "No value" line. Check episode.truncated: a long episode returns up to 999 counted readings and sets it to true.
  • carehub adds the resident context: resident, room and bed, device and zone. Its fields are null when the resident has no device assigned.
  • acknowledgement is null until someone acknowledges the episode.
  • episode.firedBand is the band the episode was judged under, as described on GET /v1/slim/notifications/medical. It is null when it cannot be established.
  • noteCount is the number of notes on the episode, or null when the count could not be established.
  • An episode in another project answers 404, the same as one that does not exist. A 404 is never caused by Signals being down.
  • A 503 with signals_unavailable means Signals could not be reached; retry after retryAfterSec.

Example

curl -X GET 'https://api.sandbox.ovok.com/v1/slim/notifications/medical/3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21' \
  -H "Authorization: Bearer ${OVOK_TOKEN}"

Successful response

200 — The episode and its resident context.

{
  "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
    },
    "values": [
      {
        "observationId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b42",
        "valueNumber": 118,
        "valueString": null,
        "valueUnit": "beats/min",
        "note": null,
        "observedAt": null,
        "recordedAt": "2026-10-09T07:40:12.000Z"
      },
      {
        "observationId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b43",
        "valueNumber": 134,
        "valueString": null,
        "valueUnit": "beats/min",
        "note": null,
        "observedAt": "2026-10-09T07:55:12.000Z",
        "recordedAt": "2026-10-09T07:55:13.000Z"
      },
      {
        "observationId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b41",
        "valueNumber": 131,
        "valueString": null,
        "valueUnit": "beats/min",
        "note": null,
        "observedAt": "2026-10-09T08:05:12.000Z",
        "recordedAt": "2026-10-09T08:05:13.000Z"
      }
    ],
    "truncated": false
  },
  "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
}

The detail has the same blocks as a feed row, and episode also carries the readings.

The response has three blocks (episode, carehub, acknowledgement) and a noteCount. A nullable field is always present, as null when it has no value.

FieldTypeDescription
episodeobjectThe Signals episode with its aggregates, passed through as Signals reported it. One episode is a run of readings outside the band.
episode.idstringThe episode id. Use it with GET /v1/slim/notifications/medical/{episodeId} and POST /v1/slim/notifications/medical/{episodeId}/ack.
episode.patientIdstringThe resident's id at Signals. It equals carehub.patientId for residents created recently; use carehub.patientId with other Ovok routes.
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.
episode.systemstring | nullThe code system of code, for example http://loinc.org.
episode.displaystring | nullDisplay text for code, when Signals has one.
episode.status"OPEN" | "CLOSED"Whether the episode is still running.
episode.openedAtstring (ISO 8601 date-time)When the episode opened.
episode.closedAtstring (ISO 8601 date-time) | nullWhen it closed. null while it is open.
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.
episode.lastSampleAtstring (ISO 8601 date-time) | nullWhen the newest reading was folded in. On an open episode it shows how fresh the data is.
episode.durationMsnumber | nullThe episode length in milliseconds, as Signals reports it.
episode.observationCountnumber | nullHow many readings were folded into the episode.
episode.firingCountnumber | nullHow many of those readings were outside the band.
episode.minValuenumber | nullThe lowest reading in the episode.
episode.maxValuenumber | nullThe highest reading in the episode.
episode.avgValuenumber | nullThe average reading in the episode.
episode.lastValuenumber | nullThe newest reading folded in. On a recovered episode this is the recovery reading.
episode.peakValuenumber | nullThe peak reading of the episode.
episode.peakAtstring (ISO 8601 date-time) | nullWhen the peak reading was recorded.
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.
episode.lastFiringAtstring (ISO 8601 date-time) | nullWhen the last reading outside the band was recorded.
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.
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.
episode.firedBand.minnumber | nullThe lower limit, or null when the band has no lower limit.
episode.firedBand.maxnumber | nullThe upper limit, or null when the band has no upper limit.
episode.firedBand.triggerVersionnumber | nullThe version of the resident's threshold rule the band belongs to.
episode.valuesobject[]Only readings the episode counted: each firing reading and the reading that recovered it. Excludes batch-data, statistics, and presence-batch history rows, non-readings, and the absent reading that closed an AWAY episode. Older episodes stored before migration 60 list readings as before.
episode.values[].observationIdstringThe reading's id.
episode.values[].valueNumbernumber | nullThe numeric value.
episode.values[].valueStringstring | nullThe value as text, when it is not numeric.
episode.values[].valueUnitstring | nullThe unit, for example beats/min.
episode.values[].notestring | nullA note recorded with the reading.
episode.values[].observedAtstring (ISO 8601 date-time) | nullThe device's event time. null when the reading carries none.
episode.values[].recordedAtstring (ISO 8601 date-time)When Signals stored the reading. It is the clock the episode window uses, so a chart plotted on it stays inside the episode's bounds.
episode.truncatedbooleantrue when more than 999 counted readings exist and the returned values list is capped.
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.
carehub.patientIdstring (uuid)The resident's Ovok Patient.id. Use it for the patient filter and for other Slim routes.
carehub.patientNamestring | nullThe resident's label (their Resident ID): the Patient's nickname, otherwise its official given name, otherwise the first name on file.
carehub.locationIdstring (uuid) | nullThe room's Location id.
carehub.locationNamestring | nullThe room's name.
carehub.roomstring | nullThe room label, from the Location's type codings.
carehub.bedstring | nullThe bed label, from the Location's type codings.
carehub.floorstring | nullThe floor label, from the Location's type codings.
carehub.deviceIdstring | nullThe device serial that the Slim device routes use.
carehub.deviceMedplumIdstring (uuid) | nullThe device's FHIR Device.id.
carehub.deviceNamestring | nullThe device's display name.
carehub.organizationIdstring (uuid) | nullThe zone's id. A zone is the device's managing Organization.
carehub.organizationNamestring | nullThe zone's name.
acknowledgementobject | nullnull until someone acknowledges the episode.
acknowledgement.acknowledgedAtstring (ISO 8601 date-time)When the episode was acknowledged.
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.
acknowledgement.acknowledgedActorobject | nullWho acknowledged. null for acknowledgements made before Ovok sent an actor, and when the session had no profile.
acknowledgement.acknowledgedActor.referencestringThe caller's profile reference, normally Practitioner/{id}. Admin and service sessions can carry another profile type.
acknowledgement.acknowledgedActor.displaystring | nullThe caller's display name, captured when the episode was acknowledged.
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.
404No episode with this id exists in your project, or its resident cannot be resolved into your project.
503Signals could not be reached, or answered with an error other than "not found" (error is signals_unavailable). The body carries error and 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