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

# Waitlist Management

> Manage the patient waitlist queue with priority scoring and outreach tracking, and view waitlist analytics KPIs.

The Waitlist Management screen (`/pm/waitlist`) provides a tabbed interface for viewing and managing the patient waitlist queue and reviewing analytics KPIs for the current organization.

## Overview

The screen has two tabs: **Queue** and **Analytics**. The Queue tab renders the `WaitlistQueue` component, which queries `pm_waitlist_entries` joined to patient data (`first_name`, `last_name`, `mrn`, `preferred_name`), ordered by `priority_score` descending and `added_at` ascending. The Analytics tab renders the `WaitlistAnalytics` component, which surfaces summary KPIs computed from `pm_waitlist_entries`: total waitlisted, total promoted, total declined, average wait days for promoted entries, and a breakdown of current waitlisted entries by program type. The entire page is gated by `PermissionGate` with `pm.waitlist.view`.

## Who it's for

Requires the `pm.waitlist.view` permission (`PM_PERMISSIONS.WAITLIST_VIEW`). No additional permission is checked in the page component itself for Queue actions; SME should confirm whether sub-actions within `WaitlistQueue` carry their own permission gates.

## Before you start

* The `pm.waitlist.view` permission must be granted for the user's role.
* An organization must be selected; the hooks throw when no org is active.

## Steps

<Steps>
  <Step title="View the waitlist queue">
    The Queue tab is shown by default. It displays waitlist entries sorted by priority score (highest first), with ties broken by earliest `added_at`.
  </Step>

  <Step title="Review analytics">
    Click the Analytics tab (bar chart icon) to view KPI cards: total waitlisted, total promoted, total declined, and average wait days for promoted patients. A breakdown by program type for currently waitlisted entries is also computed.
  </Step>
</Steps>

## Key concepts

<Tooltip tip="A numeric score used to rank waitlist entries; higher scores appear first in the Queue tab. Scoring logic is not determinable from the files reviewed.">Priority score</Tooltip>

<Tooltip tip="A waitlist entry status indicating a patient has been moved off the waitlist into a program.">Promoted</Tooltip>

<AccordionGroup>
  <Accordion title="Analytics KPI definitions (from code)">
    * **Total Waitlisted**: count of entries with `status = 'waitlisted'`
    * **Total Promoted**: count of entries with `status = 'promoted'`
    * **Total Declined**: count of entries with `status = 'declined'`
    * **Average wait days**: mean of (`promoted_at` - `added_at`) in days, for entries with both timestamps; `null` when no promoted entries exist
    * **By Program**: count of currently waitlisted entries grouped by `program_type`
  </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/WaitlistManagementPage.tsx
  * src/cores/pm/hooks/useWaitlistEntries39.ts
  * src/cores/pm/hooks/useWaitlistAnalytics39.ts
</Accordion>