> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usecobalt.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Update Patient
> Updates an existing patient. The update process differs based on the current status of the patient.
**Use the Cobalt `id` in the URL path.** The `{id}` parameter should be the Cobalt patient ID returned from API responses or GET endpoints, not the MRN or EHR ID.
The update process differs based on the current status of the patient:
### 1. Updating Pending or Failed Patients
For patients with a status of 'pending' or 'failed', the patient does not yet exist in the EHR. You can update any attribute, and the new values will be used the next time the patient creation runs.
| Parameter | Type | Required | Description |
| --------------------- | ------ | -------- | --------------------------------------------------------------------- |
| Any patient attribute | varies | No | Any attribute of the patient can be updated. All fields are optional. |
### 2. Updating Active Patients
For patients with a status of 'active' (already created in the EHR), you can update the patient's contact information, address, and provider assignments. The change is queued and applied to the EHR asynchronously; the patient's status will move to 'pending\_update' while the update is in flight and back to 'active' once the EHR write completes.
#### Contact & Address Fields
| Parameter | Type | Required | Description |
| ----------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `phone` | string | No | Home phone, formatted as `222-333-4444`. |
| `cell_phone` | string | No | Cell phone, formatted as `222-333-4444`. |
| `email` | string | No | Patient email address. |
| `address_street` | string | No | Street address line 1. |
| `address_line2` | string | No | Address line 2 (apartment, suite, unit, etc.). |
| `address_city` | string | No | City. |
| `address_state` | string | No | Two-letter state code (e.g. `CA`). DC is accepted. |
| `address_zip` | string | No | ZIP code. Accepts 5-digit (`12345`) or ZIP+4 (`12345-6789`) formats. |
| `save_previous_address` | boolean | No | When `true` (default), the patient's current address is saved as address history in the EHR before the new address is applied. Set to `false` to overwrite without preserving history. eClinicalWorks only. |
#### Provider Fields (eClinicalWorks Only)
| Parameter | Type | Required | Description |
| ------------------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `referring_provider_first_name` | string | No | Referring provider's first name. Must be used with `referring_provider_last_name`. |
| `referring_provider_last_name` | string | No | Referring provider's last name. Must be used with `referring_provider_first_name`. |
| `referring_provider_id` | string | No | Cobalt referring provider UUID (from `GET /v1/referring-providers`). Looks up the provider's name and contact info for more accurate matching. |
| `pcp_first_name` | string | No | PCP's first name. Must be used with `pcp_last_name`. |
| `pcp_last_name` | string | No | PCP's last name. Must be used with `pcp_first_name`. |
| `pcp_id` | string | No | Cobalt referring provider UUID (from `GET /v1/referring-providers`). Looks up the provider's name and contact info for more accurate matching. |
| `referred_to_provider_id` | string | No | Rendering provider EHR ID — use the `ehr_id` value from `GET /v1/providers` (not the `id`). |
#### Demographics & Contact Preference Fields (eClinicalWorks Only)
| Parameter | Type | Required | Description |
| --------------- | ------- | -------- | ------------------------------------------------------------------------------------------- |
| `language` | string | No | Patient preferred language. Must match a valid language name in your eCW instance. |
| `race` | string | No | Patient race. Must match a valid race name in your eCW instance. |
| `ethnicity` | string | No | Patient ethnicity. Must match a valid ethnicity code or display name in your eCW instance. |
| `voice_enabled` | boolean | No | Enables or disables voice (phone) notifications in the eCW Patient Communications settings. |
| `text_enabled` | boolean | No | Enables or disables text (SMS) notifications in the eCW Patient Communications settings. |
**Notification language.** When `voice_enabled` or `text_enabled` is set, the notification language in eCW follows the patient's `language` (using the new value if `language` is included in the same request, otherwise the patient's current language): Spanish when `language` contains "spanish" (case-insensitive), otherwise English. These are the only two options eCW exposes for communication notifications.
Contact/address fields, provider fields, demographics, and contact preferences are applied independently. If one group is rejected by the EHR (for example a provider name that cannot be resolved, or a record the EHR will not let you modify), the other groups in the same request are still applied. Anything that could not be applied is returned in a `failed_fields` array on the `patient.updated` webhook, along with a human-readable `message`. If no fields could be applied, the request fails and a `patient.update_failed` webhook is sent instead. Use `referring_provider_id` or `pcp_id` instead of names when possible, as ID-based resolution is more reliable.
At least one data field must be provided.
### Example Request for Updating a Pending/Failed Patient
```bash theme={null}
curl -X PATCH https://api.usecobalt.com/v1/patients/65ed04f9d25fca3876f367d9ad94e3c3 \
-H 'Content-Type: application/json' \
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh' \
-H 'access_token: 493JKLHIU98789hLKH9HHJH' \
-d '{
"phone": "555-987-6543",
"insurance_name": "Aetna",
"insurance_subscriber_number": "ABC987654321"
}'
```
### Example Request for Updating an Active Patient's Contact Info
```bash theme={null}
curl -X PATCH https://api.usecobalt.com/v1/patients/65ed04f9d25fca3876f367d9ad94e3c3 \
-H 'Content-Type: application/json' \
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh' \
-H 'access_token: 493JKLHIU98789hLKH9HHJH' \
-d '{
"phone": "555-987-6543",
"cell_phone": "555-987-6544",
"email": "patient@example.com"
}'
```
### Example Request for Updating an Active Patient's Address
```bash theme={null}
curl -X PATCH https://api.usecobalt.com/v1/patients/65ed04f9d25fca3876f367d9ad94e3c3 \
-H 'Content-Type: application/json' \
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh' \
-H 'access_token: 493JKLHIU98789hLKH9HHJH' \
-d '{
"address_street": "456 New St",
"address_line2": "Apt 7",
"address_city": "Austin",
"address_state": "TX",
"address_zip": "78701"
}'
```
To update the address without saving the previous address as history, pass `save_previous_address: false`:
```bash theme={null}
curl -X PATCH https://api.usecobalt.com/v1/patients/65ed04f9d25fca3876f367d9ad94e3c3 \
-H 'Content-Type: application/json' \
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh' \
-H 'access_token: 493JKLHIU98789hLKH9HHJH' \
-d '{
"address_street": "456 New St",
"address_city": "Austin",
"address_state": "TX",
"address_zip": "78701",
"save_previous_address": false
}'
```
### Example Request for Updating an Active Patient's Providers
```bash theme={null}
curl -X PATCH https://api.usecobalt.com/v1/patients/65ed04f9d25fca3876f367d9ad94e3c3 \
-H 'Content-Type: application/json' \
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh' \
-H 'access_token: 493JKLHIU98789hLKH9HHJH' \
-d '{
"referring_provider_id": "e35e82b85df58f08a9b38e06a91e9f1a",
"pcp_id": "223ecd1b29e546ca9db6b391eb49b213",
"referred_to_provider_id": "82749"
}'
```
Or using names instead of IDs:
```bash theme={null}
curl -X PATCH https://api.usecobalt.com/v1/patients/65ed04f9d25fca3876f367d9ad94e3c3 \
-H 'Content-Type: application/json' \
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh' \
-H 'access_token: 493JKLHIU98789hLKH9HHJH' \
-d '{
"referring_provider_first_name": "Jane",
"referring_provider_last_name": "Doe",
"pcp_first_name": "Robert",
"pcp_last_name": "Johnson"
}'
```
### Example Request for Updating an Active Patient's Demographics & Contact Preferences
```bash theme={null}
curl -X PATCH https://api.usecobalt.com/v1/patients/65ed04f9d25fca3876f367d9ad94e3c3 \
-H 'Content-Type: application/json' \
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh' \
-H 'access_token: 493JKLHIU98789hLKH9HHJH' \
-d '{
"language": "Spanish",
"race": "White",
"ethnicity": "Hispanic or Latino",
"voice_enabled": true,
"text_enabled": true
}'
```
### Example Response
```json theme={null}
{
"success": true,
"message": "Patient update queued."
}
```
Only include the fields you want to update in the request body. Omitted fields will remain unchanged.
## OpenAPI
````yaml PATCH /patients/{id}
openapi: 3.0.0
info:
title: Cobalt API
version: 1.0.1
description: API for interacting with Cobalt's EHR integration services
servers:
- url: https://api.usecobalt.com/v1
security:
- ClientCredentials: []
ClientSecret: []
AccessToken: []
paths:
/patients/{id}:
patch:
summary: Update Patient
description: >-
Updates an existing patient. The update process differs based on the
current status of the patient.
parameters:
- in: path
name: id
required: true
schema:
type: string
description: The patient's ID
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- type: object
properties:
address_city:
type: string
address_line2:
type: string
description: Address line 2 (apartment, suite, unit, etc.)
address_state:
type: string
address_street:
type: string
address_zip:
type: string
cell_phone:
type: string
dob:
type: string
format: date
email:
type: string
description: Patient email address
first_name:
type: string
insurance_name:
type: string
insurance_sequence:
type: string
enum:
- primary
- secondary
- tertiary
insurance_subscriber_number:
type: string
last_name:
type: string
phone:
type: string
referred_to_provider_id:
type: string
description: >-
The ehr_id of the provider this patient is being
referred to (rendering provider). Use the ehr_id from
GET /v1/providers
referring_provider_first_name:
type: string
description: First name of the referring provider
referring_provider_last_name:
type: string
description: Last name of the referring provider
referring_provider_id:
type: string
description: >-
The id of a referring provider from GET
/v1/referring-providers (UUID without dashes). Can be
used instead of referring_provider_first_name and
referring_provider_last_name. Currently only supported
for eClinicalWorks.
sex:
type: string
enum:
- male
- female
- unknown
description: >-
Updates for pending/failed patients. Any allowed attribute
can be updated; values are used the next time patient
creation runs against the EHR.
- type: object
description: >-
Updates for active patients. The change is queued and
applied to the EHR asynchronously; status moves to
pending_update while in flight.
properties:
phone:
type: string
description: Home phone, formatted as 222-333-4444.
cell_phone:
type: string
description: Cell phone, formatted as 222-333-4444.
email:
type: string
description: Patient email address.
address_street:
type: string
description: Street address line 1.
address_line2:
type: string
description: Address line 2 (apartment, suite, unit, etc.).
address_city:
type: string
description: City.
address_state:
type: string
description: Two-letter state code (e.g. CA). DC is accepted.
address_zip:
type: string
description: >-
ZIP code. Accepts 5-digit (12345) or ZIP+4 (12345-6789)
formats.
save_previous_address:
type: boolean
default: true
description: >-
When true (default), the patient's current address is
saved as address history in the EHR before the new
address is applied. Set to false to overwrite without
preserving history. eClinicalWorks only.
referring_provider_first_name:
type: string
description: >-
Referring provider first name. Must be used with
referring_provider_last_name. eClinicalWorks only.
referring_provider_last_name:
type: string
description: >-
Referring provider last name. Must be used with
referring_provider_first_name. eClinicalWorks only.
referring_provider_id:
type: string
description: >-
Cobalt referring provider UUID from GET
/v1/referring-providers (without dashes). More reliable
than name-based resolution. eClinicalWorks only.
pcp_first_name:
type: string
description: >-
PCP first name. Must be used with pcp_last_name.
eClinicalWorks only.
pcp_last_name:
type: string
description: >-
PCP last name. Must be used with pcp_first_name.
eClinicalWorks only.
pcp_id:
type: string
description: >-
Cobalt referring provider UUID from GET
/v1/referring-providers (without dashes). More reliable
than name-based resolution. eClinicalWorks only.
referred_to_provider_id:
type: string
description: >-
Rendering provider EHR ID — use the ehr_id value from
GET /v1/providers (not the id) (eClinicalWorks only).
language:
type: string
description: >-
Patient preferred language. Must match a valid language
name in your eCW instance (eClinicalWorks only).
race:
type: string
description: >-
Patient race. Must match a valid race name in your eCW
instance (eClinicalWorks only).
ethnicity:
type: string
description: >-
Patient ethnicity. Must match a valid ethnicity code or
display name in your eCW instance (eClinicalWorks only).
voice_enabled:
type: boolean
description: >-
Enables voice (phone) notifications for the patient in
the eCW Patient Communications settings (eClinicalWorks
only).
text_enabled:
type: boolean
description: >-
Enables text (SMS) notifications for the patient in the
eCW Patient Communications settings (eClinicalWorks
only).
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
components:
securitySchemes:
ClientCredentials:
type: apiKey
in: header
name: client_id
ClientSecret:
type: apiKey
in: header
name: client_secret
AccessToken:
type: apiKey
in: header
name: access_token
````