Insurance

Overview

The insurance endpoints let you access and manage the insurance information tied to a practice and its patients. There are two related resources:

• Insurance plans (/insurance_plans, /insurance_plans/{id}) hold general information about an insurance policy — payer ID, group number, employer name, carrier address, fee schedule, and benefit details like annual_max_individual and benefit_year_renewal_month. A plan represents the policy itself, independent of any one patient.
• Insurance coverages (/insurance_coverages, /insurance_coverages/{id}) connect a patient to an insurance plan. A coverage holds patient-specific details: the subscriber number, the patient's relationship to the subscriber (subscription_relation), coverage priority, and effective/expiration dates. A patient can have more than one active coverage (e.g. primary and secondary).
• Insurance plans can be fetched with patient_coverages, subscribers, and fee_schedule sideloaded via include[]. Coverages default to returning only active records — pass active=false to see inactive ones.
• Use the write endpoints to keep insurance data current: POST /insurance_plans creates a plan, POST /insurance_coverages posts an insurance record to a patient's chart (either against an existing subscriber via subscriber_id, or by creating a new subscription inline via insurance_subscription), and DELETE /insurance_coverages/{id} removes a coverage — for example, when a patient's policy lapses or was entered in error.

Example use cases

• Show patients which insurance plans and coverages are on file in a patient portal, so they can confirm their information is current before an appointment.
• Automatically create an insurance coverage record when a patient submits new insurance information through an online intake form, keeping the EHR in sync without manual data entry.
• Surface each coverage's benefits_remaining and the plan's annual_max_individual to front-desk staff before treatment planning, so they can flag patients who may be close to exhausting their annual benefit.