Locations

List locations

List locations using Ovok’s Slim API.

MethodPath
GET/v1/slim/location

Authentication · 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

Query parameters

Unknown query parameters are rejected with 422.

NameTypeRequiredDescription
pageintegerNoZero-based page number. Default 0, minimum 0.
countintegerNoRows per page. Default 20, minimum 1, maximum 100.
searchstringNoCase-insensitive substring match on location name, device name, resident name and zone name. Trimmed, at least 1 character.
floorstringNoKeep locations with exactly this floor code.
roomstringNoKeep locations with exactly this room code.
bedstringNoKeep locations with exactly this bed code.
organizationIdstringNoKeep locations in this zone.
deviceIdstringNoKeep only the row for this device.

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

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

200 — Locations retrieved successfully.

{
  "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"
    }
  ]
}
FieldTypeDescription
totalintegerNumber of rows after filtering, across all pages. One row per device, so a location can count more than once.
pageintegerPage number of this response.
countintegerPage size of this response.
resourcesobject[]The rows of this page.
resources[].idstring (uuid)Location id.
resources[].namestringLocation name. Empty string when it has none.
resources[].floorstringFloor code. Left out when not set.
resources[].roomstringRoom code. Left out when not set.
resources[].bedstringBed code. Left out when not set.
resources[].organizationIdstring (uuid)Zone id. Left out when the location has no zone.
resources[].organizationNamestringZone name. Left out when the location has no zone.
resources[].deviceIdstring (uuid)The row's device. Left out for a location with no device.
resources[].deviceNamestringThe row's device name. Left out for a location with no device.
resources[].patientIdstring (uuid)Resident on the row's device. Left out when there is none.
resources[].patientNamestringThat resident's Resident ID (nickname). Left out when there is none.

Errors

StatusMeaning
400Your session has no project.
401Bearer token is missing, invalid or expired.
403You are not a practitioner, admin or System Owner, or you lack Location:search or Location:read.
422A query parameter fails validation.

Last updated on

On this page