Skip to main content

Create location

MethodPath
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.

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​

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": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21"
  }'

Successful response​

201 — Location created successfully.

Errors​

StatusMeaning
400organizationId names no zone you can read, or Medplum refuses the location.
401Bearer token is missing, invalid or expired.
403You 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.
409Another location in the zone already has the same floor, room and bed. The body names it in existingLocationId.
422The body or projectId fails validation, projectId names no project, or another location has the same name.