Common questions about migrating Insurance from the legacy Patient Demographics API Endpoints to the new Insurance Management Endpoints
This FAQ addresses common questions about the migration from the Patient Demographics API Endpoints to the new Insurance Management Endpoints. For comprehensive migration guidance, detailed workflow diagrams, and complete endpoint documentation, please refer to the Migration Guide. If you need additional assistance or encounter issues not covered in this documentation, please contact our support team at [email protected].
Policy Rank
Q: What is Policy Rank and how is it defined?
A: Policy rank determines the order of insurance coverage for a patient, indicating whether an insurance policy is the patient's primary, secondary, or tertiary insurance. The rank values are defined as follows:
| Rank Value | Description |
|---|---|
1 | Primary Insurance |
2 | Secondary Insurance |
3 | Tertiary Insurance |
Q: Is Policy Rank required for insurance policies?
A: While the rank field is technically marked as Optional[int] = None in the API, active policies must have a rank to function properly. Policies without a rank are typically inactive or placeholder policies.
Q: How is Policy Rank assigned and can it be automatically determined?
A: Policy rank is not automatically determined by the system. Users must explicitly assign ranks through the UI or API. There is no business logic that automatically assigns ranks based on policy type, dates, or other criteria.
Q: What happens when I assign a rank to a policy?
A: Only one active policy can exist per rank per patient. When you assign a rank to a new policy, any existing active policy with the same rank is automatically deactivated, and the new policy becomes the active policy for that rank. This ensures patients always have exactly one primary, one secondary, and one tertiary policy (when applicable).
Q: What should integrators watch out for when using rank in the API?
A: Here are important considerations for integrators working with policy ranks:
- Always specify rank for active policies - Don't rely on the system to determine it
- Rank conflicts are resolved automatically - The system handles deactivating conflicting policies, where the incoming policy replaces (archives) the current active policy of that same rank
- Rank is patient-specific - Each patient can have their own set of ranked policies
- Inactive policies can have any rank - Only active policies enforce the "one per rank" rule
- Rank changes trigger automatic cleanup - When updating a policy's rank, the system ensures no duplicate active ranks exist
Error Handling:
- Policies without ranks are typically treated as inactive
- The system will reject requests that would create duplicate active ranks
- Always check the response to confirm the policy was created/updated as expected
Q: What field changes should I be aware of when migrating from Patient Demographics to Insurance Management endpoints?
A: There are several important field changes when migrating from the legacy Patient Demographics insurance endpoints to the new Insurance Management endpoints. These include field name changes, type changes, new fields, and removed fields. For a comprehensive breakdown of all field differences, including detailed mapping tables and migration guidance, see the Field Differences section in the migration guide.
Timing and Race Conditions
Q: Is there a recommended wait time after creating a Policy before attempting insurance image creation to avoid race conditions?
A: We recommend using the GET endpoints to verify when changes have been applied rather than relying on a fixed wait time. After creating a policy, use GET /patients/{patient_id}/policies to confirm the policy is available before attempting to upload insurance card images.
Note: There is currently a webhook for the eventual sync to the legacy system which then triggers a patient change event. However, this webhook will eventually be removed as the expectation is that integrators will interact directly with the Insurance Management System. Additionally, since the integrator initiated the change, they would not see a change come through the webhook flow anyway. For more details on the synchronization process, see Insurance Management System to Legacy System Synchronization.
Endpoint Usage
Q: Did we publish new insurance_cards endpoints that integrators should be using, or are they still expected to use the patient API paths?
A: Integrators should use the new IMS policy-based endpoints for image manipulation. The new insurance card image 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
These new endpoints tie card images directly with their assocaited Policy. The legacy endpoints using insurance_rank are still available for backward compatibility but should be migrated to the new policy-based endpoints. For more information on how insurance card images are managed, see New Flow (Insurance Versioning Endpoints).
Archive vs Delete Behavior
Q: The legacy API treats PUT with an empty insurances array as mass delete — for Insurance Management, should this behavior become mass deactivate via an IMS event, and reserve true deletes for new endpoints?
A: Yes, this behavior has been updated. When Insurance Management is enabled:
PUT /api/2.0/patients/{id}with an empty insurances array now archives (deactivates) all Policy records in IMS, preserving history- True deletion is reserved for the new IMS endpoints (
DELETE /patients/{patient_id}/policies/{policy_id}) - This maintains the distinction between archiving (preserving history) and deletion (permanent removal)
For detailed workflow diagrams showing this behavior, see Legacy System to Insurance Management System Synchronization.
Webhooks
Q: Will insurance-specific webhooks be introduced, or do changes continue to arrive via patient webhooks only?
A: No – Elation does not currently offer direct insurance webhook events. The existing patients event will fire for insurance changes, as before.
Q: How will I be notified of insurance changes when using the new Insurance Management endpoints?
A: The existing webhook system will continue to trigger for insurance changes. When you make changes through the new Insurance Management endpoints, the system will synchronize those changes to the legacy system, which will then trigger the standard patients webhook event. For a detailed overview of how this synchronization process works, see the Insurance Management System to Legacy System Synchronization section in the migration guide.
Migration Timeline
Q: When will practices be forced to adopt IMS endpoints versus opting in via a feature flag, and is October 31 a hard cutover or target date?
A: October 31, 2025 is the target deprecation date for the insurance sub-property within the Patient Demographics endpoint. After this date, integrators cannot rely on the legacy PatientDemographics insurance fields to update or retrieve insurance data. The new IMS endpoints will become the required method for insurance management. For the complete migration timeline, see Key Dates and Deprecation Timeline.
Partial Updates
Q: Are partial updates (PATCH) or field-specific updates supported?
A: All updates are via PUT, and your request should include all intended values for the policy.
Data Warehouse
Q: How will the migration to Insurance Management endpoints affect my existing data warehouse solution?
A: No migration is necessary for your data warehouse. The Insurance Management System synchronizes changes to the legacy system, so your existing data warehouse solution will continue to receive the same data format and structure it has always used. For details on how this synchronization works, see Insurance Management System to Legacy System Synchronization.