Create and Edit Referrals

Referrals in RefX are created using Referral Link.

Referral Link is a hosted referral form that encapsulates the complex logic of referral creation, including patient details, eligibility checks, offering selection, and downstream routing to systems like HAS, Epic, PartnersBuddy and many others.

By using Referral Link, your system doesn’t need to build or maintain these forms directly. Instead, you simply generate a secure one-time link for the referrer to complete.

Creating a Referral

1. Generate a referral link

   Your system calls the “Create or Upsert Link” endpoint and provides minimal context such as:

   • the referring institution and sender details, and
   • optionally, basic patient information if it is already known. This allows for pre-fills.

2. Launch the hosted form

   The API returns a url which should be opened in a browser window or webview.

   This link takes the user into the hosted referral page, prefilled with any supplied details.

3. User completes and submits

   Once the user submits, RefX validates and routes the referral to the correct downstream service automatically.

Editing a Referral

1. Retrieve the editable referral link

   Call the “Full details for a referral” endpoint and include the query parameter:

   1
   {
   2
   	"additionalField": "link"
   3
   }

   The response includes a url that points to the hosted referral edit page.

2. Launch the edit session

   Open the link in your user’s browser window or embedded frame.

3. User makes updates and resubmits

   Once edited, RefX automatically updates the referral record and notifies the downstream system as needed.

Implementation notes

• User flow:

  Open the url directly in a browser tab or iframe.

  If embedding, ensure it has network access to RefX’s production domain.

• Refresh behaviour:

  Since submission happens within the hosted form, your system won’t get a callback immediately.

  We recommend polling or refetching the referral list when:

  • your window regains focus, or
  • at fixed intervals (e.g. every 30–60 seconds).

  This ensures your referral list reflects the latest state, such as when a user completes or cancels a referral.

• Security:

  Referral links are time-bound and single-use. Avoid storing or caching them permanently.

• Recommended UX pattern:

  After generating a link, redirect the user immediately and display a loading or “Redirecting to Referral Form…” message during handoff.

• Audit behaviour:

  Each edit session creates a new timeline event (referral.amended), ensuring traceability across versions.