> This page is for version 0.0.77.
> For other versions, use one of these documentation indexes:
> - 0.0.79 (default): https://docs.refer.health.gov.sg/0-0-79/llms.txt
> - 0.0.78: https://docs.refer.health.gov.sg/0-0-78/llms.txt
> - 0.0.77: https://docs.refer.health.gov.sg/0-0-77/llms.txt
> - 0.0.76: https://docs.refer.health.gov.sg/0-0-76/llms.txt
> - 0.0.75: https://docs.refer.health.gov.sg/0-0-75/llms.txt
> - 0.0.74: https://docs.refer.health.gov.sg/0-0-74/llms.txt
> - 0.0.73: https://docs.refer.health.gov.sg/0-0-73/llms.txt
> - 0.0.72: https://docs.refer.health.gov.sg/0-0-72/llms.txt
> - 0.0.71: https://docs.refer.health.gov.sg/0-0-71/llms.txt
> - 0.0.70: https://docs.refer.health.gov.sg/0-0-70/llms.txt
> - 0.0.69: https://docs.refer.health.gov.sg/0-0-69/llms.txt
> - 0.0.68: https://docs.refer.health.gov.sg/0-0-68/llms.txt
> - 0.0.67: https://docs.refer.health.gov.sg/0-0-67/llms.txt
> - 0.0.66: https://docs.refer.health.gov.sg/0-0-66/llms.txt
> - 0.0.65: https://docs.refer.health.gov.sg/0-0-65/llms.txt
> - 0.0.64: https://docs.refer.health.gov.sg/0-0-64/llms.txt
> - 0.0.63: https://docs.refer.health.gov.sg/0-0-63/llms.txt
> - 0.0.62: https://docs.refer.health.gov.sg/0-0-62/llms.txt
> - 0.0.61: https://docs.refer.health.gov.sg/0-0-61/llms.txt
> - 0.0.60: https://docs.refer.health.gov.sg/0-0-60/llms.txt
> - 0.0.59: https://docs.refer.health.gov.sg/0-0-59/llms.txt
> - 0.0.58: https://docs.refer.health.gov.sg/0-0-58/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.refer.health.gov.sg/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.refer.health.gov.sg/_mcp/server.

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](./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.

## Fetching an action link

### 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.

## What happens when a link is opened

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.