Get medical notification
Get medical notification using Ovok’s Slim API.
| Method | Path |
|---|---|
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
| Name | Type | Required | Description |
|---|---|---|---|
episodeId | string | Yes | The 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 afterretryAfterSec. episodeis the Signals episode as Signals returned it: status, open and close times, close reason, aggregates, andvalues. Thevalueslist contains only readings the episode counted: each firing reading and the reading that recovered it. It omits history rows (batch-data,statistics, andpresence-batch), non-readings (including 0, -1, missing values and values at or below 0), and the absent reading that closed anAWAYepisode. Episodes stored before migration 60 list readings as they did before. Clients should not render a "0 bpm" or "No value" line. Checkepisode.truncated: a long episode returns up to 999 counted readings and sets it totrue.carehubadds the resident context: resident, room and bed, device and zone. Its fields arenullwhen the resident has no device assigned.acknowledgementisnulluntil someone acknowledges the episode.episode.firedBandis the band the episode was judged under, as described onGET /v1/slim/notifications/medical. It isnullwhen it cannot be established.noteCountis the number of notes on the episode, ornullwhen 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_unavailablemeans Signals could not be reached; retry afterretryAfterSec.
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.
| Field | Type | Description |
|---|---|---|
episode | object | The Signals episode with its aggregates, passed through as Signals reported it. One episode is a run of readings outside the band. |
episode.id | string | The episode id. Use it with GET /v1/slim/notifications/medical/{episodeId} and POST /v1/slim/notifications/medical/{episodeId}/ack. |
episode.patientId | string | The resident's id at Signals. It equals carehub.patientId for residents created recently; use carehub.patientId with other Ovok routes. |
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. |
episode.system | string | null | The code system of code, for example http://loinc.org. |
episode.display | string | null | Display text for code, when Signals has one. |
episode.status | "OPEN" | "CLOSED" | Whether the episode is still running. |
episode.openedAt | string (ISO 8601 date-time) | When the episode opened. |
episode.closedAt | string (ISO 8601 date-time) | null | When it closed. null while it is open. |
episode.closeReason | "RECOVERED" | "TIMEOUT" | "ACKNOWLEDGED" | "CROSSED" | "THRESHOLD_CHANGED" | "AWAY" | "STALE" | "MANUAL" | null | Why it closed; null while open. See How an episode behaves for each meaning. |
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. |
episode.durationMs | number | null | The episode length in milliseconds, as Signals reports it. |
episode.observationCount | number | null | How many readings were folded into the episode. |
episode.firingCount | number | null | How many of those readings were outside the band. |
episode.minValue | number | null | The lowest reading in the episode. |
episode.maxValue | number | null | The highest reading in the episode. |
episode.avgValue | number | null | The average reading in the episode. |
episode.lastValue | number | null | The newest reading folded in. On a recovered episode this is the recovery reading. |
episode.peakValue | number | null | The peak reading of the episode. |
episode.peakAt | string (ISO 8601 date-time) | null | When the peak reading was recorded. |
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. |
episode.lastFiringAt | string (ISO 8601 date-time) | null | When the last reading outside the band was recorded. |
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. |
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. |
episode.firedBand.min | number | null | The lower limit, or null when the band has no lower limit. |
episode.firedBand.max | number | null | The upper limit, or null when the band has no upper limit. |
episode.firedBand.triggerVersion | number | null | The version of the resident's threshold rule the band belongs to. |
episode.values | object[] | 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[].observationId | string | The reading's id. |
episode.values[].valueNumber | number | null | The numeric value. |
episode.values[].valueString | string | null | The value as text, when it is not numeric. |
episode.values[].valueUnit | string | null | The unit, for example beats/min. |
episode.values[].note | string | null | A note recorded with the reading. |
episode.values[].observedAt | string (ISO 8601 date-time) | null | The device's event time. null when the reading carries none. |
episode.values[].recordedAt | string (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.truncated | boolean | true when more than 999 counted readings exist and the returned values list is capped. |
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. |
carehub.patientId | string (uuid) | The resident's Ovok Patient.id. Use it for the patient filter and for other Slim routes. |
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. |
carehub.locationId | string (uuid) | null | The room's Location id. |
carehub.locationName | string | null | The room's name. |
carehub.room | string | null | The room label, from the Location's type codings. |
carehub.bed | string | null | The bed label, from the Location's type codings. |
carehub.floor | string | null | The floor label, from the Location's type codings. |
carehub.deviceId | string | null | The device serial that the Slim device routes use. |
carehub.deviceMedplumId | string (uuid) | null | The device's FHIR Device.id. |
carehub.deviceName | string | null | The device's display name. |
carehub.organizationId | string (uuid) | null | The zone's id. A zone is the device's managing Organization. |
carehub.organizationName | string | null | The zone's name. |
acknowledgement | object | null | null until someone acknowledges the episode. |
acknowledgement.acknowledgedAt | string (ISO 8601 date-time) | When the episode was acknowledged. |
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. |
acknowledgement.acknowledgedActor | object | null | Who acknowledged. null for acknowledgements made before Ovok sent an actor, and when the session had no profile. |
acknowledgement.acknowledgedActor.reference | string | The caller's profile reference, normally Practitioner/{id}. Admin and service sessions can carry another profile type. |
acknowledgement.acknowledgedActor.display | string | null | The caller's display name, captured when the episode was acknowledged. |
noteCount | integer | null | The number of notes on this episode. null when the count could not be established. |
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. |
404 | No episode with this id exists in your project, or its resident cannot be resolved into your project. |
503 | Signals 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