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

# Update Patient Insurance

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

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

<Note>
  Insurance updates are currently supported for `eClinicalWorks` only.
</Note>

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

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

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

```bash theme={null}
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:

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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

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

```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.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)

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


## OpenAPI

````yaml PATCH /patients/{patient_mrn}/insurances/{emr_insurance_id}
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/{emr_insurance_id}:
    patch:
      tags:
        - Patients
        - Insurance
      summary: Update patient insurance
      description: >-
        Queue an update to an existing patient insurance record. Insurance
        updates are currently supported for eClinicalWorks only. Use the
        `emr_insurance_id` returned from patient live fetch (`include:
        ["insurances"]`) or a prior insurance success webhook.
      operationId: updatePatientInsurance
      parameters:
        - in: path
          name: patient_mrn
          required: true
          schema:
            type: string
          description: The Medical Record Number (MRN) of the patient in the EMR system
        - in: path
          name: emr_insurance_id
          required: true
          schema:
            type: string
          description: >-
            EMR insurance record ID. This is returned as `emr_insurance_id` in
            live fetch and create/update success webhook responses.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              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. Use GET
                    /v1/insurance-providers to retrieve valid IDs.
                  example: insurance-provider-123
                insurance_name:
                  type: string
                  description: Insurance company name
                  example: Blue Cross Anthem
                insurance_payer_id:
                  type: string
                  description: Insurance payer ID. Must be combined with `insurance_name`.
                  example: '98999'
                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. For
                    eClinicalWorks, non-self values require
                    `subscriber_demographics.first_name` and
                    `subscriber_demographics.last_name`.
                  example: self
                subscriber_demographics:
                  type: object
                  description: >-
                    Updated insurance subscriber demographics. For
                    eClinicalWorks, if this object is provided it must include
                    `first_name` and `last_name`.
                  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: F
                    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 update 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: >-
            User or insurance provider not found, or insurance provider cannot
            be used for eClinicalWorks
          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

````