# Update patient

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

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

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

Updates a resident (patient): names, gender, birth date, placement on devices, room and zone, and resident state (discharge or reactivation).

**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 `Patient:update`, plus `Device:update` when the request changes which devices the resident is on (admins and super admins skip this check).
**Scope:** The resident must belong to the caller's project (from the token). Devices, rooms and zones you reference must be in your project, its parent project, or one of its sub-projects.

## Request [#request]

### Path parameters [#path-parameters]

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

### Body [#body]

Fields that are not listed here, such as `id`, `floor`, `room`, `bed` and `admissionDate`, are ignored. A `GET /v1/slim/patient/{id}` response is accepted as is.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `object[]` | Yes | Replaces all names. At least 1 entry. Must contain a `nickname` entry with a non-blank first `given` value. |
| `name[].use` | `"official"` \| `"nickname"` \| `"maiden"` | Yes | Kind of name. |
| `name[].given` | `string[]` | No | Given names, in order. |
| `name[].family` | `string` | No | Family name. `""` is accepted. |
| `gender` | `"male"` \| `"female"` \| `"other"` \| `"unknown"` \| `""` | No | Administrative gender. Omit or send `""` to clear. |
| `birthDate` | `string (YYYY-MM-DD)` \| `""` | No | Date of birth. Omit or send `""` to clear. |
| `locationId` | `string (uuid)` \| `""` | No | Room to place the resident in. Omit or send `""` to remove the resident from all devices. |
| `deviceId` | `string (uuid)` \| `string[]` \| `null` \| `""` | No | Device ids to place the resident on. When `locationId` is set, this must be a non-empty id or list; `null`, `""` or `[]` is refused. Omit or clear `locationId` to remove placement. |
| `organizationId` | `string (uuid)` \| `""` | No | Zone to place the resident in. When omitted, the resident takes the zone of their device: the room's zone, otherwise the device's own zone. |
| `residentState` | `"active"` \| `"discharged"` \| `"discharged-recent"` \| `"archived"` | No | `discharged` discharges an active resident. `active` reactivates a discharged one. Other values change nothing. |
| `dischargeDate` | `string` | No | Discharge time, stored as sent. Use ISO 8601. Defaults to now when discharging. |

## Behaviour [#behaviour]

The body is a full replacement of the editable fields, designed so that the result of `GET /v1/slim/patient/{id}` can be sent back unchanged. Fields the update does not declare, such as `id`, `floor` or `admissionDate`, are ignored.

- `name` replaces all of the resident's names. It must contain a `nickname` entry with a non-blank first `given` value. If the nickname changes, it must be unique in the project.
- Ovok stores `name[].given[]` and `name[].family` after trimming whitespace.
- `gender` and `birthDate` are replaced. Omitting them, or sending `""`, clears them.
- **Placement depends on `locationId`:**
  - **`locationId` omitted or `""`: the resident is removed from all of their devices**, and `deviceId` and `organizationId` are ignored. Send the current `locationId` to keep the placement.
  - `locationId` with `deviceId`: the resident is placed on those devices, and the devices move to the room. The resident leaves any other device. A resident already on one of those devices is replaced.
  - `locationId` without `deviceId`: the resident is placed on the room's device. The room must have exactly one device.
  - `organizationId`, when it differs from the current zone, moves the resident's devices, with their rooms and residents, into that zone.
  - A resident cannot be saved on devices from different zones (`422`, `path: ["deviceId"]`), unless the assignment already exactly matches those zones.
  - Without `organizationId`, the resident takes the zone of their device: the room's zone when the device is in a room, otherwise the device's own zone.
- `residentState`:
  - `discharged` on an active resident: the resident is tagged discharged, `dischargeDate` is stored (default: now), the `EpisodeOfCare` is finished, and the resident is removed from all devices. `locationId` must be omitted or `""`.
  - `discharged` on a resident already discharged: only a different `dischargeDate` has an effect; it corrects the stored date.
  - `active` on a discharged resident: the resident is reactivated, the latest `EpisodeOfCare` is reopened and `dischargeDate` is removed.
  - Other values, or the current state, change nothing.
- Any resident who loses a device in this request has their active out-of-bed notification revoked in the same write, and the device's live telemetry state is cleared afterwards.
- Archived residents cannot be updated.
- The write is atomic and takes a short write lock on the resident, the devices and, on a rename, the new Resident ID.
- Change-history entries are added for each changed field and assignment.
- The response is the resident after the update, in the same shape as `GET /v1/slim/patient/{id}`.

## Example [#example]

```bash
curl -X PUT 'https://api.sandbox.ovok.com/v1/slim/patient/3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21' \
  -H "Authorization: Bearer ${OVOK_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": [{ "use": "nickname", "given": ["demo-resident"] }],
    "gender": "male",
    "birthDate": "1940-05-01",
    "deviceId": "8c5e7a21-4b9d-4f36-a1c8-0d2e6b9f3a54",
    "locationId": "5d2a9c64-7e1b-4830-b6f5-9a3c1e8d7b02",
    "organizationId": "1e6b8d30-2c4f-4a95-8d7e-b0a2c4e6f918",
    "residentState": "active"
  }'
```

## Successful response [#successful-response]

`200` — Patient updated successfully.

```json
{
  "id": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21",
  "name": [
    { "use": "nickname", "given": ["demo-resident"], "family": "" }
  ],
  "gender": "male",
  "birthDate": "1940-05-01",
  "deviceId": "8c5e7a21-4b9d-4f36-a1c8-0d2e6b9f3a54",
  "organizationId": "1e6b8d30-2c4f-4a95-8d7e-b0a2c4e6f918",
  "locationId": "5d2a9c64-7e1b-4830-b6f5-9a3c1e8d7b02",
  "floor": "1",
  "room": "101",
  "bed": "A",
  "residentState": "active",
  "admissionDate": "2026-10-01T08:00:00.000Z"
}
```

The body is the resident after the update, as `GET /v1/slim/patient/{id}` returns it.

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` | Patient id. |
| `name` | `object[]` | The resident's names. A name stored without a `use` is returned as `official`. |
| `name[].use` | `"official"` \| `"nickname"` \| `"maiden"` | Kind of name. |
| `name[].given` | `string[]` | Given names. Empty array when none. |
| `name[].family` | `string` | Family name. Empty string when none. |
| `gender` | `"male"` \| `"female"` \| `"other"` \| `"unknown"` | Left out when not set. |
| `birthDate` | `string (YYYY-MM-DD)` | Left out when not set. |
| `deviceId` | `string (uuid) \| null` | The resident's device. `null` when the resident has no device. When there are several, the most recently updated one. |
| `organizationId` | `string (uuid)` | Zone of that device's room. Left out when there is none. |
| `locationId` | `string (uuid)` | Room of that device. Left out when there is none. |
| `floor` | `string` | Floor of the room. Left out when not set. |
| `room` | `string` | Room name or number. Left out when not set. |
| `bed` | `string` | Bed. Left out when not set. |
| `residentState` | `"active"` \| `"discharged-recent"` \| `"discharged"` \| `"archived"` | Resident state. |
| `admissionDate` | `string` | Admission time as stored. Left out when not set. |
| `dischargeDate` | `string` | Discharge time as stored. Left out when not set. |

## Errors [#errors]

| Status | Meaning |
| --- | --- |
| [`400`](/errors/malformed-request) | 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 `Patient:update` (or `Device:update` when the device assignment changes), the patient is outside your project, or a referenced device, location or zone does not exist or is outside your project, its parent or its sub-projects. |
| [`404`](/errors/not-found) | No patient with this id exists. |
| [`409`](/errors/conflict) | The project is moving to another Signals tenant, another write holds the patient, a device or the new Resident ID, or a device was reassigned while the request ran. Retry. |
| [`422`](/errors/validation-failed) | The body or `id` fails validation, the body has no Resident ID, the new Resident ID is already in use, the patient is archived, a discharge also sets `locationId`, a discharged resident is placed in a room, `locationId` is set with an empty `deviceId` (`path: ["deviceId"]`), the devices belong to different zones (`path: ["deviceId"]`), or `locationId` without `deviceId` names a room with no device or more than one. |
