Building an e‑Referral Worklist: FHIR DSTU2 vs STU3 Endpoints in NHS e‑RS API

Managing patient referrals efficiently is central to delivering timely care within the NHS. With the introduction of the NHS e‑Referral Service (e‑RS) FHIR APIs, healthcare organisations now have the opportunity to streamline the way referrals are accessed, processed, and acted upon through programmatic integrations. For developers and IT teams, one of the most critical capabilities is building a robust referral worklist that can display, filter, and manage incoming referrals directly within their systems. Yet, as the NHS evolves its FHIR standards from DSTU2 to STU3, questions around endpoint selection, payload differences, and compatibility challenges become increasingly relevant.

This article explores how to build an effective e‑Referral worklist using the NHS e‑RS API, with a particular focus on comparing the DSTU2 and STU3 endpoints, their technical structures, and how each standard can be applied in real-world integration projects.

Understanding the Role of a Worklist in e‑RS Integration

A worklist functions as the operational hub for clinicians, administrative teams, and referral coordinators. It provides a consolidated view of all patient referrals requiring action, eliminating the inefficiencies of manual tracking or reliance on multiple systems.

Within the NHS e‑RS ecosystem, the worklist is not just a display of pending referrals; it includes key metadata such as referral IDs, patient demographics, referral sources, clinical information, and the current status of each referral. Having direct API access to this data means healthcare providers can embed referral management into their existing Electronic Patient Record (EPR) systems, clinical dashboards, or custom applications.

The value lies in reducing administrative burden, accelerating referral triage, and ensuring that patients are matched with the right service in a timely manner.

Why FHIR Standards Matter in Referral Management

Fast Healthcare Interoperability Resources (FHIR) provides a consistent framework for exchanging healthcare data in a structured, RESTful manner. By adopting FHIR, the NHS has ensured that e‑RS integration can be approached with modern web development practices, reducing the complexity of legacy HL7‑based systems.

DSTU2 (Draft Standard for Trial Use 2) was the original foundation for the NHS e‑RS FHIR API. While it remains in use, STU3 (Standard for Trial Use 3) introduces refinements and new capabilities that address some of DSTU2’s limitations. For developers, understanding the nuances between these versions is essential when building a worklist that is future‑proof yet compatible with the current production environment.

Core Functional Differences Between DSTU2 and STU3 Endpoints

While both DSTU2 and STU3 provide access to referral data, their implementation details differ in key ways. DSTU2 endpoints typically use the ReferralRequest resource as the backbone of referral data. STU3, meanwhile, expands the resource model to improve clarity and add fields that support richer clinical and administrative context.

DSTU2 often requires developers to handle additional extensions to retrieve data such as attached documents or provider identifiers. In contrast, STU3 integrates many of these fields more natively within the core schema, reducing the reliance on custom parsing logic.

Another key difference is how each version manages pagination and filtering of worklist data. STU3 offers more granular filtering options, enabling worklists to be customised by criteria such as referral status, priority, or specialty.

Data Structures: ReferralRequest and Supporting Resources

In DSTU2, the ReferralRequest resource serves as the primary object for representing a referral. It includes identifiers, patient references, service request details, and supporting notes. However, attachments such as clinical referral information or diagnostic reports often rely on external DocumentReference resources linked via extensions.

STU3 retains the ReferralRequest but introduces enhanced standardisation. For example, the handling of performer information is streamlined, and new optional elements allow for clearer capture of requested service provider details. Additionally, STU3 provides more structured support for tracking referral status transitions, enabling worklists to more easily reflect the real‑time state of a referral.

This structural evolution simplifies the design of a worklist, reducing the need for developers to build complex workarounds.

Authentication and Authorisation for Worklist Access

To access the e‑RS FHIR APIs, systems must authenticate via the NHS Care Identity Service 2 (CIS2). This OAuth‑based process requires client credentials, user context, and secure token handling. The workflow generally involves exchanging an ID token for an access token, which is then used to authorise API calls.

For worklist integrations, this step ensures that only authenticated users with appropriate roles and permissions can retrieve referral data. A common design approach is to integrate authentication into an organisation’s Single Sign-On (SSO) framework, enabling seamless clinician access without repeated logins.

It’s essential to handle token expiry and refresh logic robustly, as lost tokens can cause worklist queries to fail and disrupt clinical workflows.

Designing the Worklist Query Strategy

Building an efficient worklist means striking a balance between completeness of data and system performance. Developers should carefully design their query strategy to minimise load times while ensuring that critical referrals are not overlooked.

Key considerations include:

• Pagination: Implementing pagination correctly ensures that large referral lists do not overwhelm client applications.
• Filtering: Using filters for referral status, specialty, or creation date allows the worklist to be tailored to specific clinical teams.
• Caching: Local caching can reduce API calls but must be balanced with the need for real‑time accuracy.
• Error handling: Worklist systems should gracefully handle temporary API downtime or rate limits without losing track of referrals.

A well‑designed query strategy can significantly improve the usability of a referral worklist for clinical staff.

Handling Attachments and Clinical Referral Information

One of the more complex aspects of building a referral worklist is handling clinical attachments. These may include referral letters, diagnostic test results, or supporting images. In DSTU2, attachments are often managed through DocumentReference resources, linked to the ReferralRequest via extensions.

STU3 improves this process by more tightly integrating attachment references within the core referral model. This reduces the need for multiple API calls and simplifies the logic required to present attachments alongside referral metadata.

A practical approach is to implement conditional logic: if attachments are present, pre‑fetch and cache them for quick viewing within the clinician’s workflow. This can prevent delays during busy clinics where every second matters.

Common Implementation Challenges and Solutions

Developers frequently encounter challenges when integrating with the e‑RS FHIR API, particularly around DSTU2 and STU3 interoperability. Common issues include:

• Handling mixed environments: Some systems may still rely on DSTU2 endpoints, requiring dual support.
• Interpreting extensions: DSTU2 often uses custom extensions that can vary in structure, making parsing inconsistent.
• Managing performance: Pulling large volumes of referral data can strain both client and server resources if not optimised.
• Error code interpretation: Understanding the meaning of specific 4xx or 5xx responses is vital to maintaining uptime.

Solutions typically involve building modular code that can support multiple FHIR versions, implementing robust error handling, and working closely with NHS Digital guidance to ensure compliance.

Future Outlook: Transitioning Fully to STU3 and Beyond

The NHS is steadily encouraging a shift towards STU3 as the preferred standard for e‑RS integrations. While DSTU2 remains supported in many production environments, STU3 provides the framework for future enhancements, including better support for patient‑centred care and integration with other FHIR‑based NHS APIs.

Organisations planning new integrations should strongly consider designing their systems with STU3 as the foundation, even if DSTU2 support is temporarily required. Doing so ensures that future upgrades will be less disruptive and that worklists remain aligned with evolving NHS digital strategies.

Looking further ahead, future iterations of the e‑RS API may adopt R4 standards, bringing even greater consistency and expanded resource definitions. Preparing now will ensure systems remain adaptable.

Building an e‑Referral worklist through the NHS e‑RS API is a powerful way to transform how referrals are managed in healthcare organisations. While DSTU2 has laid the groundwork, STU3 introduces significant improvements that streamline data handling, reduce reliance on extensions, and enhance filtering capabilities. For developers and IT teams, understanding the nuances between these versions is essential for creating a reliable, efficient, and future‑proof integration.