Cancel & Withdraw Referrals

Referrals can be cancelled when the referring doctor or institution needs to withdraw a referral for instance, if the patient no longer wishes to proceed, the wrong destination was selected, or duplicate referrals were made.

Cancelling a referral ensures that downstream systems (e.g. HAS or Epic) receive a proper cancellation event and can close the loop cleanly, avoiding administrative errors or unnecessary appointments.

Depending on the downstream system, you may or may not be able to invoke a cancellation. In all cases, you will only be able to cancel a pending referral.

How it works

1. Identify the referral to cancel

   Retrieve the referral details from your list and confirm its current status is cancellable (e.g. pending, not yet confirmed).

2. Submit the cancellation request

   Call the cancel endpoint and include optional fields such as:

   • cancelledByName or cancelledByUin (who performed the action)
   • cancelNote (reason for cancellation)

3. RefX updates the record

   The referral will transition to the cancelled status, and a cancellation event will be recorded in the timeline.

Implementation notes

• User permissions:

  Only the originating (sending) institution can cancel a referral.

  Attempts by receiving systems will be rejected.

• UX considerations:

  Always show a confirmation dialog before proceeding with cancellation, since this action cannot be undone.

  Include a text box to capture the cancellation reason, and display a success message once completed.

• Status propagation:

  Downstream systems are automatically notified. You do not need to call them directly.

• Audit trail:

  The cancellation is recorded as a timeline event (referral.cancelled) with metadata about who initiated it and when.

  You can display this in your system’s activity log or “Referral History” section.