This endpoint queues the addition of insurance information to a patient record in the EMR system. The operation is asynchronous and returns immediately with a job_id for tracking. Results are delivered via webhook.
Insurance Provider Resolution
The API supports three methods for identifying the insurance provider (in order of priority):
-
By Cobalt Provider ID (Most specific, recommended):
{
"insurance_provider_id": "abc123def456"
}
-
By Name + Payer ID (Most specific when ID not available):
{
"insurance_name": "ACME Health",
"insurance_payer_id": "98999"
}
-
By Name Only (Least specific, may match first result if multiple exist):
{
"insurance_name": "ACME Health"
}
Use GET /v1/insurance-providers to retrieve the correct insurance provider identifiers for your organization.
Validation Rules
Address Validation
- State: Must be a valid two-letter US state abbreviation (accepts lowercase, e.g., “ca” or “CA”)
- ZIP Code: Must be either 5 digits (e.g., “90001”) or 9 digits with hyphen (e.g., “90001-1234”)
Date Validation
- plan_begin_date: Must be in YYYY-MM-DD format (e.g., “2025-01-15”)
Relationship to Subscriber
Accepts both codes and names (case-insensitive):
- Codes: “01”, “02”, “32”, “33”, “17”, “20”, “53”, “25”
- Names: “self”, “spouse”, “mother”, “father”, “step parent”, “employee”, “life partner”, “other”
Insurance Provider Validation
insurance_payer_id alone is not supported (must be combined with insurance_name)- If provider ID, name, or name+payer_id combination is not found, returns 404 with helpful message
Example Requests
Minimal Request (Using Insurance Provider ID)
curl -X POST https://api.usecobalt.com/v1/patients/MRN123456/insurances \
-H "Content-Type: application/json" \
-H "client_id: your_client_id" \
-H "client_secret: your_client_secret" \
-H "access_token: your_access_token" \
-d '{
"member_id": "MEM123456789",
"group_id": "GRP98999",
"insurance_provider_id": "abc123def456",
"subscriber_demographics": {
"first_name": "John",
"last_name": "Doe",
"street_line_1": "123 Main St",
"city": "Los Angeles",
"state": "CA",
"zip": "90001"
}
}'
Complete Request (Using Insurance Name + Payer ID)
curl -X POST https://api.usecobalt.com/v1/patients/MRN123456/insurances \
-H "Content-Type: application/json" \
-H "client_id: your_client_id" \
-H "client_secret: your_client_secret" \
-H "access_token: your_access_token" \
-d '{
"member_id": "MEM123456789",
"group_id": "GRP98999",
"insurance_name": "ACME Health",
"insurance_payer_id": "98999",
"plan_begin_date": "2025-01-01",
"copayment": 25,
"relationship_to_subscriber": "self",
"subscriber_demographics": {
"first_name": "John",
"last_name": "Doe",
"street_line_1": "123 Main St",
"city": "Los Angeles",
"state": "CA",
"zip": "90001-1234"
}
}'
Self-Insured Patient with 9-Digit ZIP
curl -X POST https://api.usecobalt.com/v1/patients/MRN789012/insurances \
-H "Content-Type: application/json" \
-H "client_id: your_client_id" \
-H "client_secret: your_client_secret" \
-H "access_token: your_access_token" \
-d '{
"member_id": "MEM987654321",
"group_id": "GRP11111",
"insurance_name": "Blue Cross Blue Shield",
"relationship_to_subscriber": "01",
"subscriber_demographics": {
"first_name": "Jane",
"last_name": "Smith",
"street_line_1": "456 Oak Ave",
"city": "San Francisco",
"state": "ca",
"zip": "94102-1234"
}
}'
Example Response
{
"success": true,
"message": "Insurance addition queued successfully. Processing will begin shortly.",
"patient_insurance_id": "xyz789abc123",
"job_id": 12345
}
Webhook Events
After the insurance addition is processed, a webhook event will be sent to your configured webhook URL.
Success Event (patient.insurance.added)
{
"id": "evt_abc123def456",
"access_token_reference_id": "your_reference_id",
"object": "event",
"created": "2025-01-15T10:30:00.000Z",
"type": "patient.insurance.added",
"job_id": "12345",
"data": {
"patient_insurance_id": "xyz789abc123",
"patient_mrn": "MRN123456",
"member_id": "MEM123456789",
"group_id": "GRP98999",
"plan_begin_date": "2025-01-01",
"copayment": 25,
"audit_trail": [
{
"field_label": "Insurance Company",
"before": "",
"after": "ACME Health",
"property": "insurance_company"
},
...
]
}
}
The audit_trail array shows all fields that were modified in the EMR. When EMR corrections occur (e.g., name mismatch dialogs), an attempted field shows the originally submitted value, and a note explains the correction.
Failure Event (patient.insurance.failed)
{
"id": "evt_xyz789abc123",
"access_token_reference_id": "your_reference_id",
"object": "event",
"created": "2025-01-15T10:30:00.000Z",
"type": "patient.insurance.failed",
"job_id": "12345",
"data": {
"patient_insurance_id": "xyz789abc123",
"patient_mrn": "MRN123456",
"error": "Patient not found in EMR system"
}
}
Insurance addition is asynchronous. Store the returned patient_insurance_id and job_id, then listen for webhooks to determine the final status.
The Medical Record Number (MRN) of the patient in the EMR system
Plan start date in YYYY-MM-DD format (e.g., "2025-01-15")
Cobalt insurance provider ID (Priority 1, most specific). Use GET /v1/insurance-providers to retrieve valid IDs.
Insurance provider name (can be combined with insurance_payer_id)
Insurance payer ID (must be combined with insurance_name, cannot be used alone)
Copayment amount in dollars (e.g., 25)
Required range: x >= 0
relationship_to_subscriber
Patient's relationship to subscriber. Accepts either code or name (case-insensitive)
Available options:
01,
02,
32,
33,
17,
20,
53,
25,
self,
spouse,
mother,
father,
step parent,
employee,
life partner,
other
Insurance addition queued successfully
