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

​
Demographics & Contact Preference Fields

Billing notes. 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 the EHR 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 exposed 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).

Example:

"a1b2c3d4e5f6478899aabbccddeeff00"

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).

Example:

"c3d4e5f6a1b2478899aabbccddeeff00"

​
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).

Example:

"b2c3d4e5f6a1478899aabbccddeeff00"

​
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
Example:

"true"

​
text_enabled
enum<string> | null

Whether text notifications are enabled.

Available options:
true,
false
Example:

"true"

​
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
Example:

"false"

​
first_name
string | null

Patient first name.

Example:

"Jane"

​
last_name
string | null

Patient last name.

Example:

"Doe"

​
dob
string<date> | null

Date of birth (YYYY-MM-DD).

Example:

"1980-01-15"

​
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
Example:

"true"

​
callback_urls

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

Example:
​
expires_at
string<date-time> | null

Optional ISO 8601 timestamp with an explicit timezone offset, in the future when submitted. Cobalt starts no new operation attempt after this deadline and reports reasons[].code EXPIRED. An attempt already in progress, including write reconciliation, may finish after it.

Example:

"2027-06-15T14:30:00Z"

Response

Patient update queued or applied

​
success
boolean
required
Example:

true

​
message
string
required
Example:

"Patient update queued"

​
patient_id
string
required
Example:

"a1b2c3d4e5f6478899aabbccddeeff00"

​
job_id
Example:

12345