# List zones

Canonical page: https://docs.ovok.com/slim-apis/zones/list-zones

| Method | Path |
| --- | --- |
| `GET` | `/v1/slim/zones` |

[Authentication](/authentication) · [Access policies](/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 [#request]

### Query parameters [#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 [#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 [#example]

```bash
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 [#successful-response]

`200` — Zones retrieved successfully.

```json
{
  "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 [#errors]

| Status | Meaning |
| --- | --- |
| [`401`](/errors/unauthenticated) | Bearer token is missing, invalid or expired. |
| [`403`](/errors/forbidden) | 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`](/errors/validation-failed) | A query parameter fails validation. |
| [`503`](/errors/service-unavailable) | The device list cannot be built and no earlier complete list exists. Retry shortly. |
