Locations
List location assignment candidates
List location assignment candidates using Ovok’s Slim API.
| Method | Path |
|---|---|
GET | /v1/slim/location/assignment-candidates |
Authentication · 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
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
- 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.totalcounts rows. occupiedistruewhen the row's device has a resident assigned. Such rows carrywarningCode: "location_has_existing_resident". OtherwisewarningCodeisnull.assignableis alwaystrue.- Fields with no value are
null. searchandorganizationIdfilter as onGET /v1/slim/location.occupiedtakesoccupied,vacantorall(defaultall).- Rows are sorted as on
GET /v1/slim/location. - Pagination is zero-based:
page(default0) andcount(default50, max50).
Example
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/location/assignment-candidates?occupied=vacant&count=50' \
-H "Authorization: Bearer ${OVOK_TOKEN}"Successful response
200 — Location assignment candidates retrieved successfully.
{
"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
| Status | Meaning |
|---|---|
400 | Your session has no project (an admin token without one). |
401 | Bearer token is missing, invalid or expired. |
403 | 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 | A query parameter fails validation. |
Last updated on