Patients

List patients

List patients using Ovok’s Slim API.

MethodPath
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

NameTypeRequiredDescription
pageintegerNoZero-based page number. Default 0, minimum 0.
countintegerNoRows per page. Default 20, minimum 1, maximum 100.
sortBy"patientName" | "patientNickname" | "organizationName" | "locationName" | "admissionDate" | "dischargeDate" | "medicalSettings" | "bedActivitySettings"NoSort column. Default patientName.
orderBy"ASC" | "DESC"NoSort direction. Any letter case is accepted. Default ASC.
searchstringNoCase-insensitive substring match on name, nickname, room name and zone name. Trimmed, at least 1 character.
residentState"active" | "discharged-recent" | "discharged" | "archived" | "all"NoKeep residents in this state. Default active. all turns the filter off.
includeDischargedRecentbooleanNotrue also keeps discharged-recent residents when residentState is active or discharged. Any other value is false. Default false.
organizationIdstringNoKeep residents in this zone.
hasDevicebooleanNotrue keeps residents with a device. Any other value keeps residents without one. Omit to keep both.
medicalSettings"inactive" | "global" | "individual"NoKeep residents with this medical settings tag.
bedActivitySettings"inactive" | "global" | "individual"NoKeep 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.
  • 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

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"
    }
  ]
}
FieldTypeDescription
totalintegerNumber of rows after filtering, across all pages.
pageintegerPage number of this response.
countintegerPage size of this response.
resourcesobject[]The rows of this page.
resources[].idstring (uuid)Patient id.
resources[].namestringThe resident's full display name. Empty string when no name resolves.
resources[].nicknamestring | nullThe resident's nickname (Resident ID).
resources[].residentState"active" | "discharged-recent" | "discharged" | "archived"Resident state.
resources[].admissionDatestring | nullAdmission time as stored.
resources[].dischargeDatestring | nullDischarge time as stored.
resources[].organizationIdstring | nullZone id.
resources[].organizationNamestring | nullZone name.
resources[].locationIdstring | nullRoom id.
resources[].locationNamestring | nullRoom name.
resources[].deviceIdstring | nullDevice id. When the resident has several devices, one of them.
resources[].deviceNamestring | nullDevice name.
resources[].medicalSettings"inactive" | "global" | "individual" | nullMedical 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" | nullThe same tag for bed activity.

Errors

StatusMeaning
401Bearer token is missing, invalid or expired.
403You 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.
422A query parameter fails validation.
503The device list cannot be built and no earlier complete list exists. Retry shortly.

Last updated on

On this page