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

# Denials

> Track and manage claim denials and appeals across statuses and denial categories; submit structured appeal packages via six-step wizard.

The Denials page (`/pm/denials`) is the central work queue for tracking and resolving claim denials received from payers.

## Overview

The Denials page displays denial records from the `pm_claim_denials` table, each linked to a claim, a payer, and optional CARC/RARC codes. The list is sorted by payer appeal deadline (ascending, nulls last) and then by denial date (descending), so the most urgent items surface first. Two tabs organize the workspace: **Queue** shows the filterable, actionable denial list; **Analytics** provides aggregate views via the `DenialAnalyticsTab` component. Users with `pm.denials.manage` permission can add denials manually, select multiple rows for bulk assignment, and bulk-update selected denials to `resubmitted` status.

Each denial card shows the status badge, denial category, CARC code (if present), the linked claim number and payer name, denial date, denied amount, and the payer appeal deadline. Deadline dates are highlighted in a destructive color when past due, and in a warning color when within 7 days.

## Who it's for

Requires permission: `PM_PERMISSIONS.DENIALS_VIEW` (`pm.denials.view`).

Bulk actions (assign, resubmit, add denial) additionally require `pm.denials.manage`.

## Before you start

* Ensure you have the `pm.denials.view` permission.
* Denials appear automatically when ERA processing records them, or they can be added manually via the **Add Denial** button (requires `pm.denials.manage`).

## Steps

<Steps>
  <Step title="Open the Denials queue">
    Navigate to `/pm/denials`. The **Queue** tab is active by default, showing all denial records sorted by appeal deadline.
  </Step>

  <Step title="Filter by status or category">
    Use the **All Statuses** dropdown to filter by a single status (`New`, `In Review`, `Appealed`, `Resubmitted`, `Resolved`, `Written Off`). Use the **All Categories** dropdown to filter by denial category (`Medical Necessity`, `Coding`, `Authorization`, `Eligibility`, `Timely Filing`, `Duplicate`, `Other`). Click **Clear** to remove active filters.
  </Step>

  <Step title="Select denials for bulk action">
    Users with `pm.denials.manage` see a checkbox on each card and a **Select all** control. Select one or more denials to reveal the **Assign** and **Resubmit** toolbar buttons.
  </Step>

  <Step title="Bulk assign denials">
    Click **Assign (n)** to open the `BulkAssignDenialsDialog` and assign the selected denials to a staff member.
  </Step>

  <Step title="Bulk resubmit denials">
    Click **Resubmit (n)** to update all selected denials to `resubmitted` status in a single operation.
  </Step>

  <Step title="View denial detail">
    Click anywhere on a denial card (outside the checkbox) to navigate to `/pm/denials/:denialId` for the full detail view.
  </Step>

  <Step title="Add a denial manually">
    Click **Add Denial** (requires `pm.denials.manage`) to open the `CreateDenialDialog` and enter denial details.
  </Step>

  <Step title="View analytics">
    Switch to the **Analytics** tab to see aggregate denial data rendered by `DenialAnalyticsTab`.
  </Step>
</Steps>

## Key concepts

**Denial statuses:** <Tooltip tip="Lifecycle state of a denial record">Status</Tooltip> values are `new`, `in_review`, `appealed`, `resubmitted`, `resolved`, and `written_off`. Deadline color-coding is suppressed for `resolved` and `written_off` denials.

**Denial categories:** `medical_necessity`, `coding`, `authorization`, `eligibility`, `timely_filing`, `duplicate`, `other`.

**CARC / RARC codes:** <Tooltip tip="Claim Adjustment Reason Code — standard payer code explaining why a claim was adjusted or denied">CARC</Tooltip> and <Tooltip tip="Remittance Advice Remark Code — supplemental code providing additional denial context">RARC</Tooltip> codes are stored on the denial record and displayed as monospace badges on each card.

<AccordionGroup>
  <Accordion title="Empty states">
    * No filters active: "Denials from ERA processing will appear here, or add one manually."
    * Filters active: "Try adjusting your filters."
  </Accordion>

  <Accordion title="Error state">
    A load error renders a destructive-styled card with a sanitized message and a **Retry** button that re-runs the query.
  </Accordion>
</AccordionGroup>

## Creating an appeal

The New Appeal page at `/pm/appeals/new` launches a full-page six-step wizard for building and submitting a denial appeal package. Requires `pm.appeals.submit` (`PM_PERMISSIONS.APPEALS_SUBMIT`).

An optional `?denialId=` query parameter pre-fills the wizard from an existing denial record. The wizard uses `DenialAppealWizard` inside a `WizardShell` timeline layout. Step navigation activates once at least one step has been completed. On successful submission the user is redirected to `/pm/denials`; the exit action navigates back in browser history.

**Before you start:** your role must include `pm.appeals.submit`. A denial record in `pm_denials` should exist before opening the wizard; navigate from the Denials list or detail page to pre-populate `?denialId=`. The payer associated with the denial should be configured in `pm_payers`.

<Steps>
  <Step title="Step 1 — Denial Intake">
    Enter or confirm the denial ID, claim ID, payer, denial receipt date, and denial category. If `?denialId=` was supplied, the denial ID field is pre-filled.
  </Step>

  <Step title="Step 2 — Deadline & Strategy">
    Review the calculated appeal deadline (driven by `payerAppealDeadlineDays` and the receipt date) and select the appeal strategy.
  </Step>

  <Step title="Step 3 — Evidence">
    Attach or describe supporting evidence for the appeal. Changes are persisted in wizard state via `onChange` as you work.
  </Step>

  <Step title="Step 4 — Appeal Letter">
    Draft or review the appeal letter. The letter step receives `denialCategory` and `payerId` from the Intake step to support template selection.
  </Step>

  <Step title="Step 5 — Submission Path">
    Select the submission method (e.g., portal, fax, mail) and provide any required submission details.
  </Step>

  <Step title="Step 6 — Review & Submit">
    Review the full appeal package summary. The deadline is shown alongside all entered data. Click **Submit** to finalize; the wizard shows a submitting state while the mutation runs. On success the user is redirected to `/pm/denials`.
  </Step>
</Steps>

**Appeal deadline** — Computed from `payerAppealDeadlineDays` plus the denial receipt date entered in step 1. Displayed in steps 2 and 6.

**`?denialId` query parameter** — When present, pre-populates the Intake step with the referenced denial's ID so the wizard can be launched directly from the Denials list or detail page.

**Timeline layout** — The `WizardShell` renders step progress as a vertical timeline on the side; step titles and icons are shown for all six steps simultaneously, with the current step highlighted.

**Exit behavior** — Clicking the exit control calls `onExit`, which navigates back one step in browser history (`navigate(-1)`). Unsaved wizard data is lost on exit.

## Detail view

The Denial screen displays a single claim denial record and provides status management and appeal creation at route `/pm/denials/:denialId`.

### Overview

The page loads a denial via `useClaimDenialDetail`. The Denial Details card shows denial date, category (from `DENIAL_CATEGORY_LABELS`), denied amount, CARC code with description (from joined `pm_carc_codes`), RARC code with description (from joined `pm_rarc_codes`), and denial reason. The appeal deadline field highlights in warning color if within 7 days and in destructive color if past due. Status-action buttons (In Review, Resubmitted, Resolved, Write Off) are gated by `pm.denials.manage`. The Appeals card lists linked appeal submissions with status badges (from `APPEAL_STATUS_LABELS`), appeal level, and created/submitted dates. Users with `pm.appeals.submit` can launch the Appeal Wizard (navigates to `/pm/appeals/new?denialId=...`) or open a Quick Draft via `CreateAppealSheet`.

### Who it's for

Requires permission `PM_PERMISSIONS.DENIALS_VIEW` (enforced via `RequirePermission` in the route definition). Managing denials requires `pm.denials.manage`. Submitting appeals requires `pm.appeals.submit`.

### Before you start

* You need `pm.denials.view` to access this page.
* Navigate here from the Denials list (`/pm/denials`).

### Steps

<Steps>
  <Step title="Open a denial record">
    From the Denials list (`/pm/denials`), click a row to open the denial detail page.
  </Step>

  <Step title="Review denial details">
    Check the category, denied amount, CARC/RARC codes (with descriptions), denial reason, and appeal deadline.
  </Step>

  <Step title="Update status (pm.denials.manage)">
    Use the status buttons to move the denial to In Review, Resubmitted, Resolved, or Written Off as appropriate.
  </Step>

  <Step title="Create an appeal (pm.appeals.submit)">
    Click **Appeal Wizard** to navigate to the structured wizard, or **Quick Draft** to open the inline sheet.
  </Step>

  <Step title="Submit a draft appeal (pm.appeals.submit)">
    In the Appeals section, click **Submit** on any draft appeal to submit it.
  </Step>
</Steps>

### Key concepts

| Term                    | Meaning in code                                                        |
| ----------------------- | ---------------------------------------------------------------------- |
| `carc_code`             | Claim Adjustment Reason Code; description joined from `pm_carc_codes`  |
| `rarc_code`             | Remittance Advice Remark Code; description joined from `pm_rarc_codes` |
| `denial_category`       | Category label from `DENIAL_CATEGORY_LABELS` (SME confirm categories)  |
| `payer_appeal_deadline` | Deadline date; turns warning/destructive based on proximity            |
| `DenialStatus`          | `new`, `in_review`, `resubmitted`, `resolved`, `written_off`           |
| `appeal_level`          | Numeric level of the appeal submission                                 |

## 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/DenialsListPage.tsx
  * src/cores/pm/hooks/useClaimDenialList.ts
  * src/cores/pm/hooks/useClaimDenialMutation.ts
  * src/cores/pm/types/denials.ts
  * src/cores/pm/pages/DenialAppealWizardPage.tsx
  * src/cores/pm/components/wizards/denial-appeal/DenialAppealWizard.tsx
  * src/platform/permissions/constants.ts
  * src/cores/pm/pages/DenialDetailPage.tsx
  * src/cores/pm/hooks/useClaimDenialDetail.ts
  * src/cores/pm/hooks/useAppealSubmissionList.ts
  * src/cores/pm/hooks/useAppealSubmissionMutation.ts
</Accordion>