# Acknowledge notification

Canonical page: https://docs.ovok.com/slim-apis/notifications/acknowledge-notification

| Method | Path |
| --- | --- |
| `PATCH` | `/v1/slim/notifications/:id/ack` |

[Authentication](/authentication) · [Access policies](/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 [#request]

### Path parameters [#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 [#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`](/errors/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 [#example]

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

## Successful response [#successful-response]

`200` — Notification acknowledged successfully.

```json
{
  "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 [#errors]

| Status | Meaning |
| --- | --- |
| [`401`](/errors/unauthenticated) | Bearer token is missing, invalid or expired. |
| [`403`](/errors/forbidden) | 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`](/errors/not-found) | No notification with this id exists. |
| [`409`](/errors/conflict) | 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`](/errors/service-unavailable) | 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`](/errors/signals-unavailable)), `retryAfterSec: 5`, and `Retry-After: 5`; retrying the call is safe. |
| [`422`](/errors/validation-failed) | `id` is not a UUID. |
