Update Patient Insurance

Queue an update to an existing patient insurance record in eClinicalWorks.

PATCH /patients/{patient_mrn}/insurances/{emr_insurance_id}

Update patient insurance

cURL

curl --request PATCH \
  --url https://api.usecobalt.com/v1/patients/{patient_mrn}/insurances/{emr_insurance_id} \
  --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",
  "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": "F",
    "dob": "1980-01-15",
    "phone": "555-123-4567"
  }
}
'

202

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

This endpoint queues an asynchronous update for an existing patient insurance record.

Insurance updates are currently supported for eClinicalWorks only.

Identifying The Insurance To Update

Use the EMR insurance record ID. You can get it from either:

• POST /v1/patients/fetch with include: ["insurances"]
• the emr_insurance_id returned in a prior patient.insurance.added or patient.insurance.updated webhook

In live fetch responses, the update target is returned as insurances[].emr_insurance_id.

Provider Resolution

The API supports the same insurance provider resolution options as insurance create:

1. insurance_provider_id
2. insurance_name + insurance_payer_id
3. insurance_name

insurance_payer_id alone is not supported. If you request a carrier change for eClinicalWorks, the resolved insurance provider must have an eCW ehrId configured or the request will be rejected.

Validation Rules

• All request body fields are optional. Omitted fields are preserved from the current EMR insurance record.
• emr_insurance_id is required in the URL path.
• For eClinicalWorks, if you send subscriber_demographics, it must include first_name and last_name.
• For eClinicalWorks, 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 required.
• plan_begin_date, when provided, must be in YYYY-MM-DD format.

Discover The Record ID First

curl -X POST https://api.usecobalt.com/v1/patients/fetch \
  -H "Content-Type: application/json" \
  -H "client_id: your_client_id" \
  -H "client_secret: your_client_secret" \
  -H "access_token: your_access_token" \
  -d '{
    "mrn": "MRN123456",
    "search_by": "mrn",
    "include": ["insurances"]
  }'

Example insurance entry from the live-fetch webhook payload:

{
  "emr_insurance_id": "51638",
  "priority": 1,
  "insurance_ehr_id": "733",
  "insurance_name": "Alignment Health Plan(P)",
  "insurance_subscriber_number": "MEM-POSTMAN-001",
  "group_id": "GRP-POSTMAN-001",
  "plan_begin_date": "2026-07-01",
  "copayment": "10.00",
  "relationship_to_subscriber": "spouse",
  "guarantor_id": "90688",
  "is_guarantor_patient": false
}

Example Requests

Update A Few Insurance Fields

curl -X PATCH https://api.usecobalt.com/v1/patients/MRN123456/insurances/51638 \
  -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",
    "copayment": 25
  }'

Change To A Non-Self Subscriber

curl -X PATCH https://api.usecobalt.com/v1/patients/MRN123456/insurances/51638 \
  -H "Content-Type: application/json" \
  -H "client_id: your_client_id" \
  -H "client_secret: your_client_secret" \
  -H "access_token: your_access_token" \
  -d '{
    "relationship_to_subscriber": "spouse",
    "subscriber_demographics": {
      "first_name": "Jane",
      "last_name": "Doe",
      "dob": "1985-04-12",
      "phone": "5551234567",
      "sex": "F"
    }
  }'

Change The Carrier

curl -X PATCH https://api.usecobalt.com/v1/patients/MRN123456/insurances/51638 \
  -H "Content-Type: application/json" \
  -H "client_id: your_client_id" \
  -H "client_secret: your_client_secret" \
  -H "access_token: your_access_token" \
  -d '{
    "insurance_name": "ACE Medicare Supplement",
    "insurance_payer_id": "14367"
  }'

Example Response

{
  "success": true,
  "message": "Insurance update queued successfully. Processing will begin shortly.",
  "patient_insurance_id": "xyz789abc123",
  "job_id": 12345
}

Webhook Events

Success Event (patient.insurance.updated)

{
  "id": "evt_abc123def456",
  "access_token_reference_id": "your_reference_id",
  "object": "event",
  "created": "2025-01-15T10:30:00.000Z",
  "type": "patient.insurance.updated",
  "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": "spouse",
    "emr_insurance_id": "51638"
  }
}

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": "No existing insurance found with emr_insurance_id 51638 for patient MRN123456"
  }
}

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

emr_insurance_id · string · required

EMR insurance record ID. This is returned as emr_insurance_id in live fetch and create/update success webhook responses.

Body

application/json

member_id · string

Insurance member/policy ID

Example:

"MEM123456789"

group_id · string

Insurance group number

Example:

"GRP98999"

insurance_provider_id · string

Cobalt insurance provider ID. Use GET /v1/insurance-providers to retrieve valid IDs.

Example:

"insurance-provider-123"

insurance_name · string

Insurance company name

Example:

"Blue Cross Anthem"

insurance_payer_id · string

Insurance payer ID. Must be combined with insurance_name.

Example:

"98999"

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. For eClinicalWorks, non-self values require subscriber_demographics.first_name and subscriber_demographics.last_name.

Example:

"self"

subscriber_demographics · object

Updated insurance subscriber demographics. For eClinicalWorks, if this object is provided it must include first_name and last_name.

Show child attributes

Response

202

application/json

Insurance update queued successfully

success · boolean

message · string

patient_insurance_id · string

job_id · integer