Key Dates and Deprecation Timeline

Summer 2025 — New Insurance Policy Endpoints POST, PUT, DELETE /patients/{patient_id}/policies were released
April 1st, 2026 — The insurances section of the PatientDemographics resource (/api/2.0/patients/{id}) will be deprecated for writes (insurances section will become read only). You must migrate to the new endpoints before then to avoid disruption starting April 2nd and onward.

Introduction

This comprehensive migration guide provides detailed information for migrating from the legacy Patient Demographics API insurance endpoints to the new Insurance Management System endpoints. After reviewing this guide, please refer to the Insurance API FAQ for answers to common questions about the migration process. If you need additional assistance or encounter issues not covered in this documentation, please contact our support team at support@elationhealth.com.

Note: The information in this guide specifically pertains to the insurances sub-property within Patient Demographics request objects. Other properties of Patient Demographics endpoints remain unchanged.

Definitions & Terms

Legacy Approach

The Legacy Approach refers to the original API patient demographics endpoint (/api/2.0/patients/{id}) and its insurance management methodology. This approach treats insurance information as a sub-property of patient demographics and only supports complete replacement of all insurance records with each update. Any modification to insurance information results in creating entirely new records, with no ability to update individual insurance entries in place or maintain a versioned history of changes.

Versioned Approach

The Versioned Approach refers to the new Insurance Management System that is provided by a dedicated microservice with a set of specialized insurance endpoints. This approach enables granular control over individual insurance records, supporting in-place updates, record swapping, deactivation, and complete version history tracking. A key requirement of this approach is that you must first GET the current insurance information before making any modifications to ensure you have the latest version of the data.

PatientInsurance

A PatientInsurance was used in the legacy system to identify a patient's insurance coverage. It served as the primary data structure for storing insurance information as part of the patient demographics endpoint, containing all insurance-related data in a single record tied to the patient.

Policy

A Policy is used in the versioned approach to represent a patient's insurance coverage in the microservice. It is a first-class citizen with its own unique IDs and complete lifecycle management, enabling granular control over individual insurance records and supporting versioning, updates, and historical tracking.

Enabling Insurance Versioning

Elation uses feature flags to control functionality across our system. The Insurance Versioning feature flag is enabled on a practice-by-practice basis and controls access to the new insurance management capabilities.

When Insurance Versioning is enabled for a practice:

New UI Access: Users can access a new insurance management interface that displays historical versions of Policy models managed by the Insurance Management System
Enhanced Functionality: The practice gains access to granular insurance record management, including in-place updates, record swapping, and complete version history tracking
API Behavior Changes: The legacy patient demographics endpoints (/api/2.0/patients/{id}) begin to support id fields (PatientInsurance IDs) in insurance objects, enabling in-place updates instead of complete replacement

When Insurance Versioning is disabled:

Legacy UI Only: Users continue to use the existing insurance management interface
Standard Legacy Behavior: All insurance updates through the patient demographics endpoint result in complete replacement of insurance records
No Version History: No historical tracking or in-place update capabilities are available

The feature flag primarily affects the user interface experience and the availability of advanced insurance management features, while the underlying API endpoints remain functional regardless of the flag status.

Deleting vs. Archiving

The key difference between the two systems is how they handle record removal:

PatientInsurance Models (Legacy System):

Can only be deleted (permanently removed)

Policy Models (Insurance Management System):

Can be archived (preserved with history) or deleted (gone for good)

Why This is Changing

We are introducing new dedicated insurance endpoints that will replace the insurance sub-property within the patient demographics endpoint. Let's examine the limitations of the current approach and how the new Insurance Versioning system addresses these challenges.

Legacy API (/api/2.0/patients/{id}) limitations:

Only supported complete replacement of insurance information
Any change created a new record with no "in place" updates
No versioned history tracking
Led to billing confusion
Limited auditability
Difficulty supporting accurate claims

Insurance Versioning improvements:

Ability to update individual insurance records
Support for swapping insurance records
Deactivation of individual records
Complete history retention
Reduced billing errors
More reliable insurance management
Better alignment with industry record-keeping practices

What Changes for You

Old Flow (Patient Demographics Endpoints)

Updating insurance information meant sending the entire insurances array in a PUT /api/2.0/patients/{id} request.
Every change replaced all insurances; any not present were deleted, and new ones were created
Insurance card images were managed through patient insurance priority (primary, secondary, tertiary) rather than direct Policy IDs

New Flow (Insurance Versioning Endpoints)

It is now necessary to check the latest state of insurances before performing operations.
- GET /patients/{patient_id}/policies - Get the list of policies
- GET /patients/{patient_id}/policies/{policy_id} – Get a specific policy by ID
Use new endpoints such as:
- POST /patients/{patient_id}/policies – Create a new insurance policy
- PUT /patients/{patient_id}/policies/{policy_id} – Update an existing insurance policy in-place
- DELETE /patients/{patient_id}/policies/{policy_id} – Deactivate (archive) a policy, preserving history
Insurance card images are now tightly linked to Policy IDs (no more issues with "orphan" images). The new policy-based endpoints work directly with Policy IDs:
- POST /patients/{patient_id}/policies/{policy_id}/card-images – Upload insurance card images
- GET /patients/{patient_id}/policies/{policy_id}/card-images – Get insurance card images
- DELETE /patients/{patient_id}/policies/{policy_id}/card-images/{image_rank} – Delete specific insurance card image

What's Backward Compatible

For now, the legacy PUT /api/2.0/patients/{id} endpoint remains available for insurance updates. With the new Insurance Management feature:

If you include a PatientInsurance id for each insurance object in insurances, Elation will update that record in place.
If you exclude the PatientInsurance id, a new record will be created.

Any insurance record not present in the submission is archived and moved to historical (not deleted). When using the original patient demographics endpoint without providing PatientInsurance IDs, associated insurance card images are automatically migrated to the new Policy records to ensure continuity.

Field Differences

Field Category	Patient Demographics Insurance	Insurance Management Service	Relationship	Notes
Patient Info
Patient DOB	`patient_dob: str`	`patient_dob: date`	Type Change	Patient Demographics Insurance uses string, Insurance Management Service uses date (JSON: "YYYY-MM-DD" format)
Policy Details
Policy Rank	`rank: int`	`rank: Optional[int]`	Nullability Change	Patient Demographics Insurance required, Insurance Management Service optional
Copay Amount	`copay: Optional[float]`	`copay: Optional[str]`	Type Change	Patient Demographics Insurance uses float, Insurance Management Service uses string. String representation is more predictable across different clients and languages. Validated with regex: `^-?\d8(.\d10)?$
Deductible Amount	`deductible: Optional[float]`	`deductible: Optional[str]`	Type Change	Patient Demographics Insurance uses float, Insurance Management Service uses string. String representation is more predictable across different clients and languages. Validated with regex: `^-?\d8(.\d10)?$
Insurance References
Carrier ID	`insurance_company: Optional[int]`	`carrier_id: Optional[int]`	Name Change	Same value, different field name
Plan ID	`insurance_plan: Optional[int]`	`plan_id: Optional[int]`	Name Change	Same value, different field name
Insurance Names
Carrier Name	`carrier: Optional[str]`	`carrier_name: Optional[str]`	Name Change	Same value, different field name
Plan Name	`plan: Optional[str]`	`plan_name: Optional[str]`	Name Change	Same value, different field name
Status & Control
Active Status	N/A	`status: Status`	New Field	Insurance Management Service adds status enum: "active" or "inactive"
Insured Person Details
Insured Person DOB	`insured_person_dob: Optional[str]`	`insured_person_dob: Optional[date]`	Type Change	Patient Demographics Insurance uses string, Insurance Management Service uses date (JSON: "YYYY-MM-DD" format)
Insured Person Gender	`insured_person_gender: Optional[str]`	`insured_person_sex_at_birth: Optional[str]`	Name Change	Same value, different field name
Relationship to Insured	`relationship_to_insured: Optional[str]`	`relationship_to_insured: Optional[InsurerRelationship]`	Type Change	Patient Demographics Insurance uses string, Insurance Management Service uses enum: "self", "child", "spouse", or "other"
Payment & Programs
Payment Program	`payment_program: Optional[str]`	`payment_program: Optional[InsurancePaymentProgram]`	Type Change	Patient Demographics Insurance uses string, Insurance Management Service uses enum: "medicare_part_b", "medicare_advantage", "medicaid", "commercial_hmsa", "commercial_sfhp", "commercial_other", or "workers_compensation"
Timestamps
Created Date	`created_date: Optional[str]`	N/A	Removed	Patient Demographics Insurance has this field, Insurance Management Service doesn't
Deleted Date	`deleted_date: Optional[str]`	N/A	Removed	Patient Demographics Insurance has this field, Insurance Management Service doesn't
Insurance Card Images
Front Image Path	N/A	`front_image_path: Optional[str]`	New Field	Pre-signed URL to the original, uncompressed front image of the insurance card. Can be used to display or download the full-resolution front image.
Back Image Path	N/A	`back_image_path: Optional[str]`	New Field	Pre-signed URL to the original, uncompressed back image of the insurance card. Can be used to display or download the full-resolution back image.
Internal Fields
Vendor Company ID	N/A	`vendor_company_id: Optional[int]`	New Field	Internal field for data migration/processing
Vendor External ID	N/A	`vendor_external_id: Optional[str]`	New Field	Internal field for data migration/processing

Summary of Field Changes

Field Name Changes

insurance_company → carrier_id
insurance_plan → plan_id
carrier → carrier_name
plan → plan_name
insured_person_gender → insured_person_sex_at_birth

Type Changes

patient_dob: str → date (JSON: "YYYY-MM-DD" format)
insured_person_dob: str → date (JSON: "YYYY-MM-DD" format)
copay: float → string (String representation is more predictable across different clients and languages. Validated with regex: ^-?\d{1,8}(\.\d{1,10})?$|^$)
deductible: float → string (String representation is more predictable across different clients and languages. Validated with regex: ^-?\d{1,8}(\.\d{1,10})?$|^$)
relationship_to_insured: str → InsurerRelationship enum ("self", "child", "spouse", or "other")
payment_program: str → InsurancePaymentProgram enum ("medicare_part_b", "medicare_advantage", "medicaid", "commercial_hmsa", "commercial_sfhp", "commercial_other", or "workers_compensation")

New Fields in Insurance Management Service

status (enum: "active" or "inactive")
front_image_path, back_image_path (Pre-signed URLs to original, uncompressed insurance card images)
vendor_company_id, vendor_external_id (Internal fields for data migration/processing)

Removed Fields

created_date, deleted_date (timestamp fields)

Nullability Changes

rank: Required in Patient Demographics Insurance → Optional in Insurance Management Service

Key Migration Gotchas

Do not manipulate the PatientInsurance "id" field directly; provide it to update, omit to create new.
When using the original patient demographics endpoint without PatientInsurance IDs, insurance card images are automatically migrated to new Policy records.
Practices with Insurance Versioning enabled will reject insurance card uploads without a Policy ID, returning 422 errors.
PUT of an empty insurances array on legacy endpoints will archive (deactivate) all policies.
Fields required for /policies (some must be passed even on update): patient_dob, patient_first_name, patient_last_name.

Syncing Flows

The following sections go much deeper into how the legacy PatientInsurance model is modified via the original API patient demographics endpoints, and how those modifications translate into the new Policy models managed by Insurance Management System.

Note: The following is optional documentation and shared so that you can better understand how the two APIs are currently supported. This is only necessary to understand if you are using PatientInsurance IDs with the Legacy endpoints. It may also be helpful in understanding how data flows between the new Insurance Versioning UI and the legacy UI.

In the following discussion we're going to use the acronym IMS to represent the Insurance Management System.

Key Decision Points

The major difference between these scenarios is whether you provide PatientInsurance id values in your insurance objects. Providing a PatientInsurance ID allows the system to update existing records in place, preserving associated data like insurance card images. Omitting PatientInsurance IDs forces the creation of new records, which archives the old ones, but when using the original patient demographics endpoint, insurance card images are automatically migrated to maintain continuity.

flowchart LR
    A[Patient Demographics Update] --> B{Has PatientInsurance id?}
    B -->|Yes| C[Update in-place]
    B -->|No| D[Create new record]
    
    C --> E[Preserve existing Policy]
    D --> F[Archive old Policy]
    
    E --> G[✅ Images remain linked]
    F --> H["✅ Previous Policy Images Migrated (Legacy endpoint only)"]

Insurance Management System to Legacy System Synchronization

sequenceDiagram
    participant API as API Client
    participant IMS as Insurance Management Service
    participant EventStream as Event Stream
    participant Legacy as Legacy System
    participant DB as Legacy Database

    API->>IMS: POST/PUT/DELETE /patients/\{id\}/policies
    IMS->>IMS: Process Policy Change
    IMS->>EventStream: Publish Policy Event
    Note over EventStream: Event contains policy data and change type (create/update/delete)
    EventStream->>Legacy: Consume Policy Event
    Legacy->>Legacy: Transform to PatientInsurance format
    Legacy->>DB: Update Patient Demographics
    Note over Legacy,DB: Legacy PatientInsurance records are updated/created/deactivated
    Legacy-->>IMS: Event Processing Complete

Legacy System to Insurance Management System Synchronization

sequenceDiagram
    participant API as API Client
    participant Legacy as Legacy System
    participant EventStream as Event Stream
    participant IMS as Insurance Management Service
    participant DB as IMS Database

    API->>Legacy: PUT /api/2.0/patients/\{id\} (legacy)
    Legacy->>Legacy: Process PatientInsurance Changes
    Legacy->>EventStream: Publish PatientDemographics Event
    Note over EventStream: Event contains legacy PatientInsurance data
    EventStream->>IMS: Consume PatientDemographics Event
    IMS->>IMS: Transform to Policy format
    IMS->>DB: Create/Update Policy Records
    Note over IMS,DB: New Policy records created or existing ones updated
    IMS->>IMS: Migrate Card Images
    Note over IMS,IMS: Only migrated if PatientInsurance is not provided in legacy flow
    IMS-->>Legacy: Event Processing Complete