Create Patient - Documentation

Provider IDs for Referrals

When creating patients with referral information, use the ehr_id value from providers:

referred_to_provider_id (optional): Use the ehr_id from GET /v1/providers (not the id)

This value represents the rendering provider identifier your EMR system uses. Cobalt passes it directly to your EMR when creating the patient record.

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:

{
    "referring_provider_first_name": "John",
    "referring_provider_last_name": "Smith",
    "pcp_first_name": "Jane",
    "pcp_last_name": "Doe"
}

Option 2: Provider IDs (eClinicalWorks Only)

Use referring_provider_id or pcp_id from GET /v1/referring-providers (UUID 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": "e35e82b85df58f08a9b38e06a91e9f1a",
    "pcp_id": "223ecd1b29e546ca9db6b391eb49b213"
}

EMR Compatibility: The referring_provider_id and pcp_id parameters are currently only supported for eClinicalWorks. For other EMRs, you must use the name fields (referring_provider_first_name, referring_provider_last_name, pcp_first_name, pcp_last_name).

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

{
    "responsible_party": "parent",
    "responsible_party_first_name": "Jane",
    "responsible_party_last_name": "Smith",
    "responsible_party_sex": "female",
    "responsible_party_dob": "1975-06-15",
    "responsible_party_phone": "555-555-1234",
    "insurance_name": "Aetna",
    "insurance_subscriber_number": "ABC123"
}

Supported values:

Value	eCW Code	Description
`self`	1	Patient is the insured
`spouse`	2	Patient is the spouse of the insured
`child`	3	Natural Child — insured has financial responsibility
`adopted_child`	4	Natural Child — insured does not have financial responsibility (includes legally adopted)
`step_child`	5	Step Child
`foster_child`	6	Foster Child
`ward_of_court`	7	Ward of the Court
`employee`	8	Employee
`unknown`	9	Unknown / Other relationship
`handicapped_dependent`	10	Handicapped Dependent
`organ_donor`	11	Organ Donor
`cadaver_donor`	12	Cadaver Donor
`grandchild`	13	Grandchild
`niece_nephew`	14	Niece/Nephew
`injured_plaintiff`	15	Injured Plaintiff
`sponsored_dependent`	16	Sponsored Dependent
`minor_dependent`	17	Minor Dependent of a Minor Dependent
`parent`	18	Parent
`grandparent`	19	Grandparent
`life_partner`	53	Life Partner
`other`	99	Other

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:

Field	Type	Description
`language`	string	Preferred language. Must match a valid language name in your eCW instance.
`race`	string	Race. Must match a valid race name in your eCW instance.
`ethnicity`	string	Ethnicity. Must match a valid ethnicity code or display name in your eCW instance.
`release_of_info`	boolean	Consent for release of information. Defaults to `true`.
`rx_history_consent`	boolean	Consent for pharmacy history sharing. Defaults to `true`.
`self_pay`	boolean	Explicitly marks the patient as self-pay, overriding insurance-derived logic.
`default_facility_id`	string	The eCW facility ID to set as the patient’s primary service location.

{
    "language": "Spanish",
    "race": "White",
    "ethnicity": "Hispanic or Latino",
    "release_of_info": true,
    "rx_history_consent": false,
    "default_facility_id": "25"
}

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_name": "United Healthcare"
}

Option 2: Insurance Provider ID (eClinicalWorks Only) Use 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

{
    "insurance_provider_id": "e35e82b85df58f08a9b38e06a91e9f1a"
}

Example Request

Basic Request

curl -X POST https://api.usecobalt.com/v1/patients \
-H 'Content-Type: application/json' \
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh' \
-H 'access_token: 493JKLHIU98789hLKH9HHJH' \
-d '{
    "last_name": "Smith",
    "first_name": "John",
    "phone": "5551234567",
    "dob": "1980-01-01",
    "sex": "male"
}'

With Provider Names

curl -X POST https://api.usecobalt.com/v1/patients \
-H 'Content-Type: application/json' \
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh' \
-H 'access_token: 493JKLHIU98789hLKH9HHJH' \
-d '{
    "last_name": "Smith",
    "first_name": "John",
    "phone": "5551234567",
    "dob": "1980-01-01",
    "sex": "male",
    "referring_provider_first_name": "Jane",
    "referring_provider_last_name": "Doe",
    "pcp_first_name": "Robert",
    "pcp_last_name": "Johnson"
}'

With Provider IDs (eClinicalWorks Only)

curl -X POST https://api.usecobalt.com/v1/patients \
-H 'Content-Type: application/json' \
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh' \
-H 'access_token: 493JKLHIU98789hLKH9HHJH' \
-d '{
    "last_name": "Smith",
    "first_name": "John",
    "phone": "5551234567",
    "dob": "1980-01-01",
    "sex": "male",
    "referring_provider_id": "e35e82b85df58f08a9b38e06a91e9f1a",
    "pcp_id": "223ecd1b29e546ca9db6b391eb49b213"
}'

Example Response

{
    "success": true,
    "message": "Patient processing. A webhook event will be sent upon completion.",
    "patient_id": "9988776655443322"
}

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

{
    "id": "evt_pat_succ_g7h8i9",
    "access_token_reference_id": "user_pat_ref_k3l4m5",
    "object": "event",
    "created": "2023-10-29T12:00:00Z",
    "type": "patient.created",
    "data": {
        "patient_id": "9988776655443322",
        "mrn": "123456",
        "eligibility_information": [
            {
                "insurance_name": "Aetna",
                "status": "Active"
            }
        ] // returned when check_eligibility=true. Availability depends on EHR support. 
    }
}

Failure Examples

The patient.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:

{
    "id": "evt_pat_fail_dup_p2q3r4",
    "access_token_reference_id": "user_pat_ref_k3l4m5",
    "object": "event",
    "created": "2023-10-29T12:05:00Z",
    "type": "patient.failed",
    "data": {
        "patient_id": "9988776655443322",
        "failure_reason": "Duplicate patient found. Please use the existing patient or update the patient information using the PATCH /v1/patients/:id endpoint.",
        "existing_mrn": "654321"
    }
}

Referring Provider Not Found:

{
    "id": "evt_pat_fail_ref_s5t6u7",
    "access_token_reference_id": "user_pat_ref_k3l4m5",
    "object": "event",
    "created": "2023-10-29T12:10:00Z",
    "type": "patient.failed",
    "data": {
        "patient_id": "9988776655443323",
        "failure_reason": "No valid referring provider found. Please update the referring provider using the PATCH /v1/patients/:id endpoint."
    }
}

PCP Not Found:

{
    "id": "evt_pat_fail_pcp_y1z2a3",
    "access_token_reference_id": "user_pat_ref_k3l4m5",
    "object": "event",
    "created": "2023-10-29T12:12:00Z",
    "type": "patient.failed",
    "data": {
        "patient_id": "9988776655443325",
        "failure_reason": "No valid PCP provider found. Please update the PCP provider using the PATCH /v1/patients/:id endpoint."
    }
}

Insurance Not Found:

{
    "id": "evt_pat_fail_ins_v8w9x0",
    "access_token_reference_id": "user_pat_ref_k3l4m5",
    "object": "event",
    "created": "2023-10-29T12:15:00Z",
    "type": "patient.failed",
    "data": {
        "patient_id": "9988776655443324",
        "failure_reason": "No valid insurance found. Please update the insurance using the PATCH /v1/patients/:id endpoint."
    }
}

Patient creation is asynchronous. Store the returned patient_id and listen for webhooks to determine the final status.

Authorizations

client_id

string

header

required

client_secret

string

header

required

access_token

string

header

required

Body

application/json

address_city

string

address_line2

string

Address line 2 (apartment, suite, unit, etc.)

address_state

string

address_street

string

address_zip

string

cell_phone

string

check_eligibility

enum<string>

default:false

Whether to check insurance eligibility for the patient

Available options:

true,

false

dob

string

Patient email address

no_email_reason

string

Reason why email was not provided. Can be used instead of email when email is required. Only available for certain EMRs.

emergency_contact_first_name

string

emergency_contact_last_name

string

emergency_contact_phone

string

emergency_contact_relation

string

first_name

string

insurance_name

string

insurance_provider_id

string

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.

insurance_sequence

enum<string>

Available options:

primary,

secondary,

tertiary

insurance_subscriber_number

string

last_name

string

pcp_first_name

string

pcp_last_name

string

pcp_id

string

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.

pharmacy_id

string

phone

string

referred_to_provider_id

string

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

string

First name of the referring provider

referring_provider_last_name

string

Last name of the referring provider

referring_provider_id

string

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.

responsible_party

enum<string>

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

secondary_insurance_name

string

secondary_insurance_subscriber_number

string

sex

enum<string>

Available options:

male,

female,

unknown

responsible_party_first_name

string

First name of the responsible party. Required when responsible_party is not self (eClinicalWorks only).

responsible_party_last_name

string

Last name of the responsible party. Required when responsible_party is not self (eClinicalWorks only).

responsible_party_sex

enum<string>

Sex of the responsible party (eClinicalWorks only).

Available options:

male,

female

responsible_party_dob

string

Date of birth of the responsible party in YYYY-MM-DD format (eClinicalWorks only).

responsible_party_phone

string

Phone number of the responsible party (eClinicalWorks only).

language

string

Patient preferred language (eClinicalWorks only). Must match a valid language name in your eCW instance.

race

string

Patient race (eClinicalWorks only). Must match a valid race name in your eCW instance.

ethnicity

string

Patient ethnicity (eClinicalWorks only). Must match a valid ethnicity code or display name in your eCW instance.

release_of_info

boolean

Consent for release of information (eClinicalWorks only). Defaults to true.

Consent for pharmacy history sharing (eClinicalWorks only). Defaults to true.

self_pay

boolean

Explicitly marks the patient as self-pay, overriding insurance-derived self-pay logic (eClinicalWorks only).

default_facility_id

string

The eCW facility ID to set as the patient primary service location (eClinicalWorks only).

Response

200 - application/json

Successful response

success

boolean

message

string

patient_id

string

API Documentation

Account

Appointments

Availability

Claims

Documents

Insurance

Link

Locations

Messages

Notes

Orders

Patients

Pharmacies

Providers

Referrals

Referring Providers

Settings

Tasks

Telephone Encounters

Visit Statuses

Visit Types

Webhooks

Documentation Index

​Provider IDs for Referrals

​Referring Provider and PCP Options

​Option 1: Provider Names (All EMRs)

​Option 2: Provider IDs (eClinicalWorks Only)

​Responsible Party (eClinicalWorks Only)

​Registration Fields (eClinicalWorks Only)

​Insurance Options

​Example Request

​Basic Request

​With Provider Names

​With Provider IDs (eClinicalWorks Only)

​Example Response

​Webhook Notifications

​Success

​Failure Examples

Authorizations

Body

Response

Provider IDs for Referrals

Referring Provider and PCP Options

Option 1: Provider Names (All EMRs)

Option 2: Provider IDs (eClinicalWorks Only)

Responsible Party (eClinicalWorks Only)

Registration Fields (eClinicalWorks Only)

Insurance Options

Example Request

Basic Request

With Provider Names

With Provider IDs (eClinicalWorks Only)

Example Response

Webhook Notifications

Success

Failure Examples