Add Patient Insurance - Documentation

Add insurance to patient

curl --request POST \
  --url https://api.usecobalt.com/v1/patients/{patient_mrn}/insurances \
  --header 'Content-Type: application/json' \
  --header 'access_token: <api-key>' \
  --header 'client_id: <api-key>' \
  --header 'client_secret: <api-key>' \
  --data '
{
  "member_id": "MEM123456789",
  "group_id": "GRP98999",
  "insurance_provider_id": "insurance-provider-123",
  "insurance_name": "Blue Cross Anthem",
  "insurance_payer_id": "98999",
  "priority": "1",
  "plan_begin_date": "2026-01-01",
  "copayment": 25,
  "relationship_to_subscriber": "self",
  "subscriber_demographics": {
    "first_name": "John",
    "last_name": "Doe",
    "street_line_1": "123 Main Street",
    "city": "Los Angeles",
    "state": "CA",
    "zip": "90001",
    "sex": "M",
    "dob": "1980-01-15",
    "phone": "555-123-4567"
  }
}
'

{
  "success": true,
  "message": "<string>",
  "patient_insurance_id": "<string>",
  "job_id": 123
}

POST

patients

{patient_mrn}

insurances

Add insurance to patient

curl --request POST \
  --url https://api.usecobalt.com/v1/patients/{patient_mrn}/insurances \
  --header 'Content-Type: application/json' \
  --header 'access_token: <api-key>' \
  --header 'client_id: <api-key>' \
  --header 'client_secret: <api-key>' \
  --data '
{
  "member_id": "MEM123456789",
  "group_id": "GRP98999",
  "insurance_provider_id": "insurance-provider-123",
  "insurance_name": "Blue Cross Anthem",
  "insurance_payer_id": "98999",
  "priority": "1",
  "plan_begin_date": "2026-01-01",
  "copayment": 25,
  "relationship_to_subscriber": "self",
  "subscriber_demographics": {
    "first_name": "John",
    "last_name": "Doe",
    "street_line_1": "123 Main Street",
    "city": "Los Angeles",
    "state": "CA",
    "zip": "90001",
    "sex": "M",
    "dob": "1980-01-15",
    "phone": "555-123-4567"
  }
}
'

{
  "success": true,
  "message": "<string>",
  "patient_insurance_id": "<string>",
  "job_id": 123
}

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.

For eClinicalWorks, plan_begin_date is required. If relationship_to_subscriber is a non-self value such as spouse, child, or other, subscriber_demographics.first_name and subscriber_demographics.last_name are also required.

After a successful create, the success webhook includes emr_insurance_id. In eClinicalWorks, this is the same record identifier returned later as emr_insurance_id in POST /v1/patients/fetch with include: ["insurances"], and it can be used with the insurance update endpoint.

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

Priority (Optional)

priority: Insurance priority level (valid values: “1”, “2”, “3”). When not provided, the EMR will use its default priority setting.

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",
    "plan_begin_date": "2025-01-01",
    "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,
    "priority": "1",
    "relationship_to_subscriber": "spouse",
    "subscriber_demographics": {
      "first_name": "Jane",
      "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",
    "plan_begin_date": "2025-01-01",
    "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,
    "priority": 1,
    "relationship_to_subscriber": "self",
    "emr_insurance_id": "51638"
  }
}

In eClinicalWorks, emr_insurance_id is the EMR-native insurance record ID. The same value is returned in live fetch as emr_insurance_id and should be used when calling PATCH /v1/patients/:patient_mrn/insurances/:emr_insurance_id.

audit_trail is still present for some EMRs, including Experity and EZDERM. It is not currently included in the eClinicalWorks insurance success payload, so the example above reflects the eCW shape.

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",
    "failure_reason": "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.

Authorizations

client_id

string

header

required

client_secret

string

header

required

access_token

string

header

required

Path Parameters

patient_mrn

string

required

The Medical Record Number (MRN) of the patient in the EMR system

Body

application/json

member_id

string

required

Insurance member/policy ID

Example:

"MEM123456789"

group_id

string

Insurance group number

Example:

"GRP98999"

insurance_provider_id

string

Cobalt insurance provider ID (Priority 1). Use GET /v1/insurance-providers to retrieve valid IDs.

Example:

"insurance-provider-123"

insurance_name

string

Insurance company name (Priority 2)

Example:

"Blue Cross Anthem"

insurance_payer_id

string

Insurance payer ID (Priority 3)

Example:

"98999"

priority

enum<string>

Insurance priority level (1=primary, 2=secondary, 3=tertiary)

Available options:

1,

2,

3

Example:

"1"

plan_begin_date

string<date>

Insurance coverage start date in YYYY-MM-DD format

Pattern: ^\d{4}-\d{2}-\d{2}$

Example:

"2026-01-01"

copayment

number

Copayment amount in dollars

Required range: x >= 0

Example:

25

relationship_to_subscriber

string

Patient's relationship to insurance subscriber

Example:

"self"

subscriber_demographics

object

Insurance subscriber demographics

Show child attributes

Response

Insurance addition queued successfully

success

boolean

message

string

patient_insurance_id

string

job_id

integer

Update Patient Update Patient Insurance

Documentation Index

​Insurance Provider Resolution

​Validation Rules

​Address Validation

​Date Validation

​Priority (Optional)

​Relationship to Subscriber

​Insurance Provider Validation

​Example Requests

​Minimal Request (Using Insurance Provider ID)

​Complete Request (Using Insurance Name + Payer ID)

​Self-Insured Patient with 9-Digit ZIP

​Example Response

​Webhook Events

​Success Event (patient.insurance.added)

​Failure Event (patient.insurance.failed)

Authorizations

Path Parameters

Body

Response

Insurance Provider Resolution

Validation Rules

Address Validation

Date Validation

Priority (Optional)

Relationship to Subscriber

Insurance Provider Validation

Example Requests

Minimal Request (Using Insurance Provider ID)

Complete Request (Using Insurance Name + Payer ID)

Self-Insured Patient with 9-Digit ZIP

Example Response

Webhook Events

Success Event (patient.insurance.added)

Failure Event (patient.insurance.failed)