Create Patient

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

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_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>

Available options:

self

secondary_insurance_name

string

secondary_insurance_subscriber_number

string

sex

enum<string>

Available options:

male,

female,

unknown

Response

200 - application/json

Successful response

success

boolean

message

string

patient_id

string

API Documentation

Account

Appointments

Availability

Claims

Documents

Insurance

Pharmacies

Link

Locations

Messages

Notes

Orders

Patients

Providers

Referring Providers

Tasks

Telephone Encounters

Settings

Visit Statuses

Visit Types

Webhooks

Provider IDs for Referrals

Referring Provider and PCP Options

Option 1: Provider Names (All EMRs)

Option 2: Provider IDs (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

API Documentation

Account

Appointments

Availability

Claims

Documents

Insurance

Pharmacies

Link

Locations

Messages

Notes

Orders

Patients

Providers

Referring Providers

Tasks

Telephone Encounters

Settings

Visit Statuses

Visit Types

Webhooks

​Provider IDs for Referrals

​Referring Provider and PCP Options

​Option 1: Provider Names (All EMRs)

​Option 2: Provider IDs (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)

Insurance Options

Example Request

Basic Request

With Provider Names

With Provider IDs (eClinicalWorks Only)

Example Response

Webhook Notifications

Success

Failure Examples