Skip to main content
POST
/
patients
Create Patient
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 '
{
  "last_name": "<string>",
  "first_name": "<string>",
  "phone": "<string>",
  "cell_phone": "<string>",
  "dob": "<string>",
  "sex": "male",
  "referring_provider": "<string>",
  "address_street": "<string>",
  "address_city": "<string>",
  "address_state": "<string>",
  "address_zip": "<string>",
  "insurance_name": "<string>",
  "insurance_subscriber_number": "<string>",
  "insurance_sequence": "primary",
  "responsible_party": "self",
  "check_eligibility": "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>"
}
'
{
  "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.

​
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