Documentation Index
Fetch the complete documentation index at: https://help.elationhealth.com/llms.txt
Use this file to discover all available pages before exploring further.
Key Dates and Deprecation Timeline
- Summer 2025 — New Insurance Policy Endpoints
POST, PUT, DELETE /patients/{patient_id}/policieswere 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
APatientInsurance 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
APolicy 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
Policymodels 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 supportidfields (PatientInsurance IDs) in insurance objects, enabling in-place updates instead of complete replacement
- 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
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)
- 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
- 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 policiesGET /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 policyPUT /patients/{patient_id}/policies/{policy_id}– Update an existing insurance policy in-placeDELETE /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 imagesGET /patients/{patient_id}/policies/{policy_id}/card-images– Get insurance card imagesDELETE /patients/{patient_id}/policies/{policy_id}/card-images/{image_rank}– Delete specific insurance card image
What’s Backward Compatible
For now, the legacyPUT /api/2.0/patients/{id} endpoint remains available for insurance updates. With the new Insurance Management feature:
- If you include a PatientInsurance
idfor each insurance object in insurances, Elation will update that record in place. - If you exclude the PatientInsurance
id, a new record will be created.
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: `^-?\d(.\d)?$ | ^$` |
| 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: `^-?\d(.\d)?$ | ^$` |
| 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_idinsurance_plan→plan_idcarrier→carrier_nameplan→plan_nameinsured_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→InsurerRelationshipenum (“self”, “child”, “spouse”, or “other”)payment_program:str→InsurancePaymentProgramenum (“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.
PUTof 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 legacyPatientInsurance 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 PatientInsuranceid 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.