Insurance API FAQ

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

Table of Contents

• Timing and Race Conditions
• Endpoint Usage
• Archive vs Delete Behavior
• Webhooks
• Migration Timeline
• Partial Updates

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

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.saved event will fire for insurance changes, as before.

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.