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

​
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