# Update device

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

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

[Authentication](/authentication) · [Access policies](/access-policies)

Updates a device's name and identifier, and assigns or unassigns its zone, location and resident.

**Auth:** bearer token. The caller must be a practitioner, an admin or a System Owner, and needs `Device:update`.
**Scope:** the device must belong to the caller's project (from the token).

## Request [#request]

### Path parameters [#path-parameters]

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

### Body [#body]

The body is strict: a field that is not listed here fails validation.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Yes | Device serial and user-friendly name. At least 1 character. A serial used by another customer is refused with `409`. |
| `thingsboardId` | `string` | No | Device identifier that telemetry is keyed by. At least 1 character. Omit to keep it. |
| `organizationId` | `string (uuid)` \| `null` | No | Zone to assign. `null` unassigns. When the device has a room, this must match the room's zone. Omit to keep it. |
| `locationId` | `string (uuid)` \| `null` | No | Location to assign. `null` unassigns. Omit to keep it. |
| `patientId` | `string (uuid)` \| `null` | No | Resident to assign. `null` unassigns. Omit to keep it. |

## Behaviour [#behaviour]

- `name` is required. Renaming moves the device serial: readings sent under the old serial no longer reach it. Until the first reading under the new serial, the renamed device has no live values. Ovok keeps `lastSeen`; the live row `id`, `device.identifier` and `/v1/slim/device/live/telemetry` key become the new serial.
- `thingsboardId` can be set once. A device that already has a different one refuses the change with 400.
- For `organizationId`, `locationId` and `patientId`: omit the field to leave it unchanged, send `null` to unassign, or send a UUID to assign.
- A device in a room takes the room's zone. If `organizationId` differs from that zone (the room in this request, or its current room when `locationId` is omitted), the request is refused with `422` and nothing changes. A device without a room, or in a room without a zone, can use any zone. A zone change applies only to the device.
- Assigning a resident moves them: the resident is removed from every other device they hold. The resident who was on this device before loses it. Each resident who loses a device has their active out-of-bed episode closed in the same transaction.
- All changes are written in one transaction. If any part fails, nothing is written.
- Sending values the device already has is not an error, and writes nothing.
- Resident assignment changes, renames, zone changes and room moves are recorded in the change history. A change of `thingsboardId` is not.
- The response is the same as `GET /v1/slim/device/{id}` after the update.

## Example [#example]

```bash
curl -X PUT 'https://api.sandbox.ovok.com/v1/slim/device/8c5e7a21-4b9d-4f36-a1c8-0d2e6b9f3a54' \
  -H "Authorization: Bearer ${OVOK_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{"name": "Demo/1000001", "patientId": null}'
```

## Successful response [#successful-response]

`200` — The updated device.

```json
{
  "id": "8c5e7a21-4b9d-4f36-a1c8-0d2e6b9f3a54",
  "name": "Demo/1000001",
  "status": "active",
  "statusReason": [],
  "thingsboardId": "Demo/1000001",
  "organizationId": "1e6b8d30-2c4f-4a95-8d7e-b0a2c4e6f918",
  "organizationName": "Zone A",
  "locationId": "5d2a9c64-7e1b-4830-b6f5-9a3c1e8d7b02",
  "locationName": "Room 101 Bed 1",
  "patientName": null,
  "floor": "1",
  "room": "101",
  "bed": "1"
}
```

The body is the device after the update, as `GET /v1/slim/device/{id}` returns it. The example shows the device after `patientId` was set to `null`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` | Device id. |
| `name` | `string` | Device name. Empty string when it has none. |
| `status` | `"active"` \| `"inactive"` \| `"entered-in-error"` \| `"unknown"` | Connection status. Left out when unknown. |
| `statusReason` | `object[]` | Why the platform marked the device, when it did. Empty array when nothing was recorded. |
| `statusReason[].code` | `string` | Reason code, such as `no-assigned-resident`. Stable. Render from this. |
| `statusReason[].display` | `string \| null` | A sentence for the code. `null` for a code that has none. |
| `thingsboardId` | `string` | Device identifier that telemetry is keyed by. Left out when the device has none. |
| `organizationId` | `string (uuid)` | Zone id. Left out when there is none. |
| `organizationName` | `string \| null` | Zone name. |
| `locationId` | `string (uuid)` | Location id. Left out when there is none. |
| `locationName` | `string \| null` | Location name. |
| `patientId` | `string (uuid)` | Resident id. Left out when there is none. |
| `patientName` | `string \| null` | The resident's full display name. |
| `floor` | `string` | Floor code of the location. Left out when not set. |
| `room` | `string` | Room code of the location. Left out when not set. |
| `bed` | `string` | Bed code of the location. Left out when not set. |

## Errors [#errors]

| Status | Meaning |
| --- | --- |
| [`400`](/errors/malformed-request) | A zone, location or resident in the body does not exist, `thingsboardId` differs from the one the device already has, 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 `Device:update`, your session has no project, or the device is not in your project. |
| [`404`](/errors/not-found) | No device with this `id` exists. |
| [`409`](/errors/conflict) | You change `patientId` or `locationId` while your project is moving to another Signals tenant. Retry when the move is done. |
| [`409`](/errors/conflict) | `This device serial is in use by another customer.` (`path: ["name"]`). This check runs before the zone validation. |
| [`422`](/errors/validation-failed) | The body fails validation, another device in this project already uses the serial (including a `DeviceID` identifier equal to `name`), the zone does not match the room's zone (`path: ["organizationId"]`), or you assign a location to a discharged resident. |
