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

# Practice Management Referrals

> Track inbound and outbound patient referrals with status, urgency, level-of-care filtering, and packet checklists.

The Referrals screen (`/pm/referrals`) displays all inbound and outbound patient referrals for the current organization and provides tools to create, edit, update status, and soft-delete referrals.

## Overview

The screen lists referrals ordered by `referral_date` descending. Each card shows the direction (inbound arrow / outbound arrow), patient name, referral number, status badge, urgency badge (Routine, Urgent, Emergent), and optionally a court deadline indicator and SLA badge. Below the primary row, the source name or source type and the requested level(s) of care are shown. Clicking a card expands it inline to reveal presenting issue, clinical summary, program notes, and internal notes (when present), plus a next-steps component. Users can filter by direction (Inbound / Outbound), status, and level of care, and search by name, referral number, or source.

## Who it's for

Requires the `pm.referrals.view` permission. Creating and editing referrals additionally requires `pm.referrals.create` and `pm.referrals.update` respectively.

## Before you start

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

## Steps

<Steps>
  <Step title="Filter the list">
    Use the search box to find referrals by patient first name, last name, referral number, or source name. Use the Direction dropdown (All Directions, Inbound, Outbound), Status dropdown, or Level of Care dropdown to narrow results. All filters are applied server-side except the client-side search fallback for small datasets.
  </Step>

  <Step title="Expand a referral">
    Click any referral card to toggle its expanded detail section, which shows presenting issue, clinical summary, program notes, internal notes, and a next-steps component.
  </Step>

  <Step title="Update referral status">
    Use the `ReferralStatusMenu` (accessible from the action buttons on each card without expanding) to change the current status of a referral.
  </Step>

  <Step title="Open a packet checklist (outbound referrals)">
    For outbound referrals, click the checklist icon button to open the "Referral Packet" side sheet containing the `ReferralPacketChecklist` component.
  </Step>

  <Step title="Edit a referral">
    Users with `pm.referrals.update` can click the pencil icon on any card to open the `ReferralFormDialog` in edit mode.
  </Step>

  <Step title="Remove a referral">
    Users with `pm.referrals.update` can click the trash icon to trigger a confirmation dialog. Confirming performs a soft-delete (sets `deleted_at`); the referral is hidden from the list immediately.
  </Step>

  <Step title="Create a new referral">
    Users with `pm.referrals.create` can click "New Referral" in the header to open `ReferralFormDialog` in create mode. The "Upload Fax" button opens `FaxReferralUploadDialog` for fax-originated referrals.
  </Step>
</Steps>

## Key concepts

<Tooltip tip="The flow direction of the referral relative to the organization.">Direction</Tooltip> — `inbound` means the patient is being referred to this organization; `outbound` means the organization is referring the patient elsewhere.

<Tooltip tip="Levels of care available for filtering: Residential/BHRF, Inpatient Psychiatric, IOP, PHP, Outpatient, Crisis Stabilization, Housing Only.">Level of Care</Tooltip>

<AccordionGroup>
  <Accordion title="Empty state">
    When no referrals exist, the empty state message reads "Create your first referral to start tracking patient intake." When filters are active and no results match, the message reads "No referrals match the current filters."
  </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/ReferralsListPage.tsx
  * src/cores/pm/hooks/useReferralList.ts
  * src/cores/pm/types/referrals.ts
</Accordion>