# Update location

Canonical page: https://docs.ovok.com/slim-apis/location/update-location

| Method | Path |
| --- | --- |
| `PUT` | `/v1/slim/location/:id` |

[Authentication](/authentication) · [Access policies](/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.

## Request [#request]

### Path parameters [#path-parameters]

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string (uuid)` | Yes | Location id. |

### Body [#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. Omit to keep the current one. |
| `room` | `string` | No | Room code. Omit to keep the current one. |
| `bed` | `string` | No | Bed code. Omit to keep the current one. |
| `organizationId` | `string` \| `null` | No | Zone to move the location to. `null` removes the zone. Omit to keep it. |
| `deviceId` | `string (uuid)` \| `string[]` \| `null` | No | The full set of devices at the location. `null` or `[]` detaches all devices. Omit to keep them. |
| `patientId` | `string (uuid)` | No | Resident to place on the devices. Omit it to remove every resident from the devices. |

## Behaviour [#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`: clears the zone from the room, its devices and its residents.
  - an id: sets the zone on the room and its devices. A resident removed from a device in the same save keeps their zone.
- `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 added to the room take its zone; devices taken out keep their current zone.
  - 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.
- Each change to the name, floor, room, bed or zone adds an entry to the change history. A save that changes none of them adds none. 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}`.

## Example [#example]

```bash
curl -X PUT 'https://api.sandbox.ovok.com/v1/slim/location/5d2a9c64-7e1b-4830-b6f5-9a3c1e8d7b02' \
  -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",
    "deviceId": ["8c5e7a21-4b9d-4f36-a1c8-0d2e6b9f3a54"],
    "patientId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21"
  }'
```

## Successful response [#successful-response]

`200` — Location updated successfully.

```json
{
  "id": "5d2a9c64-7e1b-4830-b6f5-9a3c1e8d7b02",
  "name": "Room 201",
  "floor": "2",
  "room": "201",
  "bed": "A",
  "organizationId": "1e6b8d30-2c4f-4a95-8d7e-b0a2c4e6f918",
  "organizationName": "Zone A",
  "patientId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21",
  "patientName": "demo-resident",
  "deviceId": ["8c5e7a21-4b9d-4f36-a1c8-0d2e6b9f3a54"],
  "deviceName": "Demo/1000001"
}
```

The body is the location after the update, 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 [#errors]

| Status | Meaning |
| --- | --- |
| [`400`](/errors/malformed-request) | A referenced zone, device or resident does not exist, or the FHIR backend refuses the write. |
| [`401`](/errors/unauthenticated) | Bearer token is missing, invalid or expired. |
| [`403`](/errors/forbidden) | You are not a practitioner, admin or System Owner, you lack `Location:update` or `Device:update`, the location is outside your project, or a referenced device that you can read is outside your project scope. |
| [`404`](/errors/not-found) | No location with this id exists. |
| [`409`](/errors/conflict) | Another location in the zone already has the same floor, room and bed (the body names it in `existingLocationId` and `existingLocationName`), another write holds one of the devices, or a device was reassigned while the request ran. |
| [`422`](/errors/validation-failed) | The body or `id` fails validation, another location has the same name, `deviceId` names a device the caller cannot read (`Device not found: <id>[, <id>]`; nothing is committed), a discharged resident would be placed here, or `patientId` without `deviceId` meets a room with no device or more than one. |
