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

# Payer Management

> Configure and manage insurance payers for eligibility verification and claims submission, with search, type filtering, and active/inactive toggle.

This page lists and manages insurance payer configurations for your organization, accessible at the route `/pm/payers`.

## Overview

The Payer Management page displays a card-based list of insurance payers from `pm_payers`, scoped to the current organization. By default, only active payers are shown. Each card displays the payer name, payer type badge, electronic payer ID, and phone number. Users with `pm.payers.manage` permission see **Edit**, **Activate/Deactivate**, and **Remove** controls on each card. Supported payer types are: Commercial, Medicaid, Medicare, TRICARE, Workers' Comp, and Other. The page provides a live search input (filters by payer name), a payer type dropdown, and a "Show inactive" toggle. Soft-deleting a payer hides it from dropdowns but does not affect existing policy references; deactivating removes it from new policy dropdowns while leaving existing policies intact.

## Who it's for

Requires permission `PM_PERMISSIONS.PAYERS_VIEW` (`pm.payers.view`), enforced via `RequirePermission` in `src/routes/pm.tsx`. Editing, activating/deactivating, and removing payers additionally requires `PM_PERMISSIONS.PAYERS_MANAGE` (`pm.payers.manage`), gated via `PermissionGate` on the action controls.

## Before you start

* Your account must hold the `pm.payers.view` permission to see the payer list.
* `pm.payers.manage` is required to add, edit, deactivate, or remove payers.

## Steps

<Steps>
  <Step title="Navigate to Payer Management">
    Go to **Practice Management → Payers** (route `/pm/payers`). The page loads active payers for the current organization, sorted alphabetically by payer name.
  </Step>

  <Step title="Filter the list">
    Use the **search input** to filter by payer name, the **payer type dropdown** to filter by type (Commercial, Medicaid, Medicare, TRICARE, Workers' Comp, Other), or the **Show inactive** toggle to include inactive payers.
  </Step>

  <Step title="Add a new payer">
    Click **Add Payer** (requires `pm.payers.manage`) to open the PayerFormDialog in create mode. Complete the form and save.
  </Step>

  <Step title="Edit an existing payer">
    Click the pencil icon on any payer card (requires `pm.payers.manage`) to open the PayerFormDialog in edit mode.
  </Step>

  <Step title="Deactivate or activate a payer">
    Click **Deactivate** or **Activate** on a payer card (requires `pm.payers.manage`). A confirmation dialog explains the impact before the action is applied.
  </Step>

  <Step title="Remove a payer">
    Click the trash icon on a payer card (requires `pm.payers.manage`). A confirmation dialog warns that the payer will be soft-deleted and hidden from dropdowns.
  </Step>
</Steps>

## Key concepts

<AccordionGroup>
  <Accordion title="Payer types">
    The system recognizes: **Commercial**, **Medicaid**, **Medicare**, **TRICARE**, **Workers' Comp**, and **Other**. These are stored as `payer_type` on the payer record and rendered as colored badges (Medicaid/Medicare = default, Commercial/TRICARE = secondary, Workers' Comp/Other = outline).
  </Accordion>

  <Accordion title="Active vs. inactive vs. soft-deleted">
    * **Active** (`is_active: true`): payer appears in all dropdowns.
    * **Inactive** (`is_active: false`): payer hidden from new policy dropdowns; existing policies unaffected. Visible via the "Show inactive" toggle.
    * **Soft-deleted** (`deleted_at` set): payer hidden from all dropdowns and from this list entirely. Existing policies referencing this payer are not affected.
  </Accordion>

  <Accordion title="Electronic payer ID">
    Each payer may have an `electronic_payer_id` used for EDI/clearinghouse transactions. Cards display this as "Payer ID: {value}" or "No electronic payer ID" if absent.
  </Accordion>

  <Accordion title="Empty state">
    When no payers match the current filters, an empty state is shown. The message adapts based on whether filters are active or no payers exist at all.
  </Accordion>
</AccordionGroup>

## 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/pages/PayersListPage.tsx
  * src/cores/pm/hooks/usePayerList.ts
  * src/cores/pm/hooks/usePayerMutation.ts
  * src/platform/permissions/constants.ts
</Accordion>