Acknowledge medical notification
- Sandbox: available
- Staging: available
- Production: unknown
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 (an admin or super admin who holds no access policy skips 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.
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. - Repeating the call is safe.
- Answers 200 with the acknowledged row, in the feed's row shape, already carrying the new
acknowledgementand closed status. Replace the list entry with it; no refetch is needed. acknowledgement.acknowledgedByis Ovok's client id at Signals, not a person; do not show it as a name.acknowledgement.acknowledgedActoris the caller's profile reference and display name, ornullwhen 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.
- An episode in another project, an out-of-bed episode (code
103214-3) or one that does not exist answers the same 404, and nothing is acknowledged. Acknowledge an out-of-bed alert withPATCH /v1/slim/notifications/{id}/ack. - A 409 means the project's Signals tenant has episodic alerts switched off.
- While Signals does not answer, Ovok keeps trying for up to 12 seconds before it answers. A 503 (
signals_unavailable) means Ovok could not confirm the acknowledgement; repeat the call afterretryAfterSec(also sent asRetry-After).
Example
curl -X POST 'https://api.sandbox.ovok.com/v1/slim/notifications/medical/c3499c27-2973-0a7f-807e-fb8676a92dcb/ack' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'bearerAuthorizationBearer <JWT>episodeId*stringThe Signals episode id a feed row carries as episode.id.
The notification, now acknowledged.
application/json- response
episode*carehub*acknowledgement*noteCount*integer0 <= valuecurl -X POST 'https://api.sandbox.ovok.com/v1/slim/notifications/medical/string/ack'{ "episode": { "id": "string", "patientId": "string", "code": "string", "system": "string", "display": "string", "status": "string", "openedAt": "string", "closedAt": "string", "closeReason": "string", "lastSampleAt": "string", "durationMs": 0, "observationCount": 0, "firingCount": 0, "minValue": 0, "maxValue": 0, "avgValue": 0, "lastValue": 0, "peakValue": 0, "peakAt": "string", "lastFiringValue": 0, "lastFiringAt": "string", "lastObservationId": "string", "firedBand": { "min": 0, "max": 0, "triggerVersion": 0 } }, "carehub": { "patientId": "string", "patientName": "string", "locationId": "string", "locationName": "string", "room": "string", "bed": "string", "floor": "string", "deviceId": "string", "deviceMedplumId": "string", "deviceName": "string", "organizationId": "string", "organizationName": "string" }, "acknowledgement": { "acknowledgedAt": "string", "acknowledgedBy": "string", "acknowledgedActor": { "reference": "string", "display": "string" } }, "noteCount": 0}Get medical notification GET
Returns one medical notification with its full value history, addressed by the `episode.id` a feed row carries. The episode is read from Signals, which decides medical alerts. **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` (an admin or super admin who holds no access policy skips 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. ## Behaviour - `episode` is the Signals episode as Signals returned it: status, open and close times, close reason, aggregates, and every reading recorded while it ran (`values`). Check `episode.truncated`: a very long episode returns a capped series and says so. - `carehub` adds the resident context: resident, room and bed, device and zone. `patientName` is the resident's Resident ID, also after a discharge, an unassign or a device move. The room, bed, device and zone are those of the device the episode was raised on, also after the resident moved to another device or was unassigned. They are `null` when that device is not known or is no longer in your project. - `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. - An episode in another project, or an out-of-bed episode (code `103214-3`), 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 ```bash curl -X GET 'https://api.sandbox.ovok.com/v1/slim/notifications/medical/c3499c27-2973-0a7f-807e-fb8676a92dcb' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ```
Leave a note on a notification POST
Leaves a note on a notification. A note is a practitioner's comment on a notification, stored as a FHIR `Communication` whose `basedOn` points at the alert. The alert itself is never changed. **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` (an admin or super admin who holds no access policy skips this check). Only a practitioner can write notes. **Scope:** The caller's project (from the token). An alert or note from another project, of another kind, or that does not exist answers the same 404. ## Behaviour - `kind` names the feed the notification comes from: `oob` or `alarm` with the row's `commId` as `id`, `medical` with the row's `episode.id`, or `alert` with a raw Signals alert's `id`. - A note on a raw alert is also listed and counted on that alert's episode. Which episode is decided once, when the note is written. - `text` is trimmed and must be 1 to 2000 characters. - The author is the calling practitioner, never a body field. - Notes can be left on acknowledged notifications too. - `medical` and `alert` notes are read from Signals first, so they answer 503 `signals_unavailable` while Signals is down. Retry once Signals is back. - Answers 201 with the note as stored. ## Example ```bash curl -X POST 'https://api.sandbox.ovok.com/v1/slim/notifications/notes' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \ -H 'Content-Type: application/json' \ -d '{ "kind": "oob", "id": "c3499c27-2973-0a7f-807e-fb8676a92dcb", "text": "Resident was in the bathroom." }' ```