> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Insurance & Eligibility

> Manage patient insurance policies, coordination of benefits order, and run real-time eligibility checks.

The Insurance & Eligibility panel surfaces within the patient record at `/pm/patients/:patientId` (Insurance tab) and gives billing staff a per-patient view of active policies and eligibility check history.

## Overview

The insurance panel lists all insurance policies attached to a patient, ordered by coordination of benefits (COB) priority (`primary`, `secondary`, `tertiary`). Each policy card displays the payer name, policy status badge, effective and termination dates, and the result of the most recent eligibility check. A coverage-gap alert fires when no active policies are on file or when the latest check for an active policy returned ineligible or is overdue. Users with `pm.insurance.manage` permission can add, edit, terminate, or soft-delete policies and adjust COB priority order. When the module setting `cob_order_change_triggers_reverification` is enabled, reordering policies automatically prompts an eligibility re-check.

## Who it's for

Requires `pm.insurance.view` (`PM_PERMISSIONS.INSURANCE_VIEW`). Manage actions (add, edit, terminate, delete, run eligibility) additionally require `pm.insurance.manage` (`PM_PERMISSIONS.INSURANCE_MANAGE`).

## Before you start

* Navigate to a patient record at `/pm/patients/:patientId` and select the **Insurance** tab.
* The patient must exist in the system and your role must include `pm.insurance.view`.

## Steps

<Steps>
  <Step title="Open the patient's Insurance tab">
    From the patient detail page, select the **Insurance** tab to load the policy list and eligibility check history.
  </Step>

  <Step title="Review policy cards">
    Each card shows payer name, COB priority (Primary / Secondary / Tertiary), policy status badge, effective dates, and the latest eligibility check result. A destructive alert banner appears if no active policies are found or an active policy is ineligible or overdue.
  </Step>

  <Step title="Add or edit a policy">
    Users with `pm.insurance.manage` may click **Add Policy** (top-right) or the edit action on an existing card to open the policy form dialog.
  </Step>

  <Step title="Run an eligibility check">
    Click the run-check action on a policy card to open the eligibility dialog. The check queries `pm_eligibility_checks` and updates the latest-check badge on the card.
  </Step>

  <Step title="Adjust COB order">
    Use the priority selector on each card to change the COB order. If the module setting `cob_order_change_triggers_reverification` is on, a re-verification prompt opens automatically.
  </Step>

  <Step title="Terminate or remove a policy">
    Terminate marks the policy end date; soft-delete sets `deleted_at` and hides the policy from the active list. Both require `pm.insurance.manage`.
  </Step>
</Steps>

## Key concepts

<AccordionGroup>
  <Accordion title="No active policies (empty state)">
    When no active policies are found, a destructive banner reads "No active insurance policies on file. Claims may be rejected." An empty-state card prompts adding the first policy.
  </Accordion>

  <Accordion title="Eligibility issue alert">
    Fires when at least one active policy has a latest check with `eligible === false` or when `next_check_due` is in the past.
  </Accordion>
</AccordionGroup>

**COB Priority** — Coordination of Benefits order. Policies are ranked 1 (Primary), 2 (Secondary), 3 (Tertiary) and billed in that sequence.

**Eligibility check** — A query against `pm_eligibility_checks` that records whether the payer confirmed active coverage on the check date.

**Benefit Detail Panel** — An expandable panel on a policy card (component `BenefitDetailPanel`) that shows plan benefit details returned from the eligibility response.

## Related

<Columns cols={2}>
  <Card title="Practice Management" icon="briefcase" href="/pm/overview">
    Overview of the Practice Management core.
  </Card>

  <Card title="Governance & parity" icon="scale-balanced" href="/governance/index">
    Documentation coverage and governance.
  </Card>
</Columns>

<Note>
  This page documents shipped product behavior. It is not medical, legal, or
  billing advice. Verify against your organization's policies and applicable
  regulations before using it for clinical, compliance, or billing decisions.
  Protected health information (PHI) shown in the product is governed by your
  tenant's access controls and is never exposed in this documentation.
</Note>

<Accordion title="Documentation sources">
  * src/routes/pm.tsx
  * src/cores/pm/components/PatientInsuranceList.tsx
  * src/cores/pm/hooks/useInsurancePolicyList.ts
  * src/cores/pm/hooks/useEligibilityCheckList.ts
  * src/platform/permissions/constants.ts
  * src/platform/navigation/route-labels.ts
</Accordion>