Referral Lifecycle & Statuses | Referral Exchange docs

Every referral in RefX progresses through a set of defined statuses, representing its current position in the referral journey.

Status filters vs status values

RefX exposes two related status concepts:

Status (returned by Get full details for a referral): a detailed status that reflects the current step.
Status filter (used by Retrieves a paginated list of referrals): a stable, high-level category used for querying (draft, pending, confirmed, rejected, cancelled).

Use the status filter values when calling the Retrieves a paginated list of referrals and Retrieves a paginated list of referrals by institution endpoints, and use the detailed status values returned by the Get endpoint to drive finer-grained UI states or actions.

Status filter mapping and meanings

Status filter (Retrieves a paginated list of referrals)	Status value (Get full details for a referral)	Description
`draft`	`draft`	Referral is created but not yet submitted. Can be edited or deleted.
`pending`	`created`	Referral is submitted and queued for processing.
`pending`	`pending-singhealth-formsg`	The patient is required to provide details via a SingHealth FormSG form as they have been identified as new to SingHealth, required for first-time visits. An SMS has been triggered to the patient. Alternatively, the referral sender can fill this up on the patient’s behalf too. This status remains as such until action either by the patient or referral sender has been taken.
`pending`	`pending-singhealth-call-centre`	Waiting for the SingHealth call centre to act on the referral.
`pending`	`referral-confirmed-pending-appt`	Referral confirmed, awaiting appointment scheduling.
`pending`	`pending-email-ack`	Waiting for acknowledgement of the referral.
`pending`	`pending-amend-timeslot`	The previously selected timeslot is no longer available, and hence another timeslot needs to be re-selected.
`confirmed`	`confirmed`	Referral is confirmed.
`confirmed`	`sent`	Information email has been sent; no further action required.
`rejected`	`rejected`	Rejected by validation logic or by the receiving system.
`rejected`	`failed`	Processing failed and the referral will not proceed.
`cancelled`	`pending-cancelled`	Cancellation requested and awaiting completion.
`cancelled`	`cancelled`	Referral cancelled by sender, receiver, or administrator.

Action-required statuses and links

Some detailed statuses require action by the API consumer (for example, your UI should prompt the user to complete a step). To receive action links, call Get Full details for a referral with additionalField=link in the query string. The response includes a links array with the action URLs.

Status value (Get full details for a referral)	Action needed	Link type returned
`draft`	Complete or amend the referral before submission.	`amend`
`pending-amend-timeslot`	Reselect an appointment timeslot.	`select-timeslot`
`pending-singhealth-formsg`	Complete the SingHealth FormSG form.	`fill-singhealth-formsg`

Not all systems handle every state transition. For instance, some integrations automatically confirm referrals upon submission, while others may wait for manual scheduling or validation by the receiver.

When building your integration, plan for status changes to occur asynchronously and always treat the referral status as the source of truth.