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

# Managed Care Authorizations

> Track managed care authorization lifecycles, unit utilization, concurrent reviews, and appeals; view full authorization detail with activity timeline.

The Managed Care Authorizations dashboard at `/pm/managed-care-auth` centralizes authorization tracking for managed care plans, showing lifecycle status, unit utilization, and expiration across all payer contracts.

## Overview

The page loads authorizations from `pm_managed_care_authorizations` via `useManagedCareAuthorizations`, joining patient names (`pm_patients`) and payer names (`pm_payers`). Results are sorted by `expiration_date` ascending by default and paginated at 50 per page. A search bar filters the visible list by authorization number, patient name, payer name, or service type without a server round-trip. Authorized and used units are tracked per record alongside effective and expiration dates. Users with `pm.managed_care_auth.create` see two action buttons: **New Authorization** (opens `AuthorizationFormDialog`) and **Retro Auth** (opens `RetroAuthFormDialog` for retroactive authorization submission). Detail records are accessible via `/pm/managed-care-auth/:id`. A utilization summary report is available at `/pm/managed-care-auth/utilization`.

## Who it's for

Requires `pm.managed_care_auth.view` (`PM_PERMISSIONS.MANAGED_CARE_AUTH_VIEW`). Create and edit actions additionally require `pm.managed_care_auth.create` (checked via `PermissionGate` in the page header).

## Before you start

* Your role must include `pm.managed_care_auth.view`.
* At least one payer must be configured in `pm_payers` for the authorization form to function.
* Patients must exist in `pm_patients` before an authorization can be linked to them.

## Steps

<Steps>
  <Step title="Open the Managed Care Authorizations dashboard">
    Navigate to `/pm/managed-care-auth`. The page loads all non-deleted authorizations for your organization, sorted by expiration date.
  </Step>

  <Step title="Filter and search">
    Use the **Auth Dashboard Filters** panel to filter by payer, service type, site, patient, or status. Type in the search box to match by auth number, patient name, payer name, or service type.
  </Step>

  <Step title="Review the authorization table">
    The `AuthDashboardTable` displays each authorization with linked patient, payer, auth number, service type, status, effective/expiration dates, and unit utilization.
  </Step>

  <Step title="Open an authorization detail">
    Click a row to navigate to `/pm/managed-care-auth/:id` for the full authorization record.
  </Step>

  <Step title="Create a new authorization (authorized users)">
    Click **New Authorization** to open the authorization form dialog. Complete the required fields and submit to create the record in `pm_managed_care_authorizations`.
  </Step>

  <Step title="Submit a retro authorization (authorized users)">
    Click **Retro Auth** to open the retroactive authorization form dialog for authorizations obtained after services were rendered.
  </Step>
</Steps>

## Key concepts

**Managed care authorization** — Payer approval required before rendering certain services. Tracked by `auth_number`, `service_type`, `effective_date`, `expiration_date`, `authorized_units`, and `used_units`.

**Unit utilization** — The ratio of `used_units` to `authorized_units`. The dashboard table surfaces both values per authorization.

**Retro authorization** — An authorization submitted after services have already been delivered, entered via the `RetroAuthFormDialog`.

<AccordionGroup>
  <Accordion title="Empty state (no authorizations)">
    When no authorizations are found for the active filters, an empty state is shown: "No Authorizations — No managed care authorizations found. Create one to get started."
  </Accordion>

  <Accordion title="Error state">
    A card with a destructive text message (sanitized) replaces the table if the data query fails.
  </Accordion>
</AccordionGroup>

## Viewing a managed care authorization

The Authorization Detail screen displays a single authorization record with its unit utilization and tabbed sub-resources at route `/pm/managed-care-auth/:id` (permission: `pm.managed_care_auth.view`).

The page loads an authorization via `useAuthorizationDetail47`, displaying the `auth_number`, `auth_type`, status, and an urgency badge derived from days remaining until `expiration_date`. Two summary cards show Authorization Details (patient name, payer, service type, effective/expiration dates, notes) and Unit Utilization (a progress bar comparing `used_units` to `authorized_units`). Three tabs — Reviews, Appeals, and Activity — allow users to record concurrent reviews, manage appeals, and view a combined activity timeline.

1. From the Managed Care Authorizations dashboard (`/pm/managed-care-auth`), click a row to open its detail page.
2. The Authorization Details card shows patient, payer, service type, effective and expiration dates, and notes. The Unit Utilization card shows used vs. authorized units with a visual bar.
3. Select the **Reviews** tab to view existing concurrent reviews and add new review entries.
4. Select the **Appeals** tab to view and submit authorization-level appeals.
5. Select the **Activity** tab for a combined timeline of reviews and appeals.

| Term                              | Meaning in code                                                        |
| --------------------------------- | ---------------------------------------------------------------------- |
| `auth_number`                     | Authorization number assigned by the payer                             |
| `auth_type`                       | Type of authorization (values from payer; SME confirm)                 |
| `used_units` / `authorized_units` | Units consumed vs. units approved                                      |
| `unit_type`                       | The unit of measure for the authorization                              |
| `expiration_date`                 | Date after which the authorization is no longer valid                  |
| `daysRemaining`                   | Computed: `(expiration_date - now) / ms_per_day`; drives urgency badge |

## 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/ManagedCareAuthDashboardPage.tsx
  * src/cores/pm/hooks/useManagedCareAuthorizations.ts
  * src/platform/permissions/constants.ts
  * src/cores/pm/pages/AuthorizationDetailPage47.tsx
  * src/cores/pm/hooks/useAuthorizationDetail47.ts
  * src/cores/pm/hooks/useConcurrentReviews47.ts
  * src/cores/pm/hooks/useAuthAppeals47.ts
</Accordion>