Concepts

Referral Link V2

This page describes V2 of Referral Links, the recommended approach going forward. In V2, Get referral details no longer embeds action link URLs. Instead it returns a list of available actions, and you fetch a fresh link URL on demand from a dedicated endpoint. See Referral Link for the V1 behaviour.

A Referral Link is a one-time URL returned by RefX APIs. They allow users of external systems to authenticate with RefX to perform scoped actions on specific referrals in their browser.

Why V2

Referral Links are short-lived and single-use, so a link that is fetched together with referral details is often stale by the time a user actually clicks it. In V1, Get referral details embedded link URLs directly in the url field and links array, which meant those URLs could expire before use.

V2 separates discovering which actions are available from fetching the link to perform an action:

  • Get referral details returns an actions array describing the actions available on the referral, without any link URLs.
  • A dedicated endpoint returns a fresh link URL for a specific action, fetched in real time at the moment the user takes the action.

This guarantees the URL you open is always freshly issued, avoiding expiry and reuse issues.

Step 1 — Discover available actions

Call Get referral details (GET /referrals/:referralId). The response includes an actions array. Each entry describes one available action:

  • type — the action type (for example amend, select-timeslot, fill-singhealth-formsg, attachment, or view).
  • label — a human-readable label you can display directly to the user.
  • attachment — present only for attachment actions, identifying the attachment (id and uploadedAt).

Use this list to render the actions available to the user. Note that these entries contain no link URL — they only describe what actions exist.

Step 2 — Fetch a fresh link when the user acts

When the user clicks an action, call Get referral action link (POST /referrals/:referralId/action-links/:type) to fetch a fresh link URL, then open it in the browser.

Provide the following in the request body:

  • requesterIdentifier — an identifier for the individual requesting the link, for audit purposes (see the Requester identifier section below).
  • institutionIdType and institutionId — the institution on whose behalf the link is requested.
  • attachmentId — required only when the action type is attachment. Use the id from the corresponding action’s attachment metadata.

The response contains the freshly issued url, along with the type and label (and attachment metadata for attachment links).

Because the link is fetched at the moment the user acts, it is always fresh — do not cache it or fetch it ahead of time.

When a user opens a Referral Link, RefX exchanges that link for a session using the auth token tied to it. The auth token is immediately consumed and cannot be reused, and the user is redirected automatically to the page where they can take their action. The user’s browser continues to allow access to the referral until the session expires.

Expiry, one-time usage, and scope

Referral Links are single-use. The first successful visit consumes the link, and subsequent visits with the same URL will fail.

Referral Links are short-lived and may expire even if they were never used. Treat them as time-bound and reissue as needed. The expiry time of a link is 15 minutes from the time it is created.

If a user clicks on a Referral Link after it has been consumed or expired, they will see an error page indicating that the link is no longer valid.

The sessions generated by Referral Links are scoped to specific referrals and actions. They cannot be used to access other referrals or perform actions outside their intended scope.

The session persists on the user’s browser after the link is consumed, so users can continue in the same browser without needing the link again as long as they are performing the same action on the same referral.

Requester identifier

When fetching a Referral Link, include a requester identifier for audit purposes. It can be any identifier for the individual user requesting the link (for example, an email address or a UUID), as long as it uniquely maps to a user in your system.

APIs that require a requester identifier when retrieving a Referral Link:

  • Get referral action link (POST /referrals/:referralId/action-links/:type)
  • Create link upsert (POST /links/upsert)

Implementation guide

The recommended way to implement Referral Links is to generate them just-in-time when the user is about to take an action, rather than pre-generating and storing them for later use. In V2, the API design enforces this: Get referral details gives you only action metadata, so the only way to obtain a link URL is to fetch it fresh via Get referral action link at the moment it is needed.

The recommended flow is:

  1. When a referral is displayed, call Get referral details and use the actions array to render the actions available to the user.
  2. When the user clicks an action, call Get referral action link for that action’s type and open the returned url in the browser.

For referral upsert, the button that the user clicks to upsert a referral should trigger a call to the Create link upsert API to fetch a fresh link, which is then opened in the browser.