# List location assignment candidates

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

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

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

Lists locations a resident can be placed in, flagged as occupied or vacant. Use it to fill the location picker when you assign a resident.

**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`, `Location:read`, `Device:read`, `Patient:read` and `Organization:read` (admins and super admins skip this check).
**Scope:** The caller's project (from the token). A non-admin token without a project is refused.

## 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 `50`, minimum `1`, maximum `50`. |
| `search` | `string` | No | Case-insensitive substring match on location name, device name, resident name and zone name. Trimmed, at least 1 character. |
| `organizationId` | `string` | No | Keep locations in this zone. |
| `occupied` | `"occupied"` \| `"vacant"` \| `"all"` | No | Keep rows with a resident, rows without one, or both. Default `all`. |

## Behaviour [#behaviour]

- Read-only.
- Built from the same data as `GET /v1/slim/location`: **one row per device** at a location, and one row for a location with no device. `total` counts rows.
- `occupied` is `true` when the row's device has a resident assigned. Such rows carry `warningCode: "location_has_existing_resident"`. Otherwise `warningCode` is `null`.
- `assignable` is always `true`.
- Fields with no value are `null`.
- `search` and `organizationId` filter as on `GET /v1/slim/location`. `occupied` takes `occupied`, `vacant` or `all` (default `all`).
- Rows are sorted as on `GET /v1/slim/location`.
- Pagination is zero-based: `page` (default `0`) and `count` (default `50`, max `50`).

## Example [#example]

```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/location/assignment-candidates?occupied=vacant&count=50' \
  -H "Authorization: Bearer ${OVOK_TOKEN}"
```


## Successful response [#successful-response]

`200` — Location assignment candidates retrieved successfully.

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

| Field | Type | Description |
| --- | --- | --- |
| `total` | `integer` | Number of rows after filtering, across all pages. One row per device, and one row for a location with no device. |
| `page` | `integer` | Page number of this response. |
| `count` | `integer` | Page size of this response. |
| `resources` | `object[]` | The rows of this page. |
| `resources[].locationId` | `string (uuid)` | Location id. |
| `resources[].locationName` | `string` | Location name. |
| `resources[].organizationId` | `string \| null` | Zone id. |
| `resources[].organizationName` | `string \| null` | Zone name. |
| `resources[].deviceId` | `string \| null` | The row's device. |
| `resources[].deviceName` | `string \| null` | The row's device name. |
| `resources[].patientId` | `string \| null` | Resident on the row's device. |
| `resources[].patientName` | `string \| null` | That resident's Resident ID (nickname). |
| `resources[].occupied` | `boolean` | `true` when the row's device has a resident. |
| `resources[].assignable` | `boolean` | Always `true`. |
| `resources[].warningCode` | `"location_has_existing_resident"` \| `null` | `location_has_existing_resident` when `occupied` is `true`, otherwise `null`. |

## Errors [#errors]

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