Create Patient
Patients
Create Patient
Creates a new patient record.
POST
Create Patient
Provider IDs for Referrals
When creating patients with referral information, use theehr_id value from providers:
referred_to_provider_id(optional): Use theehr_idfromGET /v1/providers(not theid)
Don’t use the Cobalt
id here. The id field from GET responses is Cobalt’s internal UUID, used only for updating provider settings via PATCH endpoints.Referring Provider and PCP Options
When creating a patient, you can specify the referring provider and PCP (Primary Care Provider) using either names or provider IDs:Option 1: Provider Names (All EMRs)
Provide the provider’s first and last name:Option 2: Provider IDs (eClinicalWorks Only)
Provide a Cobaltid (UUID, with or without dashes). This option:
- Automatically looks up the provider’s name, phone, and fax
- Provides more accurate matching by validating contact information in the EMR
- Falls back to using provided names if the ID is not found
referring_provider_id: theidfromGET /v1/referring-providers.pcp_id: theidfrom eitherGET /v1/referring-providersorGET /v1/providers. Pass a/v1/providersidwhen the patient’s PCP is one of the practice’s own physicians rather than an external referring provider. Cobalt resolves the UUID against both sets of providers, so you can use whichever endpoint the provider appears in.
For
pcp_id, use the id field (the Cobalt UUID), not the ehr_id. This differs from referred_to_provider_id, which expects the ehr_id from GET /v1/providers.Responsible Party (eClinicalWorks Only)
By default, the patient is their own responsible party (responsible_party: "self"). For minors or patients whose billing is managed by another person, set responsible_party to one of the values below and include the guarantor’s demographic fields.
When a non-self responsible party is provided alongside insurance, Cobalt will:
- Create a guarantor record in eCW with the provided demographics
- Link that guarantor to the insurance record
- Set the responsible party on the patient
Optional guarantor fields:
responsible_party_first_name and responsible_party_last_name are required when using a non-self responsible party. The guarantor is created as a separate record in eCW — if a guarantor with those demographics already exists in your instance, a duplicate will be created.Registration Fields (eClinicalWorks Only)
Additional demographic and consent fields can be set at patient creation:Notification language. When
voice_enabled or text_enabled is set, the notification language in eCW follows the patient’s language: Spanish when language contains “spanish” (case-insensitive), otherwise English. These are the only two options eCW exposes for communication notifications.Insurance Options
When creating a patient, you can specify insurance using either the insurance name or an insurance provider ID: Option 1: Insurance Name (All EMRs)insurance_provider_id from GET /v1/insurance-providers (UUID without dashes). This option:
- Automatically looks up the insurance name, address, city, and state
- Provides more accurate matching when there are duplicate insurance names
- Falls back to using provided insurance_name if the ID is not found
Example Request
Basic Request
With Provider Names
With Provider IDs (eClinicalWorks Only)
Example Response
Webhook Notifications
When patient processing is complete, we will send a webhook to your registered endpoint. Here are examples of what those webhook payloads will look like:Success
Failure Examples
Thepatient.failed webhook event includes a failure_reason and may contain additional fields in the data object depending on the cause of the failure.
Duplicate Patient:
Patient creation is asynchronous. Store the returned patient_id and listen for webhooks to determine the final status.
Authorizations
Body
application/json
Address line 2 (apartment, suite, unit, etc.)
Whether to check insurance eligibility for the patient
Available options:
true, false Patient email address
Reason why email was not provided. Can be used instead of email when email is required. Only available for certain EMRs.
Patient Social Security Number as 9 digits, no dashes (e.g. 123456789).
Free-text reason SSN was not provided, used when ssn is omitted (e.g. 'patient refused', 'patient does not have SSN'). Recorded on the patient in the EMR. Only available for certain EMRs (eClinicalWorks).
Patient marital status. For eClinicalWorks, must be one of: Divorced, Married, Partner, Single, Unknown, Widowed, Legally Separated.
Insurance group number. Currently only used for Greenway, where it is required alongside plan_code and insurance_policy_type when attaching insurance.
The id of an insurance provider from GET /v1/insurance-providers (UUID without dashes). Can be used instead of insurance_name for enhanced matching. Currently only supported for eClinicalWorks.
Available options:
primary, secondary, tertiary The id of a PCP provider from GET /v1/referring-providers (UUID without dashes). Can be used instead of pcp_first_name and pcp_last_name. Currently only supported for eClinicalWorks.
Greenway-internal plan code identifying the payer (e.g. AETN08). Currently only used for Greenway, where it replaces the insurance_name lookup and is required alongside group_number and insurance_policy_type when attaching insurance.
The ehr_id of the provider this patient is being referred to (rendering provider). Use the ehr_id from GET /v1/providers
First name of the referring provider
Last name of the referring provider
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.
The responsible party for the patient. Non-self values (spouse, parent, child, other, unknown) are currently supported for eClinicalWorks only and require responsible_party_* demographic fields.
Available options:
self, spouse, child, adopted_child, step_child, foster_child, ward_of_court, employee, unknown, handicapped_dependent, organ_donor, cadaver_donor, grandchild, niece_nephew, injured_plaintiff, sponsored_dependent, minor_dependent, parent, grandparent, life_partner, other Available options:
male, female, unknown First name of the responsible party. Required when responsible_party is not self (eClinicalWorks only).
Last name of the responsible party. Required when responsible_party is not self (eClinicalWorks only).
Sex of the responsible party (eClinicalWorks only).
Available options:
male, female Date of birth of the responsible party in YYYY-MM-DD format (eClinicalWorks only).
Phone number of the responsible party (eClinicalWorks only).
Email address of the responsible party (eClinicalWorks only).
Street address line 1 of the responsible party (eClinicalWorks only).
Street address line 2 of the responsible party (eClinicalWorks only).
City of the responsible party (eClinicalWorks only).
Two-letter U.S. state abbreviation for the responsible party address (eClinicalWorks only).
5-digit ZIP code for the responsible party address (eClinicalWorks only).
Patient preferred language (eClinicalWorks only). Must match a valid language name in your eCW instance.
Patient race (eClinicalWorks only). Must match a valid race name in your eCW instance.
Patient ethnicity (eClinicalWorks only). Must match a valid ethnicity code or display name in your eCW instance.
Consent for release of information (eClinicalWorks only). Defaults to true.
Consent for pharmacy history sharing (eClinicalWorks only). Defaults to true.
Explicitly marks the patient as self-pay, overriding insurance-derived self-pay logic (eClinicalWorks only).
The eCW facility ID to set as the patient primary service location (eClinicalWorks only).
Enables voice (phone) notifications for the patient in the eCW Patient Communications settings (eClinicalWorks only).
Enables text (SMS) notifications for the patient in the eCW Patient Communications settings (eClinicalWorks only).