Acknowledge notification
Acknowledge notification using Ovok’s Slim API.
| Method | Path |
|---|---|
PATCH | /v1/slim/notifications/:id/ack |
Authentication · Access policies
Acknowledges an out-of-bed episode or a device alarm or attention notification. Out-of-bed rows come from Signals; device alarms and attention notifications are CommunicationRequests. For a medical notification, use POST /v1/slim/notifications/medical/{episodeId}/ack instead.
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). No CommunicationRequest:update grant is needed.
Scope: The id must belong to your project (from the token). Sub-projects are not included.
Request
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | Yes | The notification row id. For an out-of-bed row it is the Signals episode id; for a device alarm or attention row it is the CommunicationRequest id. |
The request has no body.
Behaviour
- After those checks pass, Ovok writes the status change with its own credentials.
- Acknowledging an already completed notification succeeds and changes nothing.
- If the notification is updated at the same moment (for example by a new reading on the same episode), Ovok re-reads it and retries, keeping the newer content, up to three times.
- The notification leaves the active lists and bells. The device's alert state in the live views is cleared.
- For out-of-bed rows, Ovok retries the Signals read and write for up to 12 seconds. Set the client timeout above 12 seconds. A
503 signals_unavailable(signals_unavailable) means the acknowledgement was not confirmed; retry afterretryAfterSec. The acknowledgement is idempotent. - Acknowledging an out-of-bed episode silences that episode. One in-bed reading ends the absence; the next absent reading starts a new episode with its own start and limit, whether or not the last one was acknowledged.
- The response is the updated row, in the same shape as the list rows. Its
statusiscompletedand itsnoteCountisnull. - A 409 means the notification kept changing and all three attempts lost the race. Re-read it and call again.
Example
curl -X PATCH 'https://api.sandbox.ovok.com/v1/slim/notifications/3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21/ack' \
-H "Authorization: Bearer ${OVOK_TOKEN}"Successful response
200 — Notification acknowledged successfully.
{
"commId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21",
"patientId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b12",
"patientName": "demo-resident",
"deviceId": "Demo/100AA01",
"deviceName": "Demo/100AA01",
"locationId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b13",
"locationName": "Room 101",
"color": "#E5254B",
"trigger": "above",
"type": "outOfBed",
"status": "completed",
"details": {
"threshold": 1800,
"value": 1925,
"level": "high"
},
"authoredOn": "2026-10-09T01:12:00.000Z",
"alertCount": 4,
"occurrenceDateTime": "2026-10-09T02:18:00.000Z",
"effectiveTimestamp": "2026-10-09T01:12:00.000Z",
"latestObservationTimestamp": "2026-10-09T02:18:00.000Z",
"alarm": null,
"noteCount": null
}The response is one notification row, the same shape as an element of resources on GET /v1/slim/notifications/oob.
Each row is one notification. A field described as omitted is left out of the JSON when it has no value; it is not sent as null. details, alarm and noteCount are always present.
| Field | Type | Description |
|---|---|---|
commId | string | For a device alarm or attention alert, the CommunicationRequest id. For an out-of-bed notification, the Signals episode id. Use it with PATCH /v1/slim/notifications/{id}/ack. |
patientId | string (uuid) | The resident's Patient id. Omitted when the notification has no resident. |
patientName | string | The resident's label (their Resident ID): the Patient's nickname, otherwise its official given name, otherwise the name stored on the notification. Omitted when no usable name is available. |
deviceId | string | The device identifier stamped on the notification: usually the device's name or serial, for example Demo/100AA01. Omitted when unknown. |
deviceName | string | The device's display name. Omitted when unknown. |
locationId | string (uuid) | The room's Location id. Omitted when the notification has no room. |
locationName | string | The room's current name, read from the Location. A row keeps the name it was raised with when the Location cannot be read. Omitted when no name is available; it is never a raw id. |
color | string | Display colour of the alert as a hex string, for example #E5254B. Omitted when absent. |
trigger | "above" | "below" | Whether the value went above the upper limit or below the lower limit. Omitted when the notification has no direction, such as an alarm. |
type | "outOfBed" | "deviceAlarm" | "attention" | "hr" | "br" | The notification type, as listed on the feeds: outOfBed, deviceAlarm, attention, or the legacy hr and br. Omitted when it cannot be resolved. |
status | "completed" | Always completed on an acknowledge response. |
details | object | Measurement details. Always present; every field inside is omitted when unknown. |
details.threshold | number | The limit that was crossed. For out-of-bed, in seconds. |
details.value | number | The measured value that crossed the limit. For out-of-bed, a duration in seconds. |
details.level | string | Severity label: high or low for a limit breach, red, yellow or attention for an alarm. |
authoredOn | string (ISO 8601 date-time) | When the notification was created, in UTC. Falls back to its last update time. |
alertCount | integer | How many alerts the notification has absorbed (at least 1). Omitted when not recorded. |
occurrenceDateTime | string (ISO 8601 date-time) | When the latest event on the notification happened, in UTC. It advances while an episode continues. |
episodeEndedAt | string (ISO 8601 date-time) | Set when an out-of-bed episode has ended. The notification stays active until someone acknowledges it. Omitted while the episode runs and on other types. |
effectiveTimestamp | string (ISO 8601 date-time) | The stable start of the episode: for out-of-bed, the moment the resident left the bed. It does not change as occurrenceDateTime advances. Omitted on older notifications; fall back to authoredOn. |
latestObservationTimestamp | string (ISO 8601 date-time) | When the newest reading behind the notification was taken. Omitted on older notifications; fall back to effectiveTimestamp, then authoredOn. |
alarm | object | null | The sender's alarm, for deviceAlarm and attention notifications. null for every other type, and when the sender's alarm record is incomplete. |
alarm.episodeId | string | The sender's own id for the alarm, so it can match an acknowledgement to its record. |
alarm.severity | "RED" | "YELLOW" | "ATTENTION" | The severity as the sender coded it. ATTENTION is an attention press. |
alarm.type | string | The sender's alarm type, for example DEVICE_ALARM. |
alarm.text | string | null | The sender's alarm text, or null when it sent none. |
noteCount | integer | null | Always null on an acknowledge response: it does not count notes. |
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, your session has no project, the FHIR server denies access to the notification, or the notification is not in your project or carries no project. |
404 | No notification with this id exists. |
409 | A CommunicationRequest kept changing and all three write attempts lost the race, or the Signals tenant has episodic alerts switched off for an out-of-bed episode. Re-read or retry when the condition is resolved. |
503 | For an out-of-bed episode, Signals did not confirm the acknowledgement within the 12-second server retry budget. The body has error: "signals_unavailable" (signals_unavailable), retryAfterSec: 5, and Retry-After: 5; retrying the call is safe. |
422 | id is not a UUID. |
Last updated on