Skip to main content
PATCH
/
patients
/
{patient_mrn}
/
insurances
/
{emr_insurance_id}
Update patient insurance
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"
  }
}
'
{
  "success": true,
  "message": "<string>",
  "patient_insurance_id": "<string>",
  "job_id": 123
}

Documentation Index

Fetch the complete documentation index at: https://docs.usecobalt.com/llms.txt

Use this file to discover all available pages before exploring further.

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.

Response

Insurance update queued successfully

​
success
boolean
​
message
string
​
patient_insurance_id
string
​
job_id
integer