# List locations

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

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

[Authentication](/authentication) · [Access policies](/access-policies)

Lists the locations (rooms and beds) in your project, with the device, resident and zone at each one. Use it for the location 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 `Location:search` and `Location:read` (admins and super admins skip this check).
**Scope:** The caller's project (from the token). Only locations, devices and residents in that project are returned.

## Request [#request]

### Query parameters [#query-parameters]

Unknown query parameters are rejected with `422`.

| 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`. |
| `search` | `string` | No | Case-insensitive substring match on location name, device name, resident name and zone name. Trimmed, at least 1 character. |
| `floor` | `string` | No | Keep locations with exactly this floor code. |
| `room` | `string` | No | Keep locations with exactly this room code. |
| `bed` | `string` | No | Keep locations with exactly this bed code. |
| `organizationId` | `string` | No | Keep locations in this zone. |
| `deviceId` | `string` | No | Keep only the row for this device. |

## Behaviour [#behaviour]

- Read-only.
- **One row per device.** A location with several devices appears once per device. A location with no device appears once, without device and resident fields. `total` counts rows, not locations.
- `patientId` and `patientName` are the resident assigned to that row's device. `organizationId` and `organizationName` are the location's zone.
- `search` matches, as a case-insensitive substring, the location name, the name of a device at the location, the name of a resident on such a device, or the zone name.
- `floor`, `room` and `bed` match the location's codes exactly. `organizationId` keeps locations in that zone. `deviceId` keeps only the row for that device.
- Rows are sorted by floor, room, bed, device name, then location name. The sort is case-insensitive and numeric-aware ("2" before "10"). Rows with a missing value sort after rows that have one.
- Pagination is zero-based: `page` (default `0`) and `count` (default `20`, max `100`).
- Unknown query parameters are rejected.

## Example [#example]

```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/location?search=Room%20201&page=0&count=20' \
  -H "Authorization: Bearer ${OVOK_TOKEN}"
```

## Successful response [#successful-response]

`200` — Locations retrieved successfully.

```json
{
  "total": 1,
  "page": 0,
  "count": 20,
  "resources": [
    {
      "id": "5d2a9c64-7e1b-4830-b6f5-9a3c1e8d7b02",
      "name": "Room 201",
      "floor": "2",
      "room": "201",
      "bed": "A",
      "organizationId": "1e6b8d30-2c4f-4a95-8d7e-b0a2c4e6f918",
      "organizationName": "Zone A",
      "deviceName": "Demo/1000001",
      "patientName": "demo-resident",
      "deviceId": "8c5e7a21-4b9d-4f36-a1c8-0d2e6b9f3a54",
      "patientId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21"
    }
  ]
}
```

| Field | Type | Description |
| --- | --- | --- |
| `total` | `integer` | Number of rows after filtering, across all pages. One row per device, so a location can count more than once. |
| `page` | `integer` | Page number of this response. |
| `count` | `integer` | Page size of this response. |
| `resources` | `object[]` | The rows of this page. |
| `resources[].id` | `string (uuid)` | Location id. |
| `resources[].name` | `string` | Location name. Empty string when it has none. |
| `resources[].floor` | `string` | Floor code. Left out when not set. |
| `resources[].room` | `string` | Room code. Left out when not set. |
| `resources[].bed` | `string` | Bed code. Left out when not set. |
| `resources[].organizationId` | `string (uuid)` | Zone id. Left out when the location has no zone. |
| `resources[].organizationName` | `string` | Zone name. Left out when the location has no zone. |
| `resources[].deviceId` | `string (uuid)` | The row's device. Left out for a location with no device. |
| `resources[].deviceName` | `string` | The row's device name. Left out for a location with no device. |
| `resources[].patientId` | `string (uuid)` | Resident on the row's device. Left out when there is none. |
| `resources[].patientName` | `string` | That resident's Resident ID (nickname). Left out when there is none. |

## Errors [#errors]

| Status | Meaning |
| --- | --- |
| [`400`](/errors/malformed-request) | Your session has no project. |
| [`401`](/errors/unauthenticated) | Bearer token is missing, invalid or expired. |
| [`403`](/errors/forbidden) | You are not a practitioner, admin or System Owner, or you lack `Location:search` or `Location:read`. |
| [`422`](/errors/validation-failed) | A query parameter fails validation. |
