Patients
List patients
List patients using Ovok’s Slim API.
| Method | Path |
|---|---|
GET | /v1/slim/patient |
Authentication · 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
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
- 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.
residentStatedefaults toactive, so discharged residents are hidden unless you ask for them.discharged-recentmeans discharged within the last 30 days;dischargedmeans longer ago.allturns the filter off.includeDischargedRecent=truewidensresidentState=activeorresidentState=dischargedto also includedischarged-recentresidents.organizationIdkeeps residents in that zone.hasDevice=truekeeps residents with a device;hasDevice=falsekeeps residents without one.medicalSettingsandbedActivitySettingskeep residents with that settings tag. These tags arenullwhen 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". searchis a case-insensitive substring match on the resident's name, nickname, room name and zone name.- Sort with
sortBy(defaultpatientName) andorderBy(ASCorDESC, any case, defaultASC). - Pagination is zero-based:
page(default0) andcount(default20, max100).totalcounts 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
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
200 — Patients retrieved successfully.
{
"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
| Status | Meaning |
|---|---|
401 | Bearer token is missing, invalid or expired. |
403 | 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 | A query parameter fails validation. |
503 | The device list cannot be built and no earlier complete list exists. Retry shortly. |
Last updated on