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

# External Referrals

> Manage external collections agency referrals with CSV export and status tracking.

The External Referrals page (`/pm/external-referrals`) provides a table view of accounts referred to external collections agencies, with the ability to create new referrals and export the list as a CSV file.

## Overview

The External Referrals page reads records from `pm_collections_external_referrals`, scoped to the current organization and ordered by referral date descending. The table shows: Patient (truncated UUID), Amount, Agency, Referral Date, and Status. Status values (`Pending`, `Active`, `Settled`, `Recalled`) are rendered as badges with distinct variants. The page does not paginate; all records for the organization are loaded in a single query.

Users with `pm.collections.manage` permission see a **New Referral** button that opens the `CreateReferralDialog`. When referrals are present, all users with view access see an **Export CSV** button that generates a downloadable file with columns: Patient ID, Referral Amount, Agency, Referral Date, Status, Notes.

## Who it's for

Requires permission: `PM_PERMISSIONS.COLLECTIONS_VIEW` (`pm.collections.view`).

Creating new referrals requires `PM_PERMISSIONS.COLLECTIONS_MANAGE` (`pm.collections.manage`).

## Before you start

* Ensure you have the `pm.collections.view` permission.
* The **New Referral** button and creation form are only visible with `pm.collections.manage`.

## Steps

<Steps>
  <Step title="Open External Referrals">
    Navigate to `/pm/external-referrals`. All external referral records for the organization load in the table, sorted by most recent referral date first.
  </Step>

  <Step title="Review referral records">
    Review the table columns: Patient (first 8 chars of patient ID), Amount, Agency name, Referral Date, and Status badge.
  </Step>

  <Step title="Export as CSV">
    When referral records are present, click **Export CSV** to download a file named `external-referrals.csv` containing all currently loaded records. The CSV includes Patient ID, Referral Amount, Agency, Referral Date, Status, and Notes.
  </Step>

  <Step title="Create a new referral">
    Click **New Referral** (requires `pm.collections.manage`) to open the `CreateReferralDialog`. Complete the form to create a new external referral record.
  </Step>
</Steps>

## Key concepts

**Referral statuses:** `Pending` (outline badge), `Active` (default badge), `Settled` (secondary badge), `Recalled` (destructive badge).

**CSV export:** Generated client-side from the currently loaded data using a Blob URL. The file is named `external-referrals.csv`. Notes fields are double-quote escaped.

<AccordionGroup>
  <Accordion title="Empty state">
    When no referral records exist: "External referrals will appear here when created."
  </Accordion>

  <Accordion title="Error state">
    If the data query fails: "Unable to load referrals. Please try again." with a **Retry** button that reloads the page.
  </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/ExternalReferralsPage.tsx
  * src/cores/pm/hooks/useExternalReferrals45.ts
  * src/cores/pm/types/payment-plans-collections.ts
</Accordion>