Changelog

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.