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

# Claims

> List, search, batch-submit, and view detail for professional and institutional claims — including scrub, notes, denials, and void workflows.

The Claims screen (`/pm/claims`) provides a filterable list of claims from `pm_claims` with tools for generating, submitting, and tracking claim status.

## Overview

The screen renders a card list of claims, each displaying the claim number, status badge, claim type (837P Professional or 837I Institutional), filing deadline indicator, service date range, total charge, and paid amount (if available). Claims are loaded from `pm_claims` ordered by creation date descending, always scoped to the current organization and excluding soft-deleted records. Users can filter by status and search by claim number. Checkboxes on each card (and a "select all on page" control) allow batch selection; the **Batch Selection Toolbar** appears when items are selected and lets authorized users submit the batch to the clearinghouse. A **BatchProgressDialog** shows real-time processing results. Clicking a claim card navigates to `/pm/claims/:claimId` for detail view.

## Who it's for

Requires the `pm.claims.view` permission. Additional permissions gate specific actions:

* `pm.claims.create` — Generate Claims button
* `pm.claims.submit` — Clean Claim Wizard button
* `pm.batch.claim_submit` — Submit to clearinghouse batch action

## Before you start

Requires the `pm.claims.view` permission. Claims will not load if no organization is currently selected. Batch submission is limited by the batch size maximum retrieved from `useBatchSettings`.

## Steps

<Steps>
  <Step title="Search and filter claims">
    Enter a claim number in the search field to filter by claim number (partial match). Use the status dropdown to filter by a specific status: Draft, Scrubbed, Submitted, Accepted, Paid, Partial Payment, Denied, Appealed, Void, or Adjusted.
  </Step>

  <Step title="Select claims for batch submission">
    Check individual claim checkboxes, or use **Select all on page** to select all visible claims. Only claims in **Draft** or **Scrubbed** status are eligible for batch submission; ineligible selected claims are silently excluded from the batch.
  </Step>

  <Step title="Submit selected claims to the clearinghouse">
    With claims selected, click **Submit to clearinghouse** in the Batch Selection Toolbar (requires `pm.batch.claim_submit`). The BatchProgressDialog opens and shows real-time progress. A success toast reports how many claims were submitted; a warning toast indicates partial completion with errors.
  </Step>

  <Step title="Generate new claims">
    Click **Generate Claims** (requires `pm.claims.create`) to open the `ClaimGenerateDialog`.
  </Step>

  <Step title="Use the Clean Claim Wizard">
    Click **Clean Claim Wizard** (requires `pm.claims.submit`) to open the `ClaimSubmissionWizard` for guided single-claim submission.
  </Step>

  <Step title="Open a claim for detail">
    Click any claim card to navigate to the claim detail page at `/pm/claims/:claimId`.
  </Step>

  <Step title="Update a claim's status">
    Use the status menu (rendered by `ClaimStatusMenu`) on each claim card to transition the claim to a permitted next status without opening the full detail page.
  </Step>
</Steps>

## Key concepts

<Tooltip tip="Standard electronic data interchange transaction set for professional claims (physicians, practitioners)">837P</Tooltip> and <Tooltip tip="Standard EDI transaction set for institutional claims (hospitals, facilities)">837I</Tooltip> are the two claim types supported. Filing deadline indicators appear on claim cards: an **Expired** badge (red) signals the deadline has passed; a days-remaining badge (e.g. "14d left") appears when fewer than 30 days remain before the filing deadline.

<AccordionGroup>
  <Accordion title="Empty state — no claims found">
    When no claims match the current filters, the screen shows "No claims match the current filters." When no claims exist at all, it shows "Generate claims from approved charges to get started."
  </Accordion>

  <Accordion title="Batch history">
    After a batch completes, a **View History** button in the BatchProgressDialog navigates to `/pm/batch-history` to review past batch runs.
  </Accordion>
</AccordionGroup>

## Viewing a claim

Selecting a claim card opens the claim detail page at `/pm/claims/:claimId` (permission: `pm.claims.view`). A four-card summary row shows Total Charge, Paid, Adjustment, and Patient Responsibility amounts. A `ClaimLineagePanel` renders claim lineage. If `denial_codes` are present, they appear above the tabs via `DenialCodeDisplay`. The tabbed interface provides: **Lines** (claim line items with CPT, modifiers, units, date, charge/paid amounts), **Scrub** (on-demand client-side claim scrubbing via `scrubClaim()` — requires `pm.claims.update`), **Notes** (note form + list), **Denials** (linked denials via `ClaimDenialSummaryPanel`), and **Secondary Claims** (requires `pm.cob.view`). For institutional claims (`claim_type === 'institutional_837i'`), additional UB-04 Details, Preview 837I, and Generate 837I actions appear in the header when the user has `PM_PERMISSIONS.INSTITUTIONAL_CLAIMS_GENERATE_837I`. Void and Create Replacement actions appear based on claim status and `pm.claims.void` permission.

**Additional permissions for claim detail:**

* `pm.claims.update` — Run scrubbing, add notes
* `pm.claims.void` — Void or replace claims
* `pm.cob.view` — Secondary Claims tab
* `pm.institutional_claims.generate_837i` — Generate/Preview 837I
* `pm.institutional_claims.update` — UB-04 Details

1. From the Claims list (`/pm/claims`), click a claim row to open the detail page.
2. The four summary cards show Total Charge, Paid, Adjustment, and Patient Responsibility.
3. The **Lines** tab lists each claim line with CPT code, modifiers, units, service date, charge amount, and paid amount.
4. On the **Scrub** tab, click **Run Scrubbing** (requires `pm.claims.update`) to execute client-side validation.
5. The **Notes** tab shows existing claim notes and a form to add new notes (requires `pm.claims.update`).
6. The **Denials** tab shows denial records associated with this claim via `ClaimDenialSummaryPanel`.
7. Use the status menu or Void / Create Replacement buttons in the header based on your permissions.

| Term                     | Meaning in code                                                                |
| ------------------------ | ------------------------------------------------------------------------------ |
| `claim_number`           | Display identifier for the claim                                               |
| `claim_type`             | E.g., `institutional_837i` enables UB-04 and 837I generation                   |
| `denial_codes`           | Array of denial/adjustment codes on the claim                                  |
| `CLAIM_NOTE_TYPE_LABELS` | Labels for note type categories                                                |
| `CLAIM_TYPE_LABELS`      | Display labels for claim types                                                 |
| Voidable statuses        | `draft`, `scrubbed`, `submitted`, `accepted`, `denied`, `appealed`, `adjusted` |
| Replaceable statuses     | `void`, `adjusted`                                                             |

## 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/ClaimListPage.tsx
  * src/cores/pm/hooks/useClaimList.ts
  * src/cores/pm/types/claims.ts
  * src/cores/pm/pages/ClaimDetailPage.tsx
  * src/cores/pm/hooks/useClaimDetail.ts
  * src/cores/pm/utils/claim-scrubbing.ts
</Accordion>