Notifications

Acknowledge medical notification

Acknowledge medical notification using Ovok’s Slim API.

MethodPath
POST/v1/slim/notifications/medical/:episodeId/ack

Authentication · Access policies

Acknowledges one medical notification, so it leaves the medical bell. The acknowledgement is written to Signals, which owns medical episodes.

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 (admins and super admins skip this check). Scope: The caller's project (from the token). Ovok reads the episode with your project and checks its resident against your project before it writes anything.

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.

The request has no body.

Behaviour

  • No CommunicationRequest is created or changed. Signals closes the episode with reason ACKNOWLEDGED. A resident still outside the band opens a new episode on their next reading.
  • Ovok retries the Signals read and write for up to 12 seconds. Set the client timeout above 12 seconds. Repeating the call is safe.
  • The response is the acknowledged row, in the feed's row shape, already carrying the new acknowledgement and closed status. Replace the list entry with it; no refetch is needed. noteCount is null: an acknowledge response does not count notes.
  • acknowledgement.acknowledgedBy is Ovok's client id at Signals, not a person; do not show it as a name. acknowledgement.acknowledgedActor is the caller's profile reference and display name, or null when the session has no profile.
  • Ovok clears its cached index of the project's open episodes, so other reads see the episode as closed straight away rather than after a cache expiry.
  • A 404 means the episode does not exist in your project, or its resident cannot be resolved into your project. A 409 means the project's Signals tenant has episodic alerts switched off. A 503 (signals_unavailable) means the acknowledgement did not happen; repeat the call after retryAfterSec.

Example

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

Successful response

200 — The notification, now acknowledged.

{
  "episode": {
    "id": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21",
    "patientId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b22",
    "code": "8867-4",
    "system": "http://loinc.org",
    "display": null,
    "status": "CLOSED",
    "openedAt": "2026-10-09T07:40:12.000Z",
    "closedAt": "2026-10-09T08:12:30.000Z",
    "closeReason": "ACKNOWLEDGED",
    "lastSampleAt": "2026-10-09T08:05:12.000Z",
    "durationMs": 1938000,
    "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": {
    "acknowledgedAt": "2026-10-09T08:12:30.000Z",
    "acknowledgedBy": "demo-signals-client",
    "acknowledgedActor": {
      "reference": "Practitioner/3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b26",
      "display": "Demo Practitioner"
    }
  },
  "noteCount": null
}

The response is one feed row, the same shape as an element of items on GET /v1/slim/notifications/medical.

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.
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 | nullAlways null on an acknowledge response: it does 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, 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.
409The project's Signals tenant has episodic alerts switched off.
503Signals did not confirm the acknowledgement within the 12-second retry budget (error: "signals_unavailable" (signals_unavailable), retryAfterSec: 5, Retry-After: 5). The acknowledgement did not happen; repeat the call.

Last updated on

On this page