Create Patient

Creates a new patient record.

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.

Example 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"
}'

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."
    }
}

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

last_name · string

first_name · string

phone · string

cell_phone · string

dob · string

sex · enum<string>

Available options:

male,

female,

unknown

referring_provider · string

address_street · string

address_city · string

address_state · string

address_zip · string

insurance_name · string

insurance_subscriber_number · string

insurance_sequence · enum<string>

Available options:

primary,

secondary,

tertiary

responsible_party · enum<string>

Available options:

self

check_eligibility · enum<string> · default: false

Whether to check insurance eligibility for the patient

Available options:

true,

false

pcp_first_name · string

pcp_last_name · string

secondary_insurance_name · string

secondary_insurance_subscriber_number · string

emergency_contact_first_name · string

emergency_contact_last_name · string

emergency_contact_relation · string

emergency_contact_phone · string

pharmacy_id · string

Response

200 - application/json

Successful response

success · boolean

message · string

patient_id · string