> ## 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.

# Add Patient Insurance

> Queue the addition of insurance information to a patient record in the EMR system via RPA (Robotic Process Automation).

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.

<Note>
  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.
</Note>

<Note>
  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.
</Note>

## 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):
   ```json theme={null}
   {
     "insurance_provider_id": "abc123def456"
   }
   ```

2. **By Name + Payer ID** (Most specific when ID not available):
   ```json theme={null}
   {
     "insurance_name": "ACME Health",
     "insurance_payer_id": "98999"
   }
   ```

3. **By Name Only** (Least specific, may match first result if multiple exist):
   ```json theme={null}
   {
     "insurance_name": "ACME Health"
   }
   ```

<Note>
  Use `GET /v1/insurance-providers` to retrieve the correct insurance provider identifiers for your organization.
</Note>

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

```bash theme={null}
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",
    "plan_begin_date": "2025-01-01",
    "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)

```bash theme={null}
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": "spouse",
    "subscriber_demographics": {
      "first_name": "Jane",
      "last_name": "Doe",
      "street_line_1": "123 Main St",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "90001-1234"
    }
  }'
```

### Self-Insured Patient with 9-Digit ZIP

```bash theme={null}
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",
    "plan_begin_date": "2025-01-01",
    "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

```json theme={null}
{
  "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)

```json theme={null}
{
  "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,
    "priority": 1,
    "relationship_to_subscriber": "self",
    "emr_insurance_id": "51638"
  }
}
```

<Note>
  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`.
</Note>

<Note>
  `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.
</Note>

### Failure Event (patient.insurance.failed)

```json theme={null}
{
  "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": "Patient not found in EMR system"
  }
}
```

<Note>
  Insurance addition is asynchronous. Store the returned `patient_insurance_id` and `job_id`, then listen for webhooks to determine the final status.
</Note>


## OpenAPI

````yaml POST /patients/{patient_mrn}/insurances
openapi: 3.0.0
info:
  title: Cobalt API
  version: 1.0.1
  description: API for interacting with Cobalt's EHR integration services
servers:
  - url: https://api.usecobalt.com/v1
security:
  - ClientCredentials: []
    ClientSecret: []
    AccessToken: []
paths:
  /patients/{patient_mrn}/insurances:
    post:
      tags:
        - Patients
        - Insurance
      summary: Add insurance to patient
      description: >-
        Queue the addition of insurance information to a patient record in the
        EMR system. This is an asynchronous operation that returns a job_id for
        tracking. Additional fields may be required depending on your EMR system
        - the API will return a 400 error with specific field requirements if
        needed.
      operationId: addPatientInsurance
      parameters:
        - in: path
          name: patient_mrn
          required: true
          schema:
            type: string
          description: The Medical Record Number (MRN) of the patient in the EMR system
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - member_id
              properties:
                member_id:
                  type: string
                  description: Insurance member/policy ID
                  example: MEM123456789
                group_id:
                  type: string
                  description: Insurance group number
                  example: GRP98999
                insurance_provider_id:
                  type: string
                  description: >-
                    Cobalt insurance provider ID (Priority 1). Use GET
                    /v1/insurance-providers to retrieve valid IDs.
                  example: insurance-provider-123
                insurance_name:
                  type: string
                  description: Insurance company name (Priority 2)
                  example: Blue Cross Anthem
                insurance_payer_id:
                  type: string
                  description: Insurance payer ID (Priority 3)
                  example: '98999'
                priority:
                  type: string
                  description: >-
                    Insurance priority level (1=primary, 2=secondary,
                    3=tertiary)
                  enum:
                    - '1'
                    - '2'
                    - '3'
                  example: '1'
                plan_begin_date:
                  type: string
                  format: date
                  pattern: ^\d{4}-\d{2}-\d{2}$
                  description: Insurance coverage start date in YYYY-MM-DD format
                  example: '2026-01-01'
                copayment:
                  type: number
                  minimum: 0
                  description: Copayment amount in dollars
                  example: 25
                relationship_to_subscriber:
                  type: string
                  description: Patient's relationship to insurance subscriber
                  example: self
                subscriber_demographics:
                  type: object
                  description: Insurance subscriber demographics
                  properties:
                    first_name:
                      type: string
                      description: Subscriber's first name
                      example: John
                    last_name:
                      type: string
                      description: Subscriber's last name
                      example: Doe
                    street_line_1:
                      type: string
                      description: Subscriber's street address
                      example: 123 Main Street
                    city:
                      type: string
                      description: Subscriber's city
                      example: Los Angeles
                    state:
                      type: string
                      pattern: ^[A-Za-z]{2}$
                      minLength: 2
                      maxLength: 2
                      description: Two-letter US state code
                      example: CA
                    zip:
                      type: string
                      pattern: ^\d{5}(-\d{4})?$
                      description: 5-digit or 9-digit ZIP code
                      example: '90001'
                    sex:
                      type: string
                      enum:
                        - M
                        - F
                      description: Subscriber's sex
                      example: M
                    dob:
                      type: string
                      format: date
                      description: Subscriber's date of birth in YYYY-MM-DD format
                      example: '1980-01-15'
                    phone:
                      type: string
                      description: Subscriber's phone number
                      example: 555-123-4567
      responses:
        '202':
          description: Insurance addition queued successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  patient_insurance_id:
                    type: string
                  job_id:
                    type: integer
        '400':
          description: Bad request - Missing or invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
        '404':
          description: Insurance provider not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  error:
                    type: string
components:
  securitySchemes:
    ClientCredentials:
      type: apiKey
      in: header
      name: client_id
    ClientSecret:
      type: apiKey
      in: header
      name: client_secret
    AccessToken:
      type: apiKey
      in: header
      name: access_token

````