Clinical
Referrals
The Referrals module manages patient transfers between clinicians, departments, and external facilities. It provides a structured workflow for referral creation, acceptance, scheduling, completion, and rejection with comprehensive analytics and follow-up tracking.
What is Referral Management?
Referral Management handles the complete patient transfer lifecycle: referral creation (internal to doctors/departments or external to facilities), acceptance workflow (receiving clinician acknowledges), appointment scheduling (date/time for the referred consultation), completion tracking (outcome documentation), rejection handling (with reasoned rejection notes), follow-up monitoring (accepted referrals past their appointment date), and analytics (turnaround time, completion rate, top referrers, monthly volume).
Each referral follows a five-stage status: Pending → Accepted → Completed → Cancelled → Rejected, with full audit logging at every transition. Service catalog linking allows referencing hospital services directly.
Why Does It Exist?
- → Care continuity — Structured referrals ensure patients don't fall through the cracks during transfers
- → Accountability — Every referral is tracked with timestamps, actor identity, and outcome, no lost handoffs
- → Timeliness — Follow-up monitoring catches overdue appointments before they become missed care events
- → Data-driven improvement — Turnaround analytics enables institutional optimization of transfer processes
The Referral Workflow
Referral Initiation
A clinician creates a referral specifying the referring doctor, receiving doctor or department, reason, urgency, and optionally links a service catalog entry. The referral enters 'pending' status and broadcasts a notification to receiving clinicians.
Accept & Schedule
The receiving clinician reviews the referral details and accepts it. They can optionally schedule an appointment date for the consultation. The referral moves to 'accepted' status and is queued for follow-up monitoring.
Completion & Outcome
After the consultation or procedure, the receiving clinician documents the outcome. This free-text outcome record captures the clinical disposition, follow-up instructions, and any referral loop closure details.
Rejection & Resolve
If the receiving clinician cannot accept the referral, they reject it with a reason. The rejection reason is appended to the referral notes with a timestamp. The referral is closed as 'rejected' and the referring clinician is notified.
Every Feature Explained
Referral Creation & Context
Create referrals with full clinical context, reason, urgency, and doctor routing.
Comprehensive referral data prevents information loss during patient handoffs.
Captures patient, referring doctor, receiving doctor/department, reason, urgency (routine/urgent/emergency), referral type (internal/external), external facility name, appointment date, optional notes, optional service catalog linkage. On creation, a patientServiceLink is automatically created.
Accept/Reject Workflow
Structured acceptance and rejection with reasoned outcomes.
Ensures every referral has a clear disposition and prevents indefinite pending states.
Accept moves to 'accepted' status. Reject requires a mandatory reason that gets appended to notes with a timestamp. Both transitions broadcast notifications to permission holders. Rejection is a terminal state.
Appointment Scheduling
Schedule consultation appointments for accepted referrals.
Binds the referral to a concrete time slot for the receiving clinician.
Accepts a datetime-local input. The appointmentDate is stored on the referral record. Accepted referrals with past appointment dates are surfaced in the follow-ups view for monitoring.
Follow-Up Monitoring
Track accepted referrals with past-due appointments requiring follow-up.
Prevents patients from getting lost in the referral pipeline.
The /follow-ups endpoint queries referrals where status=accepted, appointmentDate is not null and in the past. Results are ordered by appointmentDate ascending (most overdue first). Designed for paginated review by nursing or case management staff.
Service Catalog Integration
Link referrals to hospital services and sub-divisions.
Gives receiving teams precise context about the requested service.
Two-tier service linkage: hospitalSubService (category › sub-service) or serviceSubDivision (category › sub-service › division). Service selection is parsed with a prefix convention (sub: / div:). On creation, a patientServiceLink is established for continuity.
Analytics & Intelligence
Comprehensive analytics with turnaround time, completion rates, and volume trends.
Data-driven insights enable continuous process improvement.
Analytics endpoint computes: average turnaround days (completed referrals only), completion rate percentage, top 5 referring doctors, top 5 referred-to departments, 12-month monthly volume series. Avg turnaround uses raw SQL AVG extraction on epoch difference.
Patient Search & Filters
Search referrals by patient name, MRN, reason, referrer across all fields.
Quick retrieval is essential in a busy clinical environment.
Search fields include: reason, referredBy, referredTo, department, externalFacility, patient name and MRN. Filters by status, referral type. Paginated with ServerPagination. Record scopes enforce patient-level access control.
External Facility Support
Support referrals to external hospitals and clinics outside the system.
Not all care destinations are internal, external transfers need the same governance.
External facility name overrides the referred-to doctor when set. Referral type distinguishes internal (within institution) vs external (outside). External referrals track the facility name, reason, and outcome, but skip patientServiceLink creation.
Technical Architecture
| Field | Type | Institutional Role |
|---|---|---|
| referral_id | UUID | Unique referral identifier. |
| patient_id | UUID | Reference to the referred patient. |
| status | Enum | Pending, Accepted, Completed, Cancelled, Rejected. |
| referral_type | Enum | Internal (institution) or External (outside facility). |
| urgency | Enum | Routine, Urgent, Emergency. |
Note: Sensitive fields use AES-256 field-level encryption where applicable.
Governance & Power
referrals:viewreferrals:createreferrals:editreferrals:acceptreferrals:completereferrals:rejectreferrals:schedulereferrals:manageGraceful Deletion
Only pending status referrals can be deleted. Accepted, completed, or rejected referrals are immutable for audit trail integrity. Deletion requires the referrals:manage permission.
Patient Scoped Access
Referrals enforce patient-level record scoping. Users see only referrals for patients they have access to, based on doctor-patient relationships and module-specific scope rules.
Service Linkage Continuity
When a referral is created with a service catalog reference, a patientServiceLink is automatically generated, ensuring the referred service follows the patient across the institution.