Add Patient Insurance - Documentation

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

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

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

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

API Documentation

Account

Appointments

Availability

Claims

Documents

Insurance

Pharmacies

Link

Locations

Messages

Notes

Orders

Patients

Providers

Referring Providers

Tasks

Telephone Encounters

Settings

Visit Statuses

Visit Types

Webhooks

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