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 ID

plan_begin_date

string<date>

required

Plan start date in YYYY-MM-DD format (e.g., "2025-01-15")

relationship_to_subscriber

enum<string>

required

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

subscriber_demographics

object

required

Show child attributes

group_id

string

Insurance group ID

insurance_provider_id

string

Cobalt insurance company ID (Priority 1, most specific). Use GET /v1/insurance-providers to retrieve valid IDs.

insurance_name

string

Insurance provider name (can be combined with insurance_payer_id)

priority

string

Insurance priority level (valid values: "1", "2", "3"). Often referred to as primary, secondary, or tertiary.

insurance_payer_id

string

Insurance payer ID (must be combined with insurance_name, cannot be used alone)

copayment

number

Copayment amount in dollars (e.g., 25)

Required range: x >= 0

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

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)