Written by Technical Team | Last updated 15.08.2025 | 13 minute read
The NHS e-Referral Service (e-RS) is the national platform that connects general practice, community services and secondary care to enable digital referrals, triage and booking. While clinicians experience e-RS through the browser-based application, software providers increasingly integrate directly through the e-RS FHIR API. That API exposes referral and booking capabilities in a consistent, standards-based way so that clinical systems can embed referrals into their native workflows. If you are building for primary care, a hospital PAS/EPR, an advice and guidance portal or a referral management solution, understanding how the e-RS FHIR interface behaves—and how it differs from generic FHIR—will determine whether your integration feels seamless or brittle.
At its heart, the e-RS integration story is about orchestrating a multi-party workflow with strong governance. A referral is initiated by one organisation, triaged or redirected by another, and sometimes booked by patients themselves. Each step carries obligations: clinical safety, identity assurance, information governance, consent, and auditability. The FHIR API gives you the building blocks—resources, operations and profiles—but it does not remove the need to design workflows that are safe, comprehensible to users and resilient under pressure. This guide walks you through those building blocks and the practicalities of going live, from identity and security through to error handling, testing and operations.
Aligning internal data to an external standard is rarely a copy-and-paste exercise. Even the most FHIR-mature products find that e-RS has national profiles, controlled vocabularies and business rules that are stricter than generic FHIR. That is a feature, not a flaw: country-level constraints guarantee interoperability and patient safety. The trade-off is that you will spend more time on mapping, validation and conformance. Plan for this from day one and you will avoid the common pitfalls that delay onboarding.
A good e-RS integration starts with a mental model of the life cycle. Conceptually, a referral journey in e-RS moves through initiation, triage and acceptance, optionally culminating in the booking of an appointment. Specific organisations and users are permitted to act on the referral at each stage, and the API reflects that with consistent use of practitioner, organisation and patient identifiers and with resource-level access controls. Because referrals can be redirected or returned to the referrer, you should also model the possibility of loops, not just a straight line. The same applies to advice and guidance workflows, which resemble referrals but are often conversational and iterative.
The primary FHIR artefacts you will encounter mirror these concepts. The clinical intent—requesting a service for a patient—is represented by a referral request resource in older profiles and by a service request pattern in newer ones. Booking artefacts rely on appointment, schedule and slot resources, with provenance and task carrying the state transitions and work assignments. You will also see healthcare service and organisation resources to describe providers and their services, and practitioner/practitioner role to capture who is acting. Document reference is used to move clinical attachments in a structured and auditable way. If you are new to FHIR, it is tempting to treat these as independent CRUD-able records; in e-RS they are tightly choreographed, and certain operations are exposed through custom interactions rather than free-form updates.
Attachments warrant special attention. Referrals frequently include clinical documents—letters, imaging reports, structured forms—that must be transferred reliably and stored with the referral. In the FHIR world you will see these represented by document reference objects pointing to binary content. Formats are constrained (for example, PDFs, CDA or specific image types), size limits apply, and metadata matters. A robust client validates file types, sizes and hashes before upload, streams content rather than buffering entire payloads in memory where possible, and records a provenance trail so clinicians can trust what they are reading. Do not treat attachments as a secondary concern: failed or slow uploads are a major source of user frustration and operational incidents.
Search and discovery are where many teams first feel the difference between “pure FHIR” and “e-RS FHIR”. You will search for services that match a clinical need, location and eligibility criteria; you may need to fetch available appointment slots or request lists of referrals by status or worklist. In abstract FHIR, this looks like a handful of predictable _search queries. In e-RS, those searches are deliberately constrained and may require specific combinations of parameters or named operations that enforce the business rules. The upside is that your result sets are usable and policy-compliant; the downside is that generic FHIR search helpers may not fit out of the box. Plan to write targeted query utilities that reflect the e-RS profiles you are consuming.
Finally, build with statefulness in mind. Referrals are not just data objects—they are clinical workflows. State transitions (for example, triaged, rejected, booked, cancelled) are represented explicitly and drive what actions a user can take next. Attempting an operation that does not make sense for the current state will fail, and rightly so. Your user experience should surface those states clearly, make permissible actions obvious, and gracefully handle the reality that the same referral may be open in multiple systems at once. Idempotency, optimistic locking or ETag checking, and careful reconciliation logic are essential to prevent race conditions and double-booking.
NHS integrations start and end with trust—trust in who is using the system, trust in which organisation they are acting for, and trust that access is limited to the minimum necessary. The e-RS FHIR API sits inside that trust framework. In practice you will implement modern OAuth 2.0 and OpenID Connect flows to obtain access tokens that represent a real human or a well-defined application, and you will propagate the user’s role and organisation context on each call. This is not merely technical plumbing; it determines what you can see and do. Many integration challenges ultimately boil down to identity design: how you map users in your product to NHS users, how you manage session lifecycles, and how you surface to the clinician which “persona” they are using when they act.
Because referrals are clinically and legally sensitive, the platform enforces strong role-based access control. A GP creating a referral has a different permission set to a hospital booking clerk, and both differ from a consultant triaging referrals. Your client must therefore present tokens that clearly encode the user’s identity and role claims, and you should verify that your UI never offers actions the back end will reject. It is also common to require explicit organisation context: a clinician may have sessions at multiple sites, and your product must honour that context when listing worklists or creating bookings.
From a security operations perspective, there are a handful of design choices that will save you pain later. Use a confidential client capable of secure client credential management; rotate secrets and keys automatically; implement token caching and proactive refresh to avoid mid-workflow expiries; and propagate correlation IDs for end-to-end tracing. Ensure your audit trail links every action to a person, organisation, patient and timestamp, and that it can be searched and exported for clinical safety investigations.
Start with onboarding. Before writing code against production, you will complete supplier registration, nominate technical and clinical safety contacts, and obtain access to a sandbox environment. Your first engineering goal is a minimal viable flow that proves the moving parts: authenticate, create a test referral with required demographics and clinical context, add an attachment, and retrieve it from a worklist. Build that flow as a command-line script or a small harness service first. It will become your regression test and a living example for the rest of the team. Resist the temptation to commit everything into your main product until the basics are reliable.
Next, design your data mapping. Your product already has a concept of a referral or request for service, but the shape will differ from the e-RS profiles. Create a transparent field-by-field mapping and make a conscious decision about every required and optional element. That exercise reveals gaps early: missing codes, inadequate address structures, or free-text fields that must become coded concepts. Where a code system is mandated, add validation to stop bad data at source. Your mapping should include both the outbound payloads you build and the inbound payloads you parse, with a plan for versioning if profiles change.
With mapping in hand, focus on the high-risk flows: searching for services, presenting choice and eligibility, and booking. Service search is where clinical safety intersects with UX. Do not simply dump raw results; present services with the attributes clinicians care about—clinical appropriateness, distance, eligibility criteria—and explain why a service is being highlighted or filtered out. When slots are available, booking should be fast and reliable. That means robust handling of the race between viewing a slot and confirming it, and a graceful flow for when a slot is no longer available. Use idempotency keys on booking requests so a retry does not create duplicate appointments, and always surface the definitive booking reference and details back to the user.
Attachments and documents deserve their own pipeline. Implement streaming uploads to avoid memory pressure, generate hashes client-side to confirm integrity, and show progress to the user for large files. For scanning results or consultant letters arriving later, plan how those documents will be attached to the existing referral, referenced in your UI and exported to other systems. Clinical users expect to find every relevant artefact in one place, regardless of which system originated it. Your reconciliation process should link documents to the correct referral even when identifiers are partial or human-entered.
Finally, build resilience and observability from the start. Wrap API calls in retry logic that distinguishes transient from permanent errors and respects rate limits. Use circuit breakers around downstream dependencies so your whole application does not stall when the network misbehaves. Capture structured logs enriched with user, organisation, referral and correlation identifiers so that support teams can reconstruct a problem without asking clinicians to repeat steps. For long-running workflows, background workers should reconcile state regularly, detect stuck items and raise clear, actionable alerts rather than silent failures.
Operational readiness is as much about people and processes as it is about code. You will need a clinical safety case and hazard log that explain how your integration prevents, detects and mitigates harm. That safety narrative should be visible in your product: guardrails around patient selection, clear prompts when a referral is cancelled or returned, safeguards to stop bookings for the wrong organisation or clinic. Train support teams to understand referral states and booking semantics so they can triage issues quickly, and invest in an administrative console that exposes key artefacts—referrals, appointments, attachments, audit entries—without resorting to raw database queries.
Testing must combine automated and human elements. Automated tests prove conformance with profiles and protect you against regressions; exploratory testing with clinicians reveals the unintuitive corners where real-world complexity lives. Build a sandbox dataset that mimics production quirks: long patient names, unusual addresses, referrals with multiple attachments, clinics with sparse slot availability, and services with nuanced eligibility criteria. Then, test the hard bits deliberately: what happens when a booking fails at the last step, when an attachment upload is interrupted, when a referral is redirected while a user is viewing it, or when a user switches organisation context mid-workflow. The goal is not merely to pass; it is to build confidence that the product behaves predictably under stress.
Change management is a fact of life. National profiles evolve, security requirements tighten, and providers reconfigure services. Your architecture should assume change and make it cheap. Isolate your e-RS integration behind a service boundary with its own deployment cadence, contracts and test harness. Maintain compatibility matrices so you know which versions of your product support which API profiles. When a breaking change is announced, you want to land it in a single place with a controlled rollout, not chase it through your entire stack. Alongside technical changes, keep your clinical safety artefacts current: update the hazard log when you introduce new flows, and re-train users when behaviours change.
Once live, production support is where integrations succeed or fail in the eyes of users. Treat every error message as a design surface. A cryptic “400 Bad Request” is useless to a clinician under time pressure; a human-centred explanation—“This service requires a specific clinical code that was not provided. Please add [X] to the referral details.”—turns a dead end into guidance. Monitor not only failures but also signs of friction: referrals started but not submitted, repeated searches that return no results, bookings abandoned at the confirmation step. These telemetry signals point you to UX improvements that reduce calls to your helpdesk and improve clinical outcomes.
Delivering a great e-RS FHIR integration is a systems thinking exercise. It blends the mechanics of FHIR resources and OAuth tokens with the lived reality of clinical work and the governance of a national platform. Teams that succeed tend to share a handful of habits. They start with a minimal, end-to-end slice and keep it running as a regression harness. They design mapping and validation early, using the national profiles as the source of truth and baking those constraints into the UI. They treat identity as a first-class concept and model the user’s organisation context explicitly. They invest in observability and audit from day one so that support is effective and safety incidents can be investigated. And they cultivate a change-ready architecture that can absorb profile updates and new security requirements without drama.
As you plan your own build, resist the urge to think of the e-RS API as a bag of endpoints to call. Think of it as a contract to participate in a clinically governed workflow. That mindset leads to different decisions: resilient booking flows that cope with real-world races; search experiences that reflect clinical appropriateness, not just string matching; attachment pipelines that treat documents as clinical artefacts, not file uploads; and operational tooling that gives staff the visibility they need to support patients and clinicians efficiently. When you adopt that posture, the technical and human parts of the system reinforce each other rather than fight.
Is your team looking for help with e-RS integration? Click the button below.
Get in touch