Zones

Get zone device counts

Get zone device counts using Ovok’s Slim API.

MethodPath
GET/v1/slim/zones/device-counts

Authentication · Access policies

Returns device counts per zone for your project, with project-wide totals. A zone is a FHIR Organization.

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, Device:search and Device:read (admins and super admins skip this check). Scope: The caller's project (from the token).

Request

Query parameters

Each boolean is true only for the exact value true. Any other value is false.

NameTypeRequiredDescription
allbooleanNotrue counts every device in each zone, assigned or not, and ignores effectiveSleepStatus. Default false.
effectiveSleepStatus"disconnected" | "connected" | "awake" | "away" | "asleep"NoCount only devices in this state. A device that is not active counts as disconnected.
includeUnassignedbooleanNoAlso count devices with no resident and add a bucket for devices in no zone. Default false.
includeEmptybooleanNoKeep project zones that have no matching devices, with zero counts. Default false.

Behaviour

  • By default, deviceCount matches the rows GET /v1/slim/device/live returns for each zone: devices assigned to a resident.
  • all=true counts every device in each zone, assigned or not, and ignores effectiveSleepStatus.
  • effectiveSleepStatus (disconnected, connected, awake, away, asleep) counts only devices in that state. A device that is not active counts as disconnected.
  • includeUnassigned=true also counts devices with no resident (unless all=true already does) and adds a bucket, with organization unset, for devices in no zone.
  • includeEmpty=true keeps project zones that have no matching devices, with zero counts.
  • For each zone, assignedResidentDeviceCount counts devices with a resident, and activeDeviceCount / inactiveDeviceCount split devices by whether they are currently active.
  • Zones are sorted by deviceCount, highest first. total is the number of entries; the total…Count fields sum the per-zone counts.
  • 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/device-counts?includeEmpty=true&includeUnassigned=true' \
  -H "Authorization: Bearer ${OVOK_TOKEN}"

Successful response

200 — Zone device counts retrieved successfully.

{
  "total": 2,
  "totalDeviceCount": 18,
  "totalAssignedResidentDeviceCount": 15,
  "totalActiveDeviceCount": 14,
  "totalInactiveDeviceCount": 4,
  "resources": [
    {
      "organization": {
        "resourceType": "Organization",
        "id": "1e6b8d30-2c4f-4a95-8d7e-b0a2c4e6f918",
        "name": "Zone A",
        "meta": { "project": "b7a3d915-6e20-4c8f-9a14-3d5f7b9c1e68", "lastUpdated": "2026-10-09T08:00:00.000Z" }
      },
      "deviceCount": 15,
      "assignedResidentDeviceCount": 15,
      "activeDeviceCount": 12,
      "inactiveDeviceCount": 3
    },
    {
      "deviceCount": 3,
      "assignedResidentDeviceCount": 0,
      "activeDeviceCount": 2,
      "inactiveDeviceCount": 1
    }
  ]
}

The second entry is the bucket of devices in no zone. It appears with includeUnassigned=true and has no organization.

FieldTypeDescription
totalintegerNumber of entries in resources.
totalDeviceCountintegerSum of deviceCount over all entries.
totalAssignedResidentDeviceCountintegerSum of assignedResidentDeviceCount over all entries.
totalActiveDeviceCountintegerSum of activeDeviceCount over all entries.
totalInactiveDeviceCountintegerSum of inactiveDeviceCount over all entries.
resourcesobject[]One entry per zone, highest deviceCount first.
resources[].organizationobjectThe zone. Left out for the bucket of devices in no zone.
resources[].organization.resourceType"Organization"Always Organization.
resources[].organization.idstring (uuid)Zone id.
resources[].organization.namestringZone name.
resources[].organization.descriptionstringNarrative text of the zone. Left out when there is none.
resources[].organization.metaobjectLeft out when not available.
resources[].organization.meta.projectstring (uuid)Project that holds the zone.
resources[].organization.meta.lastUpdatedstring (ISO 8601 date-time)When the zone last changed.
resources[].deviceCountintegerDevices counted in this entry.
resources[].assignedResidentDeviceCountintegerCounted devices that have a resident.
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, Device:search 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