Locations

List location assignment candidates

List location assignment candidates using Ovok’s Slim API.

MethodPath
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

NameTypeRequiredDescription
pageintegerNoZero-based page number. Default 0, minimum 0.
countintegerNoRows per page. Default 50, minimum 1, maximum 50.
searchstringNoCase-insensitive substring match on location name, device name, resident name and zone name. Trimmed, at least 1 character.
organizationIdstringNoKeep locations in this zone.
occupied"occupied" | "vacant" | "all"NoKeep 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. 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}"

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"
    }
  ]
}
FieldTypeDescription
totalintegerNumber of rows after filtering, across all pages. One row per device, and one row for a location with no device.
pageintegerPage number of this response.
countintegerPage size of this response.
resourcesobject[]The rows of this page.
resources[].locationIdstring (uuid)Location id.
resources[].locationNamestringLocation name.
resources[].organizationIdstring | nullZone id.
resources[].organizationNamestring | nullZone name.
resources[].deviceIdstring | nullThe row's device.
resources[].deviceNamestring | nullThe row's device name.
resources[].patientIdstring | nullResident on the row's device.
resources[].patientNamestring | nullThat resident's Resident ID (nickname).
resources[].occupiedbooleantrue when the row's device has a resident.
resources[].assignablebooleanAlways true.
resources[].warningCode"location_has_existing_resident" | nulllocation_has_existing_resident when occupied is true, otherwise null.

Errors

StatusMeaning
400Your session has no project (an admin token without one).
401Bearer token is missing, invalid or expired.
403You 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.
422A query parameter fails validation.

Last updated on

On this page