Zones

Create location in zone

Create location in zone using Ovok’s Slim API.

MethodPath
POST/v1/slim/zones/:zoneId/locations

Authentication · Access policies

Creates a location (a FHIR Location) inside a zone. The new location's managing organization is the 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 may pass ?projectId=<uuid> to create it in that project instead; the project must exist. The zone must belong to the project in use, its parent project, or one of its sub-projects.

Request

Path parameters

NameTypeRequiredDescription
zoneIdstring (uuid)YesZone (organization) id.

Query parameters

NameTypeRequiredDescription
projectIdstring (uuid)NoCreate 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.

NameTypeRequiredDescription
namestringYesLocation name. At least 1 character. Must be unique.
floorstringNoFloor code.
roomstringNoRoom code.
bedstringNoBed code.

Behaviour

  • name is required and must be unique among the locations your token can search.
  • floor, room and bed are optional. When at least one is set, no other location in the zone may have the same floor, room and bed. A location with none of them is checked by name only.
  • The location is created with no devices or residents. Assign them with PUT /v1/slim/zones/{zoneId}/locations/{locationId}.
  • 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 new location, in the same shape as GET /v1/slim/location/{id}.

Example

curl -X POST 'https://api.sandbox.ovok.com/v1/slim/zones/1e6b8d30-2c4f-4a95-8d7e-b0a2c4e6f918/locations' \
  -H "Authorization: Bearer ${OVOK_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Room 101 Bed 1",
    "floor": "1",
    "room": "101",
    "bed": "1"
  }'

Successful response

201 — Location created in zone.

{
  "id": "5d2a9c64-7e1b-4830-b6f5-9a3c1e8d7b02",
  "name": "Room 101 Bed 1",
  "floor": "1",
  "room": "101",
  "bed": "1",
  "organizationId": "1e6b8d30-2c4f-4a95-8d7e-b0a2c4e6f918",
  "organizationName": "Zone A"
}

The body is the created location, as GET /v1/slim/location/{id} returns it.

FieldTypeDescription
idstring (uuid)Location id.
namestringLocation name. Empty string when the location has none.
floorstringFloor code. Left out when not set.
roomstringRoom code. Left out when not set.
bedstringBed code. Left out when not set.
organizationIdstring (uuid)Zone id. Left out when the location has no zone.
organizationNamestringZone name. Left out when the location has no zone.
deviceIdstring[]Ids of every device at the location. Left out when there is none.
deviceNamestringAlphabetically first name among the devices at the location. Left out when there is none.
patientIdstring (uuid)Resident on the first device at the location that has one. Left out when there is none.
patientNamestringThat resident's name. Left out when there is none.

Errors

StatusMeaning
401Bearer token is missing, invalid or expired.
403You are not a practitioner, admin or System Owner, you lack Location:create or Device:update, projectId is set by a caller who is not a super admin, your session has no project, or the zone is outside your project tree or carries no project.
404No zone with this zoneId exists.
409A location with the same floor, room and bed already exists in this zone. The body names it in existingLocationId and existingLocationName.
422zoneId is not a UUID, the body fails validation, projectId is not a UUID or names no project, or a location with the same name already exists.

Last updated on

On this page