Create location
Create location using Ovok’s Slim API.
| Method | Path |
|---|---|
POST | /v1/slim/location |
Authentication · Access policies
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 (admins and super admins skip 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.
Request
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string (uuid) | No | Create the location in this project. Super admins only. Must name an existing project. |
Body
The body is strict: a field that is not listed here fails validation.
| Name | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Location name. At least 1 character. Must be unique. |
floor | string | No | Floor code. |
room | string | No | Room code. |
bed | string | No | Bed code. |
organizationId | string | No | Id of the zone the location belongs to. |
Behaviour
namemust 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,roomorbedis 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,roomandbedare stored as type codes on the location.organizationIdsets 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}.
Example
curl -X POST 'https://api.sandbox.ovok.com/v1/slim/location' \
-H "Authorization: Bearer ${OVOK_TOKEN}" \
-H 'Content-Type: application/json' \
-d '{
"name": "Room 201",
"floor": "2",
"room": "201",
"bed": "A",
"organizationId": "1e6b8d30-2c4f-4a95-8d7e-b0a2c4e6f918"
}'Successful response
201 — Location created successfully.
{
"id": "5d2a9c64-7e1b-4830-b6f5-9a3c1e8d7b02",
"name": "Room 201",
"floor": "2",
"room": "201",
"bed": "A",
"organizationId": "1e6b8d30-2c4f-4a95-8d7e-b0a2c4e6f918",
"organizationName": "Zone A"
}The body is the created location, as GET /v1/slim/location/{id} returns it.
| Field | Type | Description |
|---|---|---|
id | string (uuid) | Location id. |
name | string | Location name. Empty string when the location has none. |
floor | string | Floor code. Left out when not set. |
room | string | Room code. Left out when not set. |
bed | string | Bed code. Left out when not set. |
organizationId | string (uuid) | Zone id. Left out when the location has no zone. |
organizationName | string | Zone name. Left out when the location has no zone. |
deviceId | string[] | Ids of every device at the location. Left out when there is none. |
deviceName | string | Alphabetically first name among the devices at the location. Left out when there is none. |
patientId | string (uuid) | Resident on the first device at the location that has one. Left out when there is none. |
patientName | string | That resident's name. Left out when there is none. |
Errors
| Status | Meaning |
|---|---|
400 | organizationId names no zone you can read, or the FHIR backend refuses the location. |
401 | Bearer token is missing, invalid or expired. |
403 | You are not a practitioner, admin or System Owner, you lack Location:create or Device:update, you set projectId without being a super admin, or the zone is outside your project, its parent or its sub-projects. |
409 | Another location in the zone already has the same floor, room and bed. The body names it in existingLocationId and existingLocationName. |
422 | The body or projectId fails validation, projectId names no project, or another location has the same name. |
Last updated on