Create Patient

Creates a new patient record.

POST /patients

Create Patient

cURL

curl --request POST \
  --url https://api.usecobalt.com/v1/patients \
  --header 'Content-Type: application/json' \
  --header 'access_token: <api-key>' \
  --header 'client_id: <api-key>' \
  --header 'client_secret: <api-key>' \
  --data '
{
  "address_city": "<string>",
  "address_line2": "<string>",
  "address_state": "<string>",
  "address_street": "<string>",
  "address_zip": "<string>",
  "cell_phone": "<string>",
  "check_eligibility": "false",
  "dob": "<string>",
  "email": "<string>",
  "no_email_reason": "<string>",
  "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>",
  "insurance_subscriber_number": "<string>",
  "last_name": "<string>",
  "pcp_first_name": "<string>",
  "pcp_last_name": "<string>",
  "pcp_id": "<string>",
  "pharmacy_id": "<string>",
  "phone": "<string>",
  "referred_to_provider_id": "<string>",
  "referring_provider_first_name": "<string>",
  "referring_provider_last_name": "<string>",
  "referring_provider_id": "<string>",
  "secondary_insurance_name": "<string>",
  "secondary_insurance_subscriber_number": "<string>",
  "responsible_party_first_name": "<string>",
  "responsible_party_last_name": "<string>",
  "responsible_party_dob": "<string>",
  "responsible_party_phone": "<string>",
  "language": "<string>",
  "race": "<string>",
  "ethnicity": "<string>",
  "release_of_info": true,
  "rx_history_consent": true,
  "self_pay": true,
  "default_facility_id": "<string>"
}
'

200

{
  "success": true,
  "message": "<string>",
  "patient_id": "<string>"
}

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:

1. Create a guarantor record in eCW with the provided demographics
2. Link that guarantor to the insurance record
3. 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

email · 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.

rx_history_consent · boolean

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