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

# Recovery Housing Referrals

> Browse, filter, view, edit, and update discharge referrals for residents by agency name, contact, referral type, and status.

The Referrals screen is at `/rh/referrals` and renders the `ReferralsPage` component. It displays all discharge referrals for the current organization via the `useReferrals` hook, with client-side filtering by search term, referral type, and status.

## Overview

The page loads all referrals via `useReferrals()` and applies three client-side filters before passing results to `ReferralsTable`:

* **Search** — matches `agency_name` or `contact_name` (case-insensitive, partial match).
* **Type filter** — selects by `referral_type`: `housing`, `employment`, `healthcare`, `social_services`, or `other`.
* **Status filter** — selects by `status`: `sent`, `accepted`, `completed`, or `declined`.

Clicking a row in the table navigates to `/rh/referrals/:id`.

## Who it's for

The outer `RHViewGuard` requires `RH_PERMISSIONS.DASHBOARD_VIEW` (`rh.dashboard.view`). The `/rh/referrals` route carries no additional permission gate beyond the guard.

## Before you start

* Hold the `rh.dashboard.view` permission to access any RH route.

## Steps

<Steps>
  <Step title="Navigate to Referrals">
    Go to `/rh/referrals`. The `ReferralsTable` loads all referrals for the current organization.
  </Step>

  <Step title="Filter the list (optional)">
    Use the search box to filter by agency or contact name. Use the Type or Status dropdowns to narrow by referral type or status.
  </Step>

  <Step title="Open a referral record">
    Click a row. The browser navigates to `/rh/referrals/:id` to show the Referral Details screen.
  </Step>
</Steps>

## Key concepts

| Term            | Meaning                                                                            |
| --------------- | ---------------------------------------------------------------------------------- |
| `agency_name`   | Name of the organization receiving the referral.                                   |
| `referral_type` | Category: `housing`, `employment`, `healthcare`, `social_services`, or `other`.    |
| `status`        | Current referral lifecycle status: `sent`, `accepted`, `completed`, or `declined`. |
| `contact_name`  | Contact person at the receiving agency.                                            |

## Viewing a referral

The Referral Details screen is at `/rh/referrals/:id` and renders the `ReferralDetailPage` component. It displays a single referral record from the `rh_referrals` table (accessed via the `useReferrals` hook) and allows inline status updates and editing via `ReferralDialog`.

The page resolves the referral by matching the `:id` path parameter against the results of `useReferrals()`. The header shows the `agency_name`, `referral_type`, and current status badges. A status dropdown (`sent`, `accepted`, `completed`, `declined`) calls `useReferralMutation.update` on change, with a toast notification on success or failure. The Edit button opens the `ReferralDialog` pre-populated with all editable fields.

Two cards are displayed:

* **Referral Details** — referral type, date, status (inline dropdown), and notes.
* **Contact Information** — agency name, contact person, phone (clickable `tel:` link), and email (clickable `mailto:` link).

The outer `RHViewGuard` requires `rh.dashboard.view`; no additional gate exists on this route. A referral record with the target ID must exist and belong to the current organization.

<Steps>
  <Step title="Navigate to the Referrals list">
    Go to `/rh/referrals`. All referrals for the current organization are listed in the `ReferralsTable`.
  </Step>

  <Step title="Open a referral record">
    Click a row in the Referrals table. The browser navigates to `/rh/referrals/:id`.
  </Step>

  <Step title="Review referral details">
    The Referral Details card shows type, date, current status, and any notes.
  </Step>

  <Step title="Update referral status">
    Use the status dropdown in the Referral Details card to change the status. The update is saved immediately via `useReferralMutation.update` and a toast confirms success.
  </Step>

  <Step title="Contact the agency">
    The Contact Information card provides clickable phone and email links if `contact_phone` and `contact_email` are populated.
  </Step>

  <Step title="Edit the referral (optional)">
    Click "Edit" to open the `ReferralDialog` and modify any field, then submit to save.
  </Step>

  <Step title="Return to the list">
    Click the back arrow button to navigate back to `/rh/referrals`.
  </Step>
</Steps>

### Key concepts

| Term                | Meaning                                                                                         |
| ------------------- | ----------------------------------------------------------------------------------------------- |
| `agency_name`       | Name of the organization receiving the referral.                                                |
| `referral_type`     | Category of the referral: `housing`, `employment`, `healthcare`, `social_services`, or `other`. |
| `status`            | Current referral status: `sent`, `accepted`, `completed`, or `declined`.                        |
| `contact_name`      | Name of the specific contact person at the agency.                                              |
| `discharge_plan_id` | Foreign key linking this referral to a discharge plan (may be empty).                           |
| `episode_id`        | Foreign key linking the referral to a resident episode.                                         |

## Related

<Columns cols={2}>
  <Card title="Recovery Housing" icon="house" href="/rh/references">
    Recovery Housing references and overview.
  </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/rh.tsx
  * src/cores/rh/pages/discharge/ReferralsPage.tsx
  * src/cores/rh/pages/discharge/ReferralDetailPage.tsx
  * src/cores/rh/hooks/discharge/index.ts
</Accordion>