Skip to main content
PATCH
Update a 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.

​
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

​
Provider Fields (eClinicalWorks Only)

​
Demographics & Contact Preference Fields (eClinicalWorks Only)

Billing notes are eClinicalWorks-only. Sending billing_notes for any other EMR returns a 400. A common workflow: read the current billing_notes via patient fetch, transform it (for example, rewrite referral: ...; to scheduledreferral: ...;), then PATCH it back.
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

​
Example Request for Updating an Active Patient’s Contact Info

​
Example Request for Updating an Active Patient’s Address

To update the address without saving the previous address as history, pass save_previous_address: false:

​
Example Request for Updating an Active Patient’s Providers

Or using names instead of IDs:

​
Example Request for Updating an Active Patient’s Demographics & Contact Preferences

​
Example Request for Marking a Patient as Self-Pay

​
Example Response

job_id is the API log ID for the request and is also present on the resulting patient.updated webhook, so you can match either identifier back to this call.
Only include the fields you want to update in the request body. Omitted fields will remain unchanged.

Authorizations

​
client_id
string
header
required
​
client_secret
string
header
required
​
access_token
string
header
required

Path Parameters

​
id
string
required

Cobalt patient ID (UUID, with or without dashes).

Body

application/json
​
phone
string | null

Primary phone (222-333-4444).

Example:

"555-123-4567"

​
cell_phone
string | null

Cell phone (222-333-4444).

Example:

"555-987-6543"

​
email
string | null

Patient email.

Example:

"jane.doe@example.com"

​
address_street
string | null

Street address line 1.

Example:

"123 Main Street"

​
address_line2
string | null

Street address line 2.

Example:

"Apt 4B"

​
address_city
string | null

City.

Example:

"Los Angeles"

​
address_state
string | null

Two-letter U.S. state abbreviation.

Example:

"CA"

​
address_zip
string | null

5-digit U.S. ZIP code.

Example:

"90001"

​
referring_provider_first_name
string | null

Referring provider first name.

Example:

"Jane"

​
referring_provider_last_name
string | null

Referring provider last name.

Example:

"Doe"

​
referring_provider_id
string | null

Cobalt referring-provider UUID (from GET /v1/referring-providers).

​
pcp_first_name
string | null

Primary care provider first name.

Example:

"Jane"

​
pcp_last_name
string | null

Primary care provider last name.

Example:

"Doe"

​
pcp_id
string | null

Cobalt UUID of the PCP (from GET /v1/referring-providers or GET /v1/providers).

​
referred_to_provider_id
string | null

Referred-to provider EMR ID.

Example:

"provider-123"

​
language
string | null

Preferred language.

Example:

"English"

​
race
string | null

Patient race.

Example:

"White"

​
ethnicity
string | null

Patient ethnicity.

Example:

"Not Hispanic or Latino"

​
voice_enabled
enum<string> | null

Whether voice notifications are enabled.

Available options:
true,
false
​
text_enabled
enum<string> | null

Whether text notifications are enabled.

Available options:
true,
false
​
billing_notes
string | null

Patient billing alert notes (free text).

Example:

"Balance due at next visit."

​
pharmacy_id
string | null

EMR pharmacy ID (the ehr_id from GET /v1/pharmacies). Sets the patient's primary pharmacy, keeping any existing pharmacies and demoting the prior primary.

Example:

"PHARM-123"

​
self_pay
enum<string> | null

Whether the patient is self-pay.

Available options:
true,
false
​
team
string | null

Team name (or numeric team id) to assign the client to. Assigning a team creates an episode for the client when one does not already exist.

Example:

"TestClinic"

​
save_previous_address
enum<string> | null

Whether to keep the prior address on file when the address changes.

Available options:
true,
false
​
callback_urls

URL(s) to receive the completion webhook for this update.

Example:

Response

Patient update queued or applied

​
success
boolean
required
​
message
string
required
​
patient_id
string
required
​
job_id