# Update a person profile

Operation ID: `person.updatePerson`

Patch mutable fields on a Person profile by FHIR resource ID. Only keys UpdatePersonRequest declares are ever written; any other body key is silently ignored. `notes` is accepted but is not currently serialized through the FHIR Person mapper, so its returned value is null; use a persisted profile field or `person.updatePersonAttributes` for application metadata. Scoped to the caller's tenant (resolved from the Bearer JWT).

## Public method

`update`

Signature: `person.update(fhirPersonId, request)`

Return type: `Promise<Person>`

## Authentication

Classification: **AUTHENTICATED**

Schemes: `bearerAuth`

## Prerequisites

None documented.

## HTTP

`PATCH /persons/{person_id}`

## Path parameters

| Name | Type | Required | Format | Allowed values | Default | Nullable | Description |
|---|---|---:|---|---|---|---:|---|
| `person_id` | `string` | Yes |  |  |  | No |  |

## Query parameters

None.

## Body parameters

| Name | Type | Required | Format | Allowed values | Default | Nullable | Description |
|---|---|---:|---|---|---|---:|---|
| `body` | [`UpdatePersonRequest`](../models/UpdatePersonRequest.md) | No |  |  |  | Yes |  |

Request model: [`UpdatePersonRequest`](../models/UpdatePersonRequest.md)

## Request example

```json
{
  "active": true,
  "address": {
    "city": "Boston",
    "country": "US",
    "is_primary": true,
    "state": "MA",
    "street1": "100 Example Avenue",
    "street2": "Apt 4B",
    "type": "home",
    "zip_code": "02108"
  },
  "birth_date": "1990-01-01",
  "email": "person.user@example.com",
  "first_name": "Alex",
  "gender": "female",
  "last_name": "Smith",
  "linked_patient_ids": [
    "patient-example-001"
  ],
  "linked_practitioner_ids": [
    "practitioner-example-001"
  ],
  "middle_name": "Jordan",
  "notes": "Non-persistent example note",
  "phone": "+15550100000",
  "prefix": "Ms.",
  "race": [
    "white"
  ],
  "relationship": "caregiver",
  "suffix": "Jr."
}
```

## Success responses

| Status | Shape | Content type | Description |
|---|---|---|---|
| `200` | [`UpdatePersonResponse`](../models/UpdatePersonResponse.md) | application/json | Updated person profile |

## Success response examples

### 200

```json
{
  "active": true,
  "address": {
    "city": "Boston",
    "country": "US",
    "is_primary": true,
    "state": "MA",
    "street1": "100 Example Avenue",
    "street2": "Apt 4B",
    "type": "home",
    "zip_code": "02108"
  },
  "attributes": {},
  "birth_date": "1990-01-01",
  "cognito_sub": "00000000-0000-4000-8000-000000000000",
  "email": "person.user@example.com",
  "fhir_id": "person-example-001",
  "first_name": "Alex",
  "gender": "female",
  "last_name": "Smith",
  "linked_patient_ids": [
    "patient-example-001"
  ],
  "linked_practitioner_ids": [
    "practitioner-example-001"
  ],
  "middle_name": "Jordan",
  "notes": null,
  "person_id": "00000000-0000-4000-8000-000000000000",
  "person_type": "caregiver",
  "phone": "+15550100000",
  "prefix": "Ms.",
  "race": [
    "white"
  ],
  "relationship": "caregiver",
  "suffix": "Jr.",
  "tenant_id": "tenant-example-001"
}
```

## Common errors

| Status | Shape | Content type | Description |
|---|---|---|---|
| `400` | [`person.ErrorResponse`](../models/person.ErrorResponse.md) | application/json | The update failed (sanitized example) |
| `401` | [`person.ErrorResponse`](../models/person.ErrorResponse.md) | application/json | Authorization required — missing or invalid Bearer JWT |
| `404` | [`person.ErrorResponse`](../models/person.ErrorResponse.md) | application/json | No Person resource exists for person_id |

## Error examples

### 400 — Downstream update failure (sanitized example)

```json
{
  "error": "Bad Request"
}
```

### 401 — Missing or invalid access token

```json
{
  "error": "Authorization required"
}
```

### 404 — No Person resource matches person_id

```json
{
  "error": "Person not found"
}
```

## NodeJS / TypeScript implementation

```ts
import { HCSDK } from "@healthcloudai/hc-sdk";
import type { UpdatePersonRequest } from "@healthcloudai/hc-sdk";
```

```ts
const fhirPersonId = "<FHIR_PERSON_ID>";

const request = {
  "active": true,
  "address": {
    "city": "Boston",
    "country": "US",
    "is_primary": true,
    "state": "MA",
    "street1": "100 Example Avenue",
    "street2": "Apt 4B",
    "type": "home",
    "zip_code": "02108"
  },
  "birth_date": "1990-01-01",
  "email": "person.user@example.com",
  "first_name": "Alex",
  "gender": "female",
  "last_name": "Smith",
  "linked_patient_ids": [
    "patient-example-001"
  ],
  "linked_practitioner_ids": [
    "practitioner-example-001"
  ],
  "middle_name": "Jordan",
  "notes": "Non-persistent example note",
  "phone": "+15550100000",
  "prefix": "Ms.",
  "race": [
    "white"
  ],
  "relationship": "caregiver",
  "suffix": "Jr."
};

const result = await person.update(fhirPersonId, request);
```

## cURL

```bash
curl -X PATCH \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{"active":true,"address":{"city":"Boston","country":"US","is_primary":true,"state":"MA","street1":"100 Example Avenue","street2":"Apt 4B","type":"home","zip_code":"02108"},"birth_date":"1990-01-01","email":"person.user@example.com","first_name":"Alex","gender":"female","last_name":"Smith","linked_patient_ids":["patient-example-001"],"linked_practitioner_ids":["practitioner-example-001"],"middle_name":"Jordan","notes":"Non-persistent example note","phone":"+15550100000","prefix":"Ms.","race":["white"],"relationship":"caregiver","suffix":"Jr."}' \
  'https://dev-api-person.health.cloud/persons/%3CPERSON_ID%3E'
```

## Notes

None.

## Prepared Test Console scenario

No canonical scenario is currently associated.

## Real response

No approved real integration response is currently published. Unapproved candidates are never rendered as examples.