List Referrals

Listing referrals is how your system can display all referrals associated with a given institution to show the referrer’s active cases, completed referrals, or pending actions.

You can use this endpoint to power your internal dashboard, check the status of referrals created through the hosted Referral Link, or integrate downstream updates (like appointment confirmations) back into your system.

How it works

1. Call the list endpoint

   Retrieve referrals associated with your institution by specifying your hciCode and, optionally, a role filter such as sender or receiver.

2. Filter by status or patient

   To narrow results, you can include filters such as:

   • status: e.g. pending, confirmed, rejected
   • patientUin: to find all referrals for a specific patient

3. Paginate results

   The API returns pagination metadata (offset, pageSize, hasNext) which you can use to implement “load more” or infinite scrolling patterns.

Implementation notes

• Polling for updates:

  To keep your referral list up to date, we recommend one of the following approaches:

  • Poll the list every few minutes
  • Re-fetch when your user returns to the referral page or window
  • Use a lightweight “sync” query that fetches only referrals updated since your last check

• Display order:

  Sort referrals by updatedAt descending so the most recent actions appear first.

• User experience:

  Consider grouping referrals by status category (e.g. “In progress”, “Completed”, “Cancelled”).

  This makes large referral volumes easier to manage and visually communicates workflow stages.

• Caching:

  You can safely cache referral data client-side for short periods (e.g. 1–5 minutes).

  RefX is designed for eventual consistency; immediate real-time updates are not necessary for most use cases.