> This page is for version 0.0.69.
> 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.

# Changelog

## October 15, 2026

## v0.0.79

The changes documented here consolidate the main changes made from v0.0.72 to v0.0.79.

### Breaking Changes

* Removed support for legacy static API keys (`Authorization: ApiKey <token>`). All requests must be authenticated with a JWT, as described on the `Authentication` page.
* Removed the deprecated `status` field from referral responses in the API reference and SDK. It is still returned for backwards compatibility but may be removed in the future, so use `coreStatus` instead.
* The following referral response fields are now optional, and are omitted rather than returned as an empty string when no value was provided:
  * `patient.uin`, `patient.phoneNumber` and `patient.dob`
  * `referringDoctor.email` and `referringDoctor.contactNumber`
* `POST /api/v1/referrals/:referralId/back-to-draft` now only accepts referrals that are still pending email acknowledgement, so rejected referrals can no longer be sent back to draft.

### Additions

* Added new `POST /api/v1/referrals/:referralId/action-links/:type` endpoint, which returns a freshly issued referral link for a single action type (`amend`, `select-timeslot`, `fill-singhealth-formsg`, `attachment` or `view`). It requires `requesterIdentifier`, `institutionIdType` and `institutionId` in the request body, plus `attachmentId` when `type` is `attachment`.
* Added new `actions` field to the `GET /api/v1/referrals/:referralId` response, listing the actions available on the referral. Each action has a `type` and `label`, and `attachment` actions also include `attachment` (`id` and `uploadedAt`).
* Added new fields to referral responses (`GET /api/v1/institutions/:institutionIdType/:institutionId/referrals`, `GET /api/v1/referrals/:referralId`, `DELETE /api/v1/referrals/:referralId`, `POST /api/v1/referrals/:referralId/cancel`, `POST /api/v1/referrals/:referralId/back-to-draft`):
  * `canBackToDraft` — whether the referral can be sent back to draft to be amended and resubmitted.
  * `offeringClinician` — the clinician (`name`) at the receiving institution for the referral's latest appointment, when available.
  * `patient.race` and `patient.email`.
* Added new `buildingName`, `city`, `geographicalArea` and `country` fields to the patient address (`address` in the `POST /api/v1/links/upsert` request body, and `patient.address` in referral responses).
* Added new values to the timeline event `type` field (`timelineEvents[].type`) returned by `GET /api/v1/referrals/:referralId`:
  * `referral.sender-hci-changed` — the referral's sender HCI code was changed, e.g. when clinics merge under a new HCI code.
  * `referral.offering-fallback` — the referral was automatically rerouted to a fallback offering because its original offering was deactivated.
  * `appt.booking-fallback` — the selected appointment timeslot could not be confirmed with the receiving system, so the institution will schedule the appointment instead.
  * `attachment.uploaded` — the receiving system uploaded an attachment to the referral. The attachment is listed as an `attachment` action in the referral's `actions` array.

### Documentation Changes

* Added a new `Referral Link V2` page in the `Concepts` section, explaining how to list a referral's available `actions` and fetch a fresh link only when the user acts.
* Added `Get action link by type` to the `API Overview` page, and fixed its broken API reference links.
* Updated the file upload limit on the `Request and Response Limits` page from 50 MB to 5 MB.
* Documented `400`, `403`, `404` and `429` error responses in the API reference.
* Clarified that `clinicalInfo` in the `POST /api/v1/links/upsert` request body is optional but strongly recommended, as it pre-fills the referral form.

### Recommendations

* Use the `actions` field with `POST /api/v1/referrals/:referralId/action-links/:type` instead of the `url` and `links` fields, so that every link you open is freshly issued. See the `Referral Link V2` page for details.
* Use the `canBackToDraft` field in referral responses to determine whether to show an amend option in the UI.
* If you have any questions or need support with these changes, please reach out to the RefX team at [refx-support@health.gov.sg](mailto:refx-support@health.gov.sg).

## June 4, 2026

## v0.0.71

### Additions

* Added a new `referral.singhealth-patient-create-reminder-sent` value to the timeline event `type` field (`timelineEvents[].type`) returned by `GET /api/v1/referrals/:referralId`.

## May 28, 2026

## v0.0.70

### Additions

* Added new `submittedAt` field to referral responses (`GET /api/v1/institutions/:institutionIdType/:institutionId/referrals`, `GET /api/v1/referrals/:referralId`, `DELETE /api/v1/referrals/:referralId`, `POST /api/v1/referrals/:referralId/cancel`, `POST /api/v1/referrals/:referralId/back-to-draft`).

### Recommendations

* Use the new `submittedAt` field instead of `createdAt` when displaying or sorting by the submission time of a referral, since `createdAt` reflects when the draft was first created rather than when it was submitted.

## May 20, 2026

## v0.0.69

### Documentation Changes

* Removed unimplemented `patient.isHsgEnrolled` field from referral responses (`GET /api/v1/institutions/:institutionIdType/:institutionId/referrals`, `GET /api/v1/referrals/:referralId`, `DELETE /api/v1/referrals/:referralId`, `POST /api/v1/referrals/:referralId/cancel`, `POST /api/v1/referrals/:referralId/back-to-draft`).
* Updated description of the `offering.description` field in referral responses (`GET /api/v1/institutions/:institutionIdType/:institutionId/referrals`, `GET /api/v1/referrals/:referralId`, `DELETE /api/v1/referrals/:referralId`, `POST /api/v1/referrals/:referralId/cancel`, `POST /api/v1/referrals/:referralId/back-to-draft`).

## May 13, 2026

## v0.0.68

### Additions

* Added new `Manual` enum value to the `senderSystem` field in referral responses (`GET /api/v1/institutions/:institutionIdType/:institutionId/referrals`, `GET /api/v1/referrals/:referralId`, `DELETE /api/v1/referrals/:referralId`, `POST /api/v1/referrals/:referralId/cancel`, `POST /api/v1/referrals/:referralId/back-to-draft`).
* Added new `Manual` enum value to the `timelineEvents[].system` field in `GET /api/v1/referrals/:referralId` response.
* Added new `gpfirst` and `ae` enum values to the `offering.category` field in referral responses (`GET /api/v1/institutions/:institutionIdType/:institutionId/referrals`, `GET /api/v1/referrals/:referralId`, `DELETE /api/v1/referrals/:referralId`, `POST /api/v1/referrals/:referralId/cancel`, `POST /api/v1/referrals/:referralId/back-to-draft`).

## April 29, 2026

## v0.0.67

### Additions

* Added new `nehrForm` enum value to the `additionalField` query parameter on `GET /api/v1/referrals/:referralId`. When requested, the response includes:
  * `nehrForm` — the referral form rendered as a self-contained HTML document, suitable for forwarding to NEHR.
  * `nehrFormType` — a human-readable description of the NEHR form type(s), with multiple templates joined by `|`.

### Documentation Changes

* Added a new `NEHR Integration` page in the `Concepts` section, explaining how to map RefX fields (`offering.nehrCode`, `offering.specialty`, `nehrForm`, `nehrFormType`) into a NEHR `putComposition` request.

### Recommendations

* For NEHR integrations, call `GET /api/v1/referrals/:referralId?additionalField=nehrForm` immediately before submitting to NEHR, and forward the returned `nehrForm` HTML as-is — do not modify, reflow, or strip styles, or it may not render correctly in NEHR.
* Read the new `NEHR Integration` concept page for the full mapping between RefX fields and NEHR `putComposition` payload locations.
* If you have any questions or need support with these changes, please reach out to the RefX team at [refx-support@health.gov.sg](mailto:refx-support@health.gov.sg).

## April 24, 2026

## v0.0.66

The changes documented here consolidate the main changes made from v0.0.58 to v0.0.66.

### Breaking Changes

* `GET /api/v1/referrals/:referralId` now requires `requesterIdentifier`, `institutionIdType`, and `institutionId` as query parameters.
* `DELETE /api/v1/referrals/:referralId` now requires `institutionIdType` and `institutionId` as query parameters.
* `POST /api/v1/referrals/:referralId/back-to-draft` now requires `institutionIdType` and `institutionId` in the request body.
* `POST /api/v1/referrals/:referralId/cancel` now requires `institutionIdType`, `institutionId`, and `cancelNote` in the request body.
* `POST /api/v1/referrals/:referralId/notes` now requires `institutionIdType` and `institutionId` in the request body.
* `POST /api/v1/links/upsert` now requires `requesterIdentifier` and `institutionIdType` in the request body.
* `status` field in `appointments` array in `GET /api/v1/referrals/:referralId` response has some values renamed:
  * `booked` -> `scheduled`
  * `noShow` -> `no-show`
* Added new `type` values to `timelineEvents` array in `GET /api/v1/referrals/:referralId` response:
  * `referral.pending-acceptance`
  * `appt.actualized`
  * `appt.no-show`
  * `appt.cancelled`

### Additions

* Added `nationality` field to `POST /api/v1/links/upsert` request body.
* Added `location` field to `appointments` array in `GET /api/v1/referrals/:referralId` response.
* Added new `isCancellable` and `coreStatus` fields to `GET /api/v1/referrals/:referralId` response.
* Added new `sender-action-required` enum value to the `GET /api/v1/institutions/:institutionIdType/:institutionId/referrals` `status` query parameter.
* Added new `offering.specialty` and `offering.nehrCode` fields to `GET /api/v1/referrals/:referralId` response.
* Added new `label` field to `links` array in `GET /api/v1/referrals/:referralId` response.

### Deprecations

* The `status` field in the `GET /api/v1/referrals/:referralId` response is now deprecated in favor of the new `coreStatus` field and may be removed in the future.

### Documentation Changes

* Removed unnecesssary endpoints from API documentation.
* Added pattern for `dob` field in `POST /api/v1/links/upsert` request body to indicate ISO 8601 format.
* Updated `Referral Lifecycle & Statuses` page in the `Concepts` section:
  * New `coreStatus` field.
  * How to get additional details for some referral statuses.
  * Recommendations for displaying appointment statuses.
  * Recommendations for implementing referral action links for when users need to take action on a referral.
* Updated `Referral Link` page in the `Concepts` section:
  * Clarify link expiry, validity, and scope.
  * Recommendations for redirecting users using referral links.
* Added new `Implementation Reference` page in the `Getting Started` section.

### Recommendations

* Include nationality information when calling `POST /api/v1/links/upsert` using the provided enum values to prefill the referral form and reduce manual entry for the user.
* Use the `isCancellable` field in the `GET /api/v1/referrals/:referralId` response to determine whether to show a cancel option in the UI.
* Use the `coreStatus` field in the `GET /api/v1/referrals/:referralId` response instead of the `status` field to determine the status to display to the user. The `status` field contains more granular information that may not be relevant for display purposes.
* Do not programmatically handle the `type` field in the `timelineEvents` array in the `GET /api/v1/referrals/:referralId` response as there may be new event types added in the future. Instead, use the `description` field to display meaningful information to users without needing to update your system for new event types.
* Use the new `sender-action-required` enum value for the `status` query parameter in the `GET /api/v1/institutions/:institutionIdType/:institutionId/referrals` endpoint to highlight referrals that require action from the user.
* Use the new `label` field in the `links` array in the `GET /api/v1/referrals/:referralId` response as the text on buttons in the UI that redirect users to RefX.
* Read the new and updated documentation pages for recommendations on how to successfully integrate with RefX.
* If you have any questions or need support with these changes, please reach out to the RefX team at [refx-support@health.gov.sg](mailto:refx-support@health.gov.sg).