Notifications

Acknowledge notification

Acknowledge notification using Ovok’s Slim API.

MethodPath
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

NameTypeRequiredDescription
idstring (uuid)YesThe 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 after retryAfterSec. 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 status is completed and its noteCount is null.
  • 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.

FieldTypeDescription
commIdstringFor 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.
patientIdstring (uuid)The resident's Patient id. Omitted when the notification has no resident.
patientNamestringThe 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.
deviceIdstringThe device identifier stamped on the notification: usually the device's name or serial, for example Demo/100AA01. Omitted when unknown.
deviceNamestringThe device's display name. Omitted when unknown.
locationIdstring (uuid)The room's Location id. Omitted when the notification has no room.
locationNamestringThe 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.
colorstringDisplay 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.
detailsobjectMeasurement details. Always present; every field inside is omitted when unknown.
details.thresholdnumberThe limit that was crossed. For out-of-bed, in seconds.
details.valuenumberThe measured value that crossed the limit. For out-of-bed, a duration in seconds.
details.levelstringSeverity label: high or low for a limit breach, red, yellow or attention for an alarm.
authoredOnstring (ISO 8601 date-time)When the notification was created, in UTC. Falls back to its last update time.
alertCountintegerHow many alerts the notification has absorbed (at least 1). Omitted when not recorded.
occurrenceDateTimestring (ISO 8601 date-time)When the latest event on the notification happened, in UTC. It advances while an episode continues.
episodeEndedAtstring (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.
effectiveTimestampstring (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.
latestObservationTimestampstring (ISO 8601 date-time)When the newest reading behind the notification was taken. Omitted on older notifications; fall back to effectiveTimestamp, then authoredOn.
alarmobject | nullThe sender's alarm, for deviceAlarm and attention notifications. null for every other type, and when the sender's alarm record is incomplete.
alarm.episodeIdstringThe 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.typestringThe sender's alarm type, for example DEVICE_ALARM.
alarm.textstring | nullThe sender's alarm text, or null when it sent none.
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, the FHIR server denies access to the notification, or the notification is not in your project or carries no project.
404No notification with this id exists.
409A 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.
503For 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.
422id is not a UUID.

Last updated on

On this page