Zones

List zones

List zones using Ovok’s Slim API.

MethodPath
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

NameTypeRequiredDescription
pageintegerNoZero-based page number. Default 0, minimum 0.
countintegerNoRows per page. Default 20, minimum 1, maximum 100.
sortBy"name" | "deviceCount" | "activeDeviceCount" | "inactiveDeviceCount"NoSort column. Default name.
orderBy"ASC" | "DESC"NoSort direction. Upper case only. Default ASC.
searchstringNoCase-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. deviceCount is the number of such devices in the zone; activeDeviceCount and inactiveDeviceCount split 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=true lists it.
  • search keeps zones whose name contains the text, ignoring case.
  • sortBy: name (default), deviceCount, activeDeviceCount or inactiveDeviceCount. orderBy: ASC (default) or DESC.
  • Paging: page from 0, count from 1 to 100 (default 20). total is 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
    }
  ]
}
FieldTypeDescription
totalintegerNumber of zones after the search filter, across all pages.
pageintegerPage number of this response.
countintegerPage size of this response.
resourcesobject[]The zones of this page.
resources[].zoneIdstring (uuid)Zone id.
resources[].zoneNamestringZone name.
resources[].deviceCountintegerDevices with a resident in the zone.
resources[].assignedResidentDeviceCountintegerDevices with a resident in the zone. Equals deviceCount on this route.
resources[].activeDeviceCountintegerCounted devices that are currently active.
resources[].inactiveDeviceCountintegerCounted devices that are not active.

Errors

StatusMeaning
401Bearer token is missing, invalid or expired.
403You 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.
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