List location assignment candidates

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.

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

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

Field	Type	Meaning
total	number	Total rows matching the filters. A row represents a device at a location, or a location with no device.
page, count	number	Zero-based page index and page size.
resources	array	Assignment candidates with location, device, resident, occupied, assignable, and warningCode fields.

Successful response

200 — Location assignment candidates retrieved successfully.

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.