Update location

Method	Path
PUT	/v1/slim/location/:id

Authentication · Access policies

Updates a location: its name, floor, room, bed and zone, the devices at it, and the resident on those devices.

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:update and Device:update (admins and super admins skip this check). Scope: The location must belong to the caller's project (from the token). Devices and residents you attach must be in your project or one of its sub-projects. The zone must be in your project, a sub-project, or the parent project.

Behaviour

• name is required and must be unique among the locations your token can search, not counting this one.
• floor, room, bed: an omitted field keeps its current value. If the zone, floor, room or bed changes, the new combination must not match another location's.
• organizationId:
  • omitted: the zone is unchanged.
  • null: the zone is removed from the location and from every device at it.
  • an id: the location and every device at it move to that zone. Residents on those devices move too.
• deviceId (one id or a list):
  • omitted: the devices at the location are unchanged.
  • a list: it becomes the full set of devices at the location. Devices not in the list are detached; new ones are attached. null or [] detaches all devices.
  • Devices that hold a discharged resident cannot be attached.
• patientId:
  • an id: that resident is assigned to the devices in deviceId, or, when deviceId is omitted or empty, to the single device at the location. The resident is first removed from any other device. A resident already on a target device is replaced. A discharged resident is refused.
  • omitted: every resident is removed from every device at the location and every device in deviceId. To keep the current resident, send their patientId.
• A resident who loses a device has their active out-of-bed notification revoked in the same write, and the device's live telemetry state is cleared afterwards.
• Device use history is updated for every device whose resident changes.
• The write is atomic and takes a short write lock. A concurrent write to the same resources, or a device reassigned by someone else while this request ran, gets a 409.
• Every save adds a location-updated entry to the change history. Residents who move into a new zone, or lose a device, also get an entry in their own change history.
• The response is the location after the update, in the same shape as GET /v1/slim/location/{id}.
• If another location has the same zone, floor, room and bed, the request is refused with 409 and the body carries existingLocationId and existingLocationName.

Example

curl -X PUT 'https://api.sandbox.ovok.com/v1/slim/location/3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21' \
  -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",
    "deviceId": ["3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21"],
    "patientId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21"
  }'

Successful response

200 — Location updated successfully.

Errors

Status	Meaning
400	A referenced zone, device or resident does not exist, or Medplum refuses the write.
401	Bearer token is missing, invalid or expired.
403	You are not a practitioner, admin or System Owner, you lack Location:update or Device:update, the location is outside your project, or a device at the location or a referenced zone, device or resident is outside your project scope.
404	No location with this id exists.
409	Another location in the zone already has the same floor, room and bed (named in existingLocationId), another write holds one of the devices, or a device was reassigned while the request ran.
422	The body or id fails validation, another location has the same name, a discharged resident would be placed here, or patientId without deviceId meets a room with no device or more than one.