# List patients

Canonical page: https://docs.ovok.com/slim-apis/patient/list-patients

| Method | Path |
| --- | --- |
| `GET` | `/v1/slim/patient` |

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

Lists the residents (patients) of your project with their zone, room, device and settings tags. Use it for the residents table in the Slim dashboard.

**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:search`, `Patient:read`, `Device:read`, `Location:read` and `Organization:read` (admins and super admins skip this check).
**Scope:** The caller's project (from the token). A token without a project is refused.

## Request [#request]

### Query parameters [#query-parameters]

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | `integer` | No | Zero-based page number. Default `0`, minimum `0`. |
| `count` | `integer` | No | Rows per page. Default `20`, minimum `1`, maximum `100`. |
| `sortBy` | `"patientName"` \| `"patientNickname"` \| `"organizationName"` \| `"locationName"` \| `"admissionDate"` \| `"dischargeDate"` \| `"medicalSettings"` \| `"bedActivitySettings"` | No | Sort column. Default `patientName`. |
| `orderBy` | `"ASC"` \| `"DESC"` | No | Sort direction. Any letter case is accepted. Default `ASC`. |
| `search` | `string` | No | Case-insensitive substring match on name, nickname, room name and zone name. Trimmed, at least 1 character. |
| `residentState` | `"active"` \| `"discharged-recent"` \| `"discharged"` \| `"archived"` \| `"all"` | No | Keep residents in this state. Default `active`. `all` turns the filter off. |
| `includeDischargedRecent` | `boolean` | No | `true` also keeps `discharged-recent` residents when `residentState` is `active` or `discharged`. Any other value is `false`. Default `false`. |
| `organizationId` | `string` | No | Keep residents in this zone. |
| `hasDevice` | `boolean` | No | `true` keeps residents with a device. Any other value keeps residents without one. Omit to keep both. |
| `medicalSettings` | `"inactive"` \| `"global"` \| `"individual"` | No | Keep residents with this medical settings tag. |
| `bedActivitySettings` | `"inactive"` \| `"global"` \| `"individual"` | No | Keep residents with this bed activity settings tag. |

## Behaviour [#behaviour]

- Read-only.
- One row per resident. When a resident is on several devices, the row shows one of them, so a resident is never listed twice.
- `residentState` defaults to `active`, so discharged residents are hidden unless you ask for them. `discharged-recent` means discharged within the last 30 days; `discharged` means longer ago. `all` turns the filter off.
- `includeDischargedRecent=true` widens `residentState=active` or `residentState=discharged` to also include `discharged-recent` residents.
- `organizationId` keeps residents in that zone. `hasDevice=true` keeps residents with a device; `hasDevice=false` keeps residents without one.
- `medicalSettings` and `bedActivitySettings` keep residents with that settings tag. These tags are `null` when Ovok could not read the project's threshold settings; such rows match no settings filter.
- When the home has never saved its threshold template, residents with no individual limits read `medicalSettings: "global"`.
- `search` is a case-insensitive substring match on the resident's name, nickname, room name and zone name.
- Sort with `sortBy` (default `patientName`) and `orderBy` (`ASC` or `DESC`, any case, default `ASC`).
- Pagination is zero-based: `page` (default `0`) and `count` (default `20`, max `100`). `total` counts all matching rows.
- Fields with no value are `null`.
- Results are cached for up to 60 seconds per user. A change to a resident, device, room or zone made through Ovok clears the cache.
- The route answers 503 when the device list cannot be built and no earlier complete list exists. Retry shortly.

## Example [#example]

```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/patient?residentState=active&sortBy=patientNickname&orderBy=asc&page=0&count=20' \
  -H "Authorization: Bearer ${OVOK_TOKEN}"
```

## Successful response [#successful-response]

`200` — Patients retrieved successfully.

```json
{
  "total": 1,
  "page": 0,
  "count": 20,
  "resources": [
    {
      "id": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21",
      "name": "Anna Beispiel",
      "nickname": "demo-resident",
      "residentState": "active",
      "admissionDate": "2026-10-01T08:00:00.000Z",
      "dischargeDate": null,
      "organizationId": "1e6b8d30-2c4f-4a95-8d7e-b0a2c4e6f918",
      "organizationName": "Zone A",
      "locationId": "5d2a9c64-7e1b-4830-b6f5-9a3c1e8d7b02",
      "locationName": "Room 101",
      "deviceId": "8c5e7a21-4b9d-4f36-a1c8-0d2e6b9f3a54",
      "deviceName": "Demo/1000001",
      "medicalSettings": "global",
      "bedActivitySettings": "individual"
    }
  ]
}
```

| Field | Type | Description |
| --- | --- | --- |
| `total` | `integer` | Number of rows after filtering, across all pages. |
| `page` | `integer` | Page number of this response. |
| `count` | `integer` | Page size of this response. |
| `resources` | `object[]` | The rows of this page. |
| `resources[].id` | `string (uuid)` | Patient id. |
| `resources[].name` | `string` | The resident's full display name. Empty string when no name resolves. |
| `resources[].nickname` | `string \| null` | The resident's nickname (Resident ID). |
| `resources[].residentState` | `"active"` \| `"discharged-recent"` \| `"discharged"` \| `"archived"` | Resident state. |
| `resources[].admissionDate` | `string \| null` | Admission time as stored. |
| `resources[].dischargeDate` | `string \| null` | Discharge time as stored. |
| `resources[].organizationId` | `string \| null` | Zone id. |
| `resources[].organizationName` | `string \| null` | Zone name. |
| `resources[].locationId` | `string \| null` | Room id. |
| `resources[].locationName` | `string \| null` | Room name. |
| `resources[].deviceId` | `string \| null` | Device id. When the resident has several devices, one of them. |
| `resources[].deviceName` | `string \| null` | Device name. |
| `resources[].medicalSettings` | `"inactive"` \| `"global"` \| `"individual"` \| `null` | Medical settings tag: no medical notification can fire (`inactive`), the resident follows the project defaults (`global`), or has own settings that alert (`individual`). `null` when the threshold settings could not be read. |
| `resources[].bedActivitySettings` | `"inactive"` \| `"global"` \| `"individual"` \| `null` | The same tag for bed activity. |

## 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:search`, `Patient:read`, `Device:read`, `Location:read` or `Organization:read`, your session has no project, or you cannot access the project. |
| [`422`](/errors/validation-failed) | A query parameter fails validation. |
| [`503`](/errors/service-unavailable) | The device list cannot be built and no earlier complete list exists. Retry shortly. |
