# List out-of-bed notifications

Canonical page: https://docs.ovok.com/slim-apis/notifications/list-out-of-bed-notifications

| Method | Path |
| --- | --- |
| `GET` | `/v1/slim/notifications/oob` |

[Authentication](/authentication) · [Access policies](/access-policies)

Lists your project's out-of-bed notifications, filtered and paged. Signals evaluates out-of-bed; Ovok serves one row per episode from Signals. Medical notifications are not here; read `GET /v1/slim/notifications/medical` for those.

**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 `CommunicationRequest:read`, `CommunicationRequest:search` and `Observation:read` (admins and super admins skip this check).
**Scope:** The caller's project (from the token). The `project` query parameter is accepted but ignored.

## Request [#request]

### Query parameters [#query-parameters]

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `"active"` \| `"completed"` \| `"cancelled"` \| `"draft"` \| `"on-hold"` \| `"revoked"` \| `"unknown"` \| `"entered-in-error"` | No | `active` lists new episodes and `completed` lists reviewed episodes. Omit it to list both. `revoked` lists episodes closed by hand. There is no `all` value. |
| `patient` | `string` | No | Only this resident's notifications. A Patient id, or `Patient/{id}`. |
| `device` | `string` | No | Only this device's notifications. A Device id, `Device/{id}`, or the device's identifier value (for example `Demo/100AA01`). A Device id that does not exist returns an empty page, not an unfiltered one. |
| `startDate` | `string (ISO 8601 date-time)` | No | Inclusive lower bound on the episode's last firing time, a UTC instant ending in `Z`. Defaults to one year back for active episodes and 30 days back for reviewed episodes. When `status` is omitted, each half uses its own default. |
| `endDate` | `string (ISO 8601 date-time)` | No | Inclusive upper bound on the episode's last firing time, a UTC instant ending in `Z`. No default. Must not be before `startDate`. |
| `page` | `integer` | No | The zero-based page number. Minimum 0, default 0. |
| `count` | `integer` | No | The page size. Minimum 1, maximum 100, default 25. |
| `project` | `string` | No | Accepted and ignored. The project always comes from the token. |

Any other parameter, including `type`, is ignored.

## Behaviour [#behaviour]

- The notification type is fixed to out-of-bed; there is no `type` parameter. Prefer this route over the deprecated `GET /v1/slim/notifications?type=outOfBed`.
- `active` lists new episodes and `completed` lists reviewed episodes. With no `status`, the route merges both lists newest first; each row keeps its own status. A manually closed unacknowledged episode is `revoked`: it appears in neither list, so request `status=revoked`. An unacknowledged `STALE` episode stays `active` with `episodeEndedAt` set. There is no `status=all`.
- One row per out-of-bed episode, not per reading: the resident's open episode is updated in place.
- One in-bed reading ends an absence and clears its acknowledgement silence. The next absent reading starts a new absence with its own start and limit, whether or not the previous one was acknowledged. See [How an episode behaves](/signals/connected-ovok#how-an-episode-behaves).
- Sort order: newest first by event time (`occurrenceDateTime`, then `authoredOn`, then id).
- `patient` takes a Patient id or `Patient/{id}`. `device` takes a Device id, `Device/{id}`, or the device's identifier value. A Device id that does not exist returns an empty page rather than an unfiltered one.
- `startDate` and `endDate` bind to the episode's last firing time for every status. They are inclusive UTC instants; a `startDate` after `endDate` fails validation.
- Paging: `page` starts at 0 and `count` is 1 to 100 (default 25). `total` is the sum of the matching lists, capped at 1,000; with no `status`, it is the combined active and completed count. `truncated` reports `result-cap` when rows were cut at 1,000.
- `noteCount` is always `null` on this route; Signals owns out-of-bed episode notes.
- The row id is the Signals episode id. Acknowledge it with `PATCH /v1/slim/notifications/{id}/ack`; episode notes use `/v1/slim/notifications/oob/{id}/notes`.
- Signals reads wait up to 5 seconds. If Signals does not answer, the route returns `503 signals_unavailable` ([`signals_unavailable`](/errors/signals-unavailable)) with `retryAfterSec` and `Retry-After`. The server can also shed a read with `503 live_reads_over_capacity` ([`live_reads_over_capacity`](/errors/live-reads-over-capacity)).

## Example [#example]

```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/notifications/oob?status=active&page=0&count=25' \
  -H "Authorization: Bearer ${OVOK_TOKEN}"
```

## Successful response [#successful-response]

`200` — Out-of-bed notifications retrieved successfully.

```json
{
  "total": 2,
  "page": 0,
  "count": 25,
  "truncated": null,
  "resources": [
    {
      "commId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b11",
      "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": "active",
      "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": 1
    },
    {
      "commId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b14",
      "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": "active",
      "details": {
        "threshold": 1800,
        "value": 2410,
        "level": "high"
      },
      "authoredOn": "2026-10-08T22:05:00.000Z",
      "alertCount": 7,
      "occurrenceDateTime": "2026-10-08T22:50:00.000Z",
      "episodeEndedAt": "2026-10-08T22:58:00.000Z",
      "effectiveTimestamp": "2026-10-08T22:05:00.000Z",
      "latestObservationTimestamp": "2026-10-08T22:50:00.000Z",
      "alarm": null,
      "noteCount": 0
    }
  ]
}
```

| Field | Type | Description |
| --- | --- | --- |
| `total` | `integer` | Number of matching rows, capped at 1,000. When `status` is omitted, this is the sum of the active and completed lists before the cap. |
| `page` | `integer` | The page number you asked for. |
| `count` | `integer` | The page size you asked for. |
| `truncated` | `object \| null` | `null` when nothing was withheld. Otherwise the server stopped looking, and this says why. |
| `truncated.reason` | `"result-cap"` | More rows exist beyond the 1,000-result cap. |
| `truncated.limit` | `integer` | The cap or scan limit that was reached. |
| `resources` | `object[]` | The page of rows, newest first by the episode's last firing time. Each element is a row, described below. |

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 |
| --- | --- | --- |
| `resources[].commId` | `string` | The out-of-bed episode's Signals id. Use it to acknowledge the notification with `PATCH /v1/slim/notifications/{id}/ack` and for `/v1/slim/notifications/oob/{id}/notes`. |
| `resources[].patientId` | `string (uuid)` | The resident's Patient id. Omitted when the notification has no resident. |
| `resources[].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. |
| `resources[].deviceId` | `string` | The device identifier stamped on the notification: usually the device's name or serial, for example `Demo/100AA01`. Omitted when unknown. |
| `resources[].deviceName` | `string` | The device's display name. Omitted when unknown. |
| `resources[].locationId` | `string (uuid)` | The room's Location id. Omitted when the notification has no room. |
| `resources[].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. |
| `resources[].color` | `string` | Display colour of the alert as a hex string, for example `#E5254B`. Omitted when absent. |
| `resources[].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. |
| `resources[].type` | `"outOfBed"` | The notification type. Always `outOfBed` on this route. |
| `resources[].status` | `"active"` \| `"completed"` \| `"cancelled"` \| `"on-hold"` \| `"draft"` \| `"revoked"` \| `"entered-in-error"` \| `"unknown"` | The notification's status. `active` until someone acknowledges it, then `completed`. The other values are standard FHIR request statuses. |
| `resources[].details` | `object` | Measurement details. Always present; every field inside is omitted when unknown. |
| `resources[].details.threshold` | `number` | The limit that was crossed. For out-of-bed, in seconds. |
| `resources[].details.value` | `number` | The measured value that crossed the limit. For out-of-bed, a duration in seconds. |
| `resources[].details.level` | `string` | Severity label: `high` or `low` for a limit breach, `red`, `yellow` or `attention` for an alarm. |
| `resources[].authoredOn` | `string (ISO 8601 date-time)` | When the notification was created, in UTC. Falls back to its last update time. |
| `resources[].alertCount` | `integer` | How many alerts the notification has absorbed (at least 1). Omitted when not recorded. |
| `resources[].occurrenceDateTime` | `string (ISO 8601 date-time)` | When the latest event on the notification happened, in UTC. It advances while an episode continues. |
| `resources[].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. |
| `resources[].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`. |
| `resources[].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`. |
| `resources[].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. |
| `resources[].alarm.episodeId` | `string` | The sender's own id for the alarm, so it can match an acknowledgement to its record. |
| `resources[].alarm.severity` | `"RED"` \| `"YELLOW"` \| `"ATTENTION"` | The severity as the sender coded it. `ATTENTION` is an attention press. |
| `resources[].alarm.type` | `string` | The sender's alarm type, for example `DEVICE_ALARM`. |
| `resources[].alarm.text` | `string \| null` | The sender's alarm text, or `null` when it sent none. |
| `resources[].noteCount` | `null` | Always `null` on this route. |

## 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 `CommunicationRequest:read`, `CommunicationRequest:search` or `Observation:read`, your session has no project, you cannot access the project, or the `device` filter names a Device you cannot read. |
| [`422`](/errors/validation-failed) | A query parameter fails validation, for example a `count` outside 1 to 100, a negative `page`, a `startDate` or `endDate` that is not a UTC instant, or a `startDate` after `endDate`. |
| [`503`](/errors/service-unavailable) | Signals did not answer within 5 seconds (`error: "signals_unavailable"` ([`signals_unavailable`](/errors/signals-unavailable))), or the server shed the read (`error: "live_reads_over_capacity"` ([`live_reads_over_capacity`](/errors/live-reads-over-capacity))). The body carries `retryAfterSec` and the `Retry-After` header carries the same delay in seconds. Retry after it. |
