Create and Edit Referrals | Referral Exchange docs

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

Generate a referral link

Your system calls the “Create or Upsert Link” endpoint and provides minimal context such as:
- the referring institution, sender details, and
- optionally, basic patient information if it is already known. Try to provide as much information as possible as this will pre-fill the form and significantly improve the referral creation experience for the user.
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.
User completes and submits

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

Editing a Referral

Retrieve the editable referral link

Call the “Get referral details” endpoint and include the query parameter:
```
1 {
2   "additionalField": "link"
3 }
```
If the referral is in an editable state, the response will include an array of links that point to the different hosted referral edit pages.
Launch the edit session

Open the link in your user’s browser window or embedded frame.
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.
Link validity: Referral links are time-bound and single-use. Avoid storing, caching, or preloading them.
Recommended UX pattern: After generating a link, redirect the user immediately and display a loading or “Redirecting to Referral Form…” message during handoff.

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