# Acknowledge medical notification

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

| Method | Path |
| --- | --- |
| `POST` | `/v1/slim/notifications/medical/:episodeId/ack` |

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

### Path parameters [#path-parameters]

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `episodeId` | `string` | Yes | The 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 [#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`](/errors/signals-unavailable)) means the acknowledgement did not happen; repeat the call after `retryAfterSec`.

## Example [#example]

```bash
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 [#successful-response]

`200` — The notification, now acknowledged.

```json
{
  "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.

| Field | Type | Description |
| --- | --- | --- |
| `episode` | `object` | The Signals episode with its aggregates, passed through as Signals reported it. One episode is a run of readings outside the band. |
| `episode.id` | `string` | The episode id. Use it with `GET /v1/slim/notifications/medical/{episodeId}` and `POST /v1/slim/notifications/medical/{episodeId}/ack`. |
| `episode.patientId` | `string` | The resident's id at Signals. It equals `carehub.patientId` for residents created recently; use `carehub.patientId` with other Ovok routes. |
| `episode.code` | `string` | The 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.system` | `string \| null` | The code system of `code`, for example `http://loinc.org`. |
| `episode.display` | `string \| null` | Display text for `code`, when Signals has one. |
| `episode.status` | `"OPEN"` \| `"CLOSED"` | Whether the episode is still running. |
| `episode.openedAt` | `string (ISO 8601 date-time)` | When the episode opened. |
| `episode.closedAt` | `string (ISO 8601 date-time) \| null` | When it closed. `null` while it is open. |
| `episode.closeReason` | `"RECOVERED"` \| `"TIMEOUT"` \| `"ACKNOWLEDGED"` \| `"CROSSED"` \| `"THRESHOLD_CHANGED"` \| `"AWAY"` \| `"STALE"` \| `"MANUAL"` \| `null` | Why it closed; `null` while open. See [How an episode behaves](/signals/connected-ovok#how-an-episode-behaves) for each meaning. |
| `episode.lastSampleAt` | `string (ISO 8601 date-time) \| null` | When the newest reading was folded in. On an open episode it shows how fresh the data is. |
| `episode.durationMs` | `number \| null` | The episode length in milliseconds, as Signals reports it. |
| `episode.observationCount` | `number \| null` | How many readings were folded into the episode. |
| `episode.firingCount` | `number \| null` | How many of those readings were outside the band. |
| `episode.minValue` | `number \| null` | The lowest reading in the episode. |
| `episode.maxValue` | `number \| null` | The highest reading in the episode. |
| `episode.avgValue` | `number \| null` | The average reading in the episode. |
| `episode.lastValue` | `number \| null` | The newest reading folded in. On a recovered episode this is the recovery reading. |
| `episode.peakValue` | `number \| null` | The peak reading of the episode. |
| `episode.peakAt` | `string (ISO 8601 date-time) \| null` | When the peak reading was recorded. |
| `episode.lastFiringValue` | `number \| null` | The 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.lastFiringAt` | `string (ISO 8601 date-time) \| null` | When the last reading outside the band was recorded. |
| `episode.lastObservationId` | `string \| null` | The 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.firedBand` | `object \| null` | The 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.min` | `number \| null` | The lower limit, or `null` when the band has no lower limit. |
| `episode.firedBand.max` | `number \| null` | The upper limit, or `null` when the band has no upper limit. |
| `episode.firedBand.triggerVersion` | `number \| null` | The version of the resident's threshold rule the band belongs to. |
| `carehub` | `object` | The 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.patientId` | `string (uuid)` | The resident's Ovok `Patient.id`. Use it for the `patient` filter and for other Slim routes. |
| `carehub.patientName` | `string \| null` | The resident's label (their Resident ID): the Patient's nickname, otherwise its official given name, otherwise the first name on file. |
| `carehub.locationId` | `string (uuid) \| null` | The room's Location id. |
| `carehub.locationName` | `string \| null` | The room's name. |
| `carehub.room` | `string \| null` | The room label, from the Location's type codings. |
| `carehub.bed` | `string \| null` | The bed label, from the Location's type codings. |
| `carehub.floor` | `string \| null` | The floor label, from the Location's type codings. |
| `carehub.deviceId` | `string \| null` | The device serial that the Slim device routes use. |
| `carehub.deviceMedplumId` | `string (uuid) \| null` | The device's FHIR `Device.id`. |
| `carehub.deviceName` | `string \| null` | The device's display name. |
| `carehub.organizationId` | `string (uuid) \| null` | The zone's id. A zone is the device's managing Organization. |
| `carehub.organizationName` | `string \| null` | The zone's name. |
| `acknowledgement` | `object \| null` | `null` until someone acknowledges the episode. |
| `acknowledgement.acknowledgedAt` | `string (ISO 8601 date-time)` | When the episode was acknowledged. |
| `acknowledgement.acknowledgedBy` | `string \| null` | Ovok'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.acknowledgedActor` | `object \| null` | Who acknowledged. `null` for acknowledgements made before Ovok sent an actor, and when the session had no profile. |
| `acknowledgement.acknowledgedActor.reference` | `string` | The caller's profile reference, normally `Practitioner/{id}`. Admin and service sessions can carry another profile type. |
| `acknowledgement.acknowledgedActor.display` | `string \| null` | The caller's display name, captured when the episode was acknowledged. |
| `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, or you cannot access the project. |
| [`404`](/errors/not-found) | No episode with this id exists in your project, or its resident cannot be resolved into your project. |
| [`409`](/errors/conflict) | The project's Signals tenant has episodic alerts switched off. |
| [`503`](/errors/service-unavailable) | Signals did not confirm the acknowledgement within the 12-second retry budget (`error: "signals_unavailable"` ([`signals_unavailable`](/errors/signals-unavailable)), `retryAfterSec: 5`, `Retry-After: 5`). The acknowledgement did not happen; repeat the call. |
