List locations
- Sandbox: available
- Staging: available
- Production: unknown
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 (an admin or super admin who holds no access policy skips this check).
Scope: The caller's project (from the token). Only locations, devices and residents in that project are returned.
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.
totalcounts rows, not locations. patientIdandpatientNameare the resident assigned to that row's device.organizationIdandorganizationNameare the location's zone.searchmatches, 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,roomandbedmatch the location's codes exactly.organizationIdkeeps locations in that zone.deviceIdkeeps 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(default0) andcount(default20, max100). - 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 eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'bearerAuthorizationBearer <JWT>search?stringSearch locations by name, device name, patient name, or organization name.
1 <= lengthfloor?stringRestrict results to locations with the specified floor code.
1 <= lengthroom?stringRestrict results to locations with the specified room code.
1 <= lengthbed?stringRestrict results to locations with the specified bed code.
1 <= lengthorganizationId?stringRestrict results to locations managed by the specified organization.
1 <= lengthdeviceId?stringRestrict results to locations assigned to the specified device.
1 <= lengthpage?string"0"count?string"20"Locations retrieved successfully.
application/json- response
total*number0 <= valuepage*number0 <= valuecount*number1 <= valueresources*array<>curl -X GET 'https://api.sandbox.ovok.com/v1/slim/location'{ "total": 0, "page": 0, "count": 1, "resources": [ { "id": "string", "name": "string", "floor": "string", "room": "string", "bed": "string", "organizationId": "string", "organizationName": "string", "deviceName": "string", "patientName": "string", "deviceId": "string", "patientId": "string" } ]}List location assignment candidates GET
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` (an admin or super admin who holds no access policy skips 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 ```bash curl -X GET 'https://api.sandbox.ovok.com/v1/slim/location/assignment-candidates?occupied=vacant&count=50' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ``` ```json { "total": 1, "page": 0, "count": 50, "resources": [ { "locationId": "c3499c27-2973-0a7f-807e-fb8676a92dcb", "locationName": "Room 201 Bed 1", "organizationId": null, "organizationName": null, "deviceId": null, "deviceName": null, "patientId": null, "patientName": null, "occupied": false, "assignable": true, "warningCode": null } ] } ```
Create location POST
Creates a location (room or bed), optionally in a zone. **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:create` and `Device:update` (an admin or super admin who holds no access policy skips this check). **Scope:** The location is created in the caller's project (from the token). A super-admin caller can pass `?projectId=<uuid>` to create it in that project instead. Any other caller who passes `projectId` gets a 403. ## Behaviour - `name` must be unique. The check is an exact name match against the locations your token can search. With `?projectId`, the check runs in that project only. - When any of `floor`, `room` or `bed` is set, the combination of zone, floor, room and bed must also be unique. The comparison ignores case and extra whitespace. A location with only a name has no such check. - `floor`, `room` and `bed` are stored as type codes on the location. `organizationId` sets the zone. The zone must be in your project, one of its sub-projects, or its parent project. - The create is guarded against a concurrent create of the same floor, room and bed. If another request creates it first, you get a 409 that names the existing location. - No devices or residents are attached. Use `PUT /v1/slim/location/{id}` for that. - A location-created entry is added to the change history. A failure to write that entry does not fail the request. - The response is the created location, in the same shape as `GET /v1/slim/location/{id}`. - If a location with the same zone, floor, room and bed exists, the request is refused with 409 and the body carries `existingLocationId` and `existingLocationName`. ## Example ```bash curl -X POST 'https://api.sandbox.ovok.com/v1/slim/location' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \ -H 'Content-Type: application/json' \ -d '{ "name": "Room 201", "floor": "2", "room": "201", "bed": "A", "organizationId": "87ea5dfc-8b8e-384d-8489-79496e706390" }' ```