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.

Core referral statuses and meanings

There are two fields in the referral object that indicate the referral’s current status, coreStatus and status. You should rely on coreStatus to determine what to display to the user and whether any action is required. The status field is an internal implementation detail of RefX that is subject to more frequent changes and will be removed from the external API in the future.

Core status	Description
`draft`	Referral is created but not yet submitted. Can be edited or deleted.
`pending`	Referral is submitted and is pending an appointment.
`confirmed`	Referral is confirmed with an appointment.
`rejected`	Referral has been rejected by validation logic or by the receiving system.
`cancelled`	Referral has been cancelled by sender, receiver, or administrator.
`sender-action-required`	Referral requires action from the sender before it can proceed.

Status details

Some referral statuses have additional details that provide more context to the end user, such as the reason for rejection.

Core status	Additional details
`rejected`	Rejection reason can be found in the `description` field of the latest `referral.rejected` or `appt.rejected` timeline event.
`cancelled`	Cancellation reason can be found in the `description` field of the latest `referral.cancelled` timeline event.

Referral status vs appointment status

Referrals that have a core status of confirmed may have one or more associated appointments with their own statuses, available through the appointments array. It is possible for an appointment to be cancelled while the referral remains confirmed, for example while pending rescheduling. You should be able to display multiple appointments per referral.

The timeslotStartAt and appointmentLocation fields in the referral will refer to the most recently scheduled appointment. Look into the appointments array for details of all appointments associated with the referral, including their individual statuses.

Action-required statuses and links

Some statuses require action by the API consumer (for example, your UI should prompt the user to complete a step).

Core status	Link type returned	Action needed
`draft`	`amend`	Complete or amend the referral before submission.
`sender-action-required`	`select-timeslot`	Reselect an appointment timeslot.
`sender-action-required`	`fill-singhealth-formsg`	Complete the SingHealth FormSG form.

The recommended way to implement referral action links (apart from the draft status, which can be handled separately) is to highlight referrals with the sender-action-required status to the user. When the user clicks on the referral, call Get referral details with additionalField=link in the query string. The response will include a links array.

Each link object should correspond to a button in the UI, with the label field suitable to be used directly as the button text to describe the action to the user. When the user clicks on the button, instead of navigating directly to the URL provided in the url field, you should call Get referral details again to generate a fresh link, and then navigate the user to the new URL. This is because the links have a short validity period and may expire if the user takes too long to click on the button after the initial referral details call. Learn more about referral links here.

With this implementation, even if there are additional link types added in the future, your UI will be able to handle them without any code changes.