Zones
List zones
List zones using Ovok’s Slim API.
| Method | Path |
|---|---|
GET | /v1/slim/zones |
Authentication · Access policies
Lists the zones of your project with their device counts. A zone is a FHIR Organization. Use it for a zone overview; use GET /v1/slim/zones/{zoneId} for one zone's locations.
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 Organization:search, Organization:read and Device:read (admins and super admins skip this check).
Scope: The caller's project (from the token).
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 | "name" | "deviceCount" | "activeDeviceCount" | "inactiveDeviceCount" | No | Sort column. Default name. |
orderBy | "ASC" | "DESC" | No | Sort direction. Upper case only. Default ASC. |
search | string | No | Case-insensitive substring match on the zone name. Trimmed, at least 1 character. |
Behaviour
- Counts are taken from the same rows as
GET /v1/slim/device/live: only devices assigned to a resident are counted.deviceCountis the number of such devices in the zone;activeDeviceCountandinactiveDeviceCountsplit them by whether the device is currently active, as on the live view. - Only zones with at least one counted device are listed. A zone with no assigned devices does not appear;
GET /v1/slim/zones/device-counts?includeEmpty=truelists it. searchkeeps zones whose name contains the text, ignoring case.sortBy:name(default),deviceCount,activeDeviceCountorinactiveDeviceCount.orderBy:ASC(default) orDESC.- Paging:
pagefrom 0,countfrom 1 to 100 (default 20).totalis the number of zones after the search filter. - 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/zones?sortBy=deviceCount&orderBy=DESC&page=0&count=20' \
-H "Authorization: Bearer ${OVOK_TOKEN}"Successful response
200 — Zones retrieved successfully.
{
"total": 1,
"page": 0,
"count": 20,
"resources": [
{
"zoneId": "1e6b8d30-2c4f-4a95-8d7e-b0a2c4e6f918",
"zoneName": "Zone A",
"deviceCount": 15,
"assignedResidentDeviceCount": 15,
"activeDeviceCount": 12,
"inactiveDeviceCount": 3
}
]
}| Field | Type | Description |
|---|---|---|
total | integer | Number of zones after the search filter, across all pages. |
page | integer | Page number of this response. |
count | integer | Page size of this response. |
resources | object[] | The zones of this page. |
resources[].zoneId | string (uuid) | Zone id. |
resources[].zoneName | string | Zone name. |
resources[].deviceCount | integer | Devices with a resident in the zone. |
resources[].assignedResidentDeviceCount | integer | Devices with a resident in the zone. Equals deviceCount on this route. |
resources[].activeDeviceCount | integer | Counted devices that are currently active. |
resources[].inactiveDeviceCount | integer | Counted devices that are not active. |
Errors
| Status | Meaning |
|---|---|
401 | Bearer token is missing, invalid or expired. |
403 | You are not a practitioner, admin or System Owner, you lack Organization:search, Organization:read or Device: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