Skip to main content
POST
Add insurance to a patient
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.
member_id is the subscriber/member number you provide (the policy number from the insurance card), not an EHR-generated value. The EHR-generated record identifier is emr_insurance_id, returned on the webhook after the record is created.

​
Insurance Provider Resolution

The API supports three methods for identifying the insurance provider (in order of priority):
  1. By Cobalt Provider ID (Most specific, recommended):
  2. By Name + Payer ID (Most specific when ID not available):
  3. By Name Only (Least specific, may match first result if multiple exist):
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”)
  • plan_end_date: Optional. Must be in YYYY-MM-DD format (e.g., “2025-12-31”). Omit for open-ended coverage.

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

​
Complete Request (Using Insurance Name + Payer ID)

​
Self-Insured Patient with 9-Digit ZIP

​
Example Response

​
Webhook Events

After the insurance addition is processed, a webhook event will be sent to your configured webhook URL.

​
Success Event (patient.insurance.added)

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)

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

Patient MRN.

Body

application/json
​
member_id
string
required

Insurance member / subscriber ID.

Example:

"MEM123456789"

​
group_id
string

Insurance group number.

Example:

"GRP98999"

​
insurance_provider_id
string

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

Example:

"insurance-provider-123"

​
insurance_payer_id
string

Insurance payer ID, used to disambiguate insurance_name.

Example:

"98999"

​
insurance_name
string

Insurance provider name (one insurance identifier).

Example:

"Blue Cross Anthem"

​
subscriber_demographics
object

Policy holder demographics.

​
relationship_to_subscriber
string

Patient relationship to the policy holder.

Example:

"self"

​
insurance_policy_type
string

Insurance policy type / coverage category.

Example:

"PPO"

​
insurance_sequence
string

Coverage order (e.g. primary / secondary).

Example:

"primary"

​
plan_begin_date
string<date>

Plan begin date (YYYY-MM-DD).

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

"2026-01-01"

​
plan_end_date
string<date>

Plan end date (YYYY-MM-DD). Omit for open-ended coverage.

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

"2026-12-31"

​
copayment
number

Copayment amount.

Required range: x >= 0
Example:

25

​
priority
enum<string>

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

Available options:
1,
2,
3
Example:

"1"

​
update_patient_demographics
boolean

Whether to also update the patient demographics in the EMR. Defaults to true.

​
update_if_exists
boolean

Update the matching insurance if one already exists instead of adding a new record. Defaults to false.

​
check_eligibility
boolean

Run an eligibility check after the insurance is added. Defaults to false.

​
callback_urls
string[]

URLs to receive the completion webhook, in addition to the account webhook.

Response

Operation queued for processing

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