Handling Referral Actions: Using Accept, Reject, Redirect APIs in e‑RS FHIR Endpoints

The NHS e‑Referral Service (e‑RS) is a cornerstone of digital healthcare in England, streamlining how patients are referred to secondary care and ensuring their journey is both efficient and transparent. For developers and healthcare organisations integrating with e‑RS through FHIR endpoints, referral actions such as accepting, rejecting, or redirecting referrals are among the most critical features to implement correctly. These actions determine how a referral progresses through the system and directly impact patient care pathways.

This article explores in depth how to handle referral actions using the e‑RS FHIR API endpoints, with a strong focus on the technical considerations of working with the Accept, Reject, and Redirect functions.

The Role of Referral Actions in NHS e‑RS Integration

Referral actions are the operational backbone of e‑RS. They allow providers to manage the flow of patient referrals, ensuring that requests are directed to the most appropriate services while maintaining a clear audit trail.

The ability to programmatically accept, reject, or redirect a referral is vital for reducing manual administration and supporting clinicians in making timely decisions. Without these endpoints, referral processing would remain a largely manual exercise, with increased risk of delays, data errors, and patient dissatisfaction.

A well‑designed integration with referral actions embedded allows organisations to unify the referral process with their internal Electronic Patient Record (EPR) systems or bespoke care management platforms.

FHIR and the Structure of e‑RS Referral Actions

The e‑RS API leverages the FHIR standard, providing RESTful endpoints that return structured JSON payloads. Within this architecture, referral actions typically extend the core ReferralRequest resource, supplemented by operation endpoints that trigger workflow changes.

The Accept, Reject, and Redirect functions are not separate resources; rather, they operate on the ReferralRequest object, updating its state according to NHS workflows. STU3 implementations provide more structured support for these updates than earlier DSTU2 endpoints, offering greater consistency in data handling and action auditing.

For developers, this means that understanding how FHIR operations are bound to referral resources is fundamental when building robust action handling.

Authentication and Authorisation for Referral Actions

Access to referral actions requires secure authentication through the NHS Care Identity Service 2 (CIS2). Using an OAuth 2.0 flow, a system exchanges client credentials and user context for access tokens.

The security model is designed to ensure that only authorised healthcare professionals with the appropriate role-based permissions can perform referral actions. For instance, a referral may only be accepted by a clinician with the appropriate specialty designation.

Implementations must handle:

• Token lifecycle management to ensure sessions remain valid during clinical workflows.
• Role-based access checks to prevent unauthorised users from accepting or redirecting referrals.
• Audit logging so every action taken through the API is recorded for compliance.

Accepting a Referral Using the e‑RS API

Accepting a referral signifies that the provider has reviewed the request and is prepared to deliver the required service. This is one of the most common and straightforward referral actions.

The Accept action typically involves a POST or PUT request to the referral action endpoint with the referral ID. The payload may include optional metadata, such as the clinician who accepted the referral and any internal notes. On successful acceptance, the referral status is updated to reflect readiness for booking or consultation.

In STU3, the acceptance process benefits from clearer status codes and structured response messages, ensuring downstream systems receive confirmation without ambiguity. This reduces the risk of duplicate or incomplete acceptance records appearing in the worklist.

Rejecting a Referral: Clinical and Technical Considerations

Rejecting a referral is a sensitive action, as it has direct implications for patient care and service planning. Rejection may occur if the referral is inappropriate for the service, incomplete, or outside the scope of the provider.

From a technical perspective, the Reject API requires a payload that specifies both the rejection reason and, where possible, guidance for next steps. The rejection reasons are drawn from NHS-defined code sets to ensure consistency across providers.

Developers must pay particular attention to:

• Validation rules: ensuring the rejection reason is valid within the FHIR specification.
• Response handling: confirming that the rejection has been successfully logged within e‑RS.
• User prompts: enabling clinicians to select appropriate rejection reasons through user-friendly interfaces.

The Reject action ensures referrals are not simply discarded but recorded accurately to maintain accountability and allow for resubmission if corrected.

Redirecting a Referral to a More Suitable Service

Redirecting a referral allows providers to move the request to a more appropriate service within e‑RS. This avoids rejection while ensuring the patient’s care pathway continues without unnecessary delays.

Technically, redirecting is more complex than acceptance or rejection. It requires the system to:

• Identify an appropriate alternative service through the e‑RS Service Search API.
• Submit a redirect request referencing the new service ID.
• Provide justification for the redirect, which is captured in the referral audit trail.

In practice, redirecting is most effective when integrated with intelligent service selection features, allowing clinicians to identify suitable services in real time during the referral review process.

Handling Referral Status Transitions in Worklists

Referral actions directly influence how referrals appear in provider worklists. When a referral is accepted, it moves to a ready-for-appointment queue. When rejected, it is removed from the active list but remains available for audit. When redirected, it disappears from the current provider’s worklist and reappears in the target service’s queue.

Developers building worklists must ensure their applications refresh status information frequently enough to reflect these changes in near real-time. In STU3, more granular status codes are available, making it easier to differentiate between various action states and provide clinicians with accurate referral progress updates.

Error Handling and Response Codes

Robust error handling is critical when dealing with referral actions. A failed referral action can disrupt patient care if not caught and corrected quickly. Common error scenarios include invalid referral IDs, insufficient user permissions, and expired tokens.

To mitigate issues, developers should:

• Implement retries for transient errors.
• Log all failed actions with detailed response payloads for audit and debugging.
• Provide clear error messages to users, avoiding ambiguous “action failed” prompts.

Typical response codes include:

• 200 OK / 201 Created for successful actions.
• 400 Bad Request for validation errors.
• 403 Forbidden for insufficient permissions.
• 404 Not Found when the referral ID does not exist.
• 500 Internal Server Error for issues on the NHS platform side.

Best Practices for Implementing Referral Action APIs

Successful implementation of referral action endpoints requires a balance between technical precision and user experience. Key best practices include:

• Design intuitive interfaces so clinicians can perform actions without navigating complex menus.
• Validate payloads locally before submission to reduce the risk of rejection from the API.
• Incorporate audit logging for compliance and traceability of actions.
• Use STU3 endpoints where available, as they provide richer status handling and clearer error responses.
• Test extensively in sandbox environments to catch integration issues before deploying to live systems.

These practices not only improve technical reliability but also ensure clinicians can focus on delivering care rather than troubleshooting system issues.

Preparing for Future Enhancements in e‑RS APIs

The NHS continues to enhance the e‑RS platform, and future API releases are expected to expand the scope of referral actions and improve interoperability with other FHIR-based systems. This may include more detailed clinical metadata capture, expanded redirect logic, and improved patient‑facing transparency through linked APIs.

For developers, building referral action handling with modular, version‑agnostic architecture ensures that systems can adopt future standards without extensive rework. Organisations that proactively adapt to evolving NHS digital standards will be better positioned to deliver seamless, future‑proof referral pathways.