Written by Technical Team | Last updated 15.08.2025 | 18 minute read
For years, the NHS e-Referral Service (e-RS) has been the national gateway for moving people from primary to secondary care. The arrival of e-RS’ modern FHIR APIs means you can drive that highway directly from your software: create, update, triage, and track referrals without printing a single sheet. The result is a referral pathway that is faster, auditable by design, and kinder to clinicians’ time as well as to patients who expect digital-first experiences.
Digitising the referral flow is not simply a matter of replacing a letter with an upload. With FHIR at its core, the e-RS API makes referrals modular, queryable, and event-driven. That opens the door to automation—pre-population of referral data from GP systems, automated service search and shortlist generation, structured attachments, and real-time booking or deferral. It’s the difference between a document-shipping process and an integrated care journey that is secure, traceable, and measurable end to end.
If you build on the e-RS FHIR API thoughtfully—respecting its resource model, security patterns, and operational constraints—you can deliver a paperless flow that feels native in both the GP and provider contexts. This article is a practical blueprint for doing just that: understanding the API’s shape, designing patient-centred journeys, implementing step by step, and proving value with metrics that matter.
At its heart, the e-RS FHIR API is a RESTful interface that exposes referral operations aligned to FHIR resources. It is designed to support two distinct duty-of-care perspectives: the referrer (typically primary care) who originates and manages referrals, and the provider (secondary care) who receives, reviews, books and treats. That split shows up in the endpoints you’ll use, the authorisation model, and in how records are retrieved and updated across each stage of the pathway.
From a standards perspective, you will encounter both the England-specific FHIR profiling and familiar core resources like Patient, Practitioner, HealthcareService, Appointment, Task, and (depending on the operation) a referral-carrying artefact such as ServiceRequest or a referral wrapper defined by the specification. These resources form the building blocks for search, shortlist creation, booking, deferral, triage (Referral Assessment Service), advice & guidance, and document management. Where e-RS imposes constraints (for example, mandatory identifiers or value sets), those are specified in the implementation materials and OpenAPI specification published by NHS England.
Security is non-negotiable and handled using NHS patterns. For clinician-facing integrations you’ll authenticate end users with NHS Care Identity Service 2 (CIS2) and authorise API calls accordingly. For patient-mediated read scenarios (such as showing a person their referrals in a citizen app), the Patient Care API is designed to be used by a Patient Care Aggregator acting on behalf of the patient. Both modes rely on OAuth 2.0 flows and JWT-based tokens but reflect different identity assurance routes and scopes. In development, you can accelerate onboarding by using the mock authorisation service to simulate users and tokens.
It’s important to regard e-RS as more than a single endpoint. You are integrating with a national platform that enforces role-based controls, business-function checks, service eligibility, and data minimisation. That means your software should be ready to handle errors that reflect legitimate-relationship checks, business function entitlement issues, or slotting constraints when booking. Monitoring these responses and presenting clear remediation messages to users is a core part of an excellent paperless experience, not a bolt-on.
In practice, you will weave the e-RS FHIR API into your own system’s capabilities. For referrers, that might include pulling the patient context from a GP record, using the API to search and shortlist suitable services, attaching the referral letter and structured data, then booking or deferring. For providers, it might include syncing “Referrals for Review”, surfacing the clinical referral information and attachments in your EPR, triaging, booking, rescheduling or cancelling appointments, and sending outcome updates back to e-RS so the worklist stays authoritative.
At a glance, the e-RS FHIR API surfaces capabilities such as:
The easiest way to design a robust paperless pathway is to start with the people using it and sketch the happy-path alongside the necessary safety rails. Let’s consider two complementary journeys—one for a GP referrer and one for a provider service.
A referrer-first journey begins inside the GP system with a patient in context. Your UI should pre-populate a referral draft with demographics, the clinical justification, relevant coded data, and preferred parameters such as location or waiting-time ranges. Using the e-RS API, the system searches for suitable HealthcareService entries and constructs a shortlist. If the case benefits from vetting before booking, the referral is submitted to a Referral Assessment Service with attachments. Otherwise, live slot availability is retrieved and an appointment is booked immediately, with the confirmation shared digitally with the patient.
A common friction point is attachments—do not treat them like a file upload after the fact. Make attachments part of the clinical authoring experience: allow clinicians to generate a well-structured letter from coded data, include recent results where appropriate, and validate that mandatory elements are present before submission. Where your system holds structured data already, attach the smallest useful artefacts rather than entire PDFs, and prefer machine-readable where allowed so providers can triage quickly. The e-RS API supports linking attachments to the referral in a way that keeps the record consistent.
Your design should acknowledge that not every referral is book-now. Build a deferral flow that is as smooth as booking. For example, when a clinician chooses to defer, your UI should capture the rationale, show what will happen next, and provide a way to track progress. Notifications to the patient—ideally via your product if it is patient-facing, or via existing NHS channels where appropriate—must make it clear whether action is needed. The point of paperless is not “no paper”; it is no ambiguity.
On the provider side, think in terms of worklists. The e-RS “Referrals for Review” list becomes the top of your intake funnel. Your integration should pull new items into the EPR or referral management system on a schedule or via a user-initiated refresh, expose all the clinical referral information (CRI) and attachments, and support decisioning: accept, reject (with a coded reason), seek advice, or request more information. When an appointment is required, keep the clinician in one place—offer slot management from within your UI rather than bouncing people to separate portals. Updates you make—acceptance, booking, cancellation—must be pushed back to e-RS so the national record stays authoritative and other parties see a consistent state.
Finally, advice and guidance deserves first-class treatment. In many pathways, A&G helps avoid unnecessary first outpatient appointments by getting quick input from a specialist. If your product supports it, integrate A&G as a peer to referrals so that clinicians can pivot from A&G to referral (or vice versa) without re-entering data. Where the e-RS API offers a way to link these conversations with subsequent referrals, preserve the lineage; it becomes gold dust for audit, safety review, and service improvement.
Before you write a single line of code, lock down your operating model: who will use the integration (clinicians, admin staff, patients), from which organisations, and under what roles? Map those to the e-RS business functions and to the identity flows you need to support. For workforce-facing flows, plan to integrate CIS2 with your application’s session model; for patient-mediated read flows, decide how your aggregator will authenticate patients (for example, NHS login in adjacent APIs) and how you will represent consent and access control in your own system. In early development, the mock authorisation service is your friend—it lets you simulate tokens for different user personas without wiring smartcards on day one.
A pragmatic step-by-step path looks like this:
When you model requests and responses, respect the FHIR profile constraints and use the correct identifiers. Healthcare services will carry identifiers aligned with NHS England profiles (for example, service IDs and ODS codes); appointments and tasks often require specific status transitions and coded reason values. Build schema validation into your CI so you know instantly when an element drifts from the contract or when a dependency upgrades a profile. NHS England publishes OpenAPI definitions and profiling guidance; consume those artifacts in your code generator or test harnesses to reduce manual drift.
Expect to support both “book now” and “defer to provider” patterns. For book-now, your code will search availability, render slots, and post a booking. For deferral, you will capture a minimal set of fields and hand the case to the receiving service’s review queue. In either scenario, your system should maintain a friendly, human-readable timeline that mirrors the underlying FHIR state transitions. Many teams find it helpful to build a tiny state machine for Referral → Shortlisted → Booked|Deferred → Accepted|Rejected → Attended|DidNotAttend → Completed, even if those are collapsed under the hood—this keeps the UI consistent.
Plan for resilience in the messy middle. Network partitions, timeouts, and partial failures are inevitable. Use correlation IDs across calls; treat each write as idempotent where the API allows; and never assume success until you’ve confirmed the new canonical state from e-RS. If your product synchronises data into a local store, introduce a compact, append-only audit log of e-RS interactions—this accelerates troubleshooting and allows safe replay.
Core technical patterns that work well with e-RS FHIR:
Going paperless is ultimately a service change, not just a new API integration. Your go-live plan should sequence targeted pathways and practices rather than flipping an entire ICS in one day. Start with a one-to-many pathway (for example, GP → single specialty) to refine data capture, attachments, and booking rules, then broaden to neighbouring specialties. Bring operational leads into the design sessions early: they will tell you which reason codes, slot rules, and triage thresholds matter most, and they will spot exceptions that should inform your UX copy.
Safety and governance are materially easier in a FHIR-native world because you can observe structured state changes. Commit to a clear clinical safety case and a DCB0129/0160 approach that is proportionate to your product’s class. Bake in role-based access checks and legitimate-relationship validation responses as first-class UI messages; do not bury them in logs. Operational dashboards should elevate measures that correlate with better patient experience and staff time saved: percentage of referrals booked at first attempt, time from referral creation to booking, triage turnaround time, cancellation reasons by code, and the rate of referrals that needed re-work due to missing attachments.
The final hallmark of a mature, paperless referral flow is continuous improvement driven by real-world data. Use the structured nature of e-RS interactions to find bottlenecks. If a service’s slots are repeatedly exhausted, show alternative services sooner. If certain attachments trigger frequent requests for more information, nudge referrers at authoring time with a checklist. Over time, you can fold those learnings back into clinical templates so the system gently steers everyone towards “right first time”.
While FHIR is famously flexible, your goal here is consistency. Treat the e-RS API’s view of the world as the source of truth for referral state and mirror it in your own data model with as little transformation as possible. In particular, preserve server-assigned identifiers on everything you create—referral identifiers, appointment IDs, and any document links—so that reconciliation is reliable and humans can cross-reference across systems when needed.
For patients, keep a minimal mirror of demographics necessary for rendering referral context. If you already integrate with PDS in your product, resist the urge to enrich the e-RS payloads with every attribute you hold; stick to what the API expects and what the receiving service needs. For clinicians, store the identifiers you receive (such as SDS user ID) so you can accurately attribute actions and debug authorisation errors. For services, index the descriptors you care about (specialty, sub-specialty, locations, booking type) locally to accelerate search and shortlist rendering, but plan a periodic refresh to keep them aligned with the national directory.
When it comes to appointments, be precise about status transitions. A cancellation, for example, isn’t simply “no longer booked”; it often requires a coded reason and may trigger downstream steps such as notifying the referrer or re-opening a deferral/triage path. Design your front end so that users cannot enter free text where a code is required. The same applies to acceptance and rejection decisions on the provider side: ask for the minimum fields necessary to keep the e-RS record coherent and to allow analytics to make sense later. If you see spikes in rejection for a particular reason code, you’ll want confidence that people were using the same set of options.
Document handling deserves special attention. Although many teams start with PDFs, you will get more value by treating documents as structured payloads where possible. That might mean generating a rich referral letter from a template populated with codes and key measurements, or attaching discrete artefacts like recent bloods and imaging results in addition to the narrative. The goal is to make triage fast and safe: specialists can scan the key facts quickly, and any automated rules you build (for example, “reject referrals missing an eGFR in the last six months”) become feasible. Over time, this reduces the “refer-to-and-fro” that drags down both patient experience and clinic utilisation.
Finally, design for partial agility. National profiles and value sets evolve. Your product should make it easy to update these without a full release—load value sets at start-up, flag profile changes in your CI, and include schema versioning in your validation layer. When upstream specifications add new fields or codes, you can surface them with minimal disruption. Keeping your integration adaptable is as much a part of paperless success as the initial build.
Paperless fails if clinicians feel like the paperwork merely moved on-screen. Invest in micro-copy and defaults: set sensible defaults for priority, use progressively disclosed fields, and pre-check boxes where policy allows (for example, consent to share referral details with the provider). Consider an author-then-send pattern with live validation so the referrer can spot missing data before submission. On longer forms, anchor the experience with a sticky “Referral summary” card that updates as you type; it gives a feeling of progress and reduces cognitive load.
Service search is a place where poor UX breeds frustration. Shortlists should be explainable—show why a service appears (specialty match, distance, waits) and why some are hidden (eligibility rules). When presenting slots, prefer a calendar-like grid with keyboard shortcuts and smart filters (soonest, nearest, wheelchair access). If you support triage (RAS), explain what happens after submission and reflect status changes visibly on the patient’s timeline.
For providers, surface high-signal information first: reason for referral, key vitals/tests, alerts and safeguarding flags, and any prior A&G thread. Design decision buttons that read like actions—Accept, Request more information, Redirect, Reject—and back them with just-enough fields. If your product integrates with theatre or clinic templates, make booking within the same screen to avoid context switching. Provider users are happiest when they can review, decide, and book in minutes.
Error messages are part of UX. Translate low-level errors—business function not found, legitimate relationship missing, slot conflict—into human language and offer a next step. For example: “This action requires the ‘Referral Management’ business function. Ask your organisation’s e-RS admin to grant it.” That prevents tickets, reduces delays, and makes the paperless promise feel real rather than brittle.
Your route to live will run through environmental gates. Begin with local development against the mock authorisation service to exercise headers, tokens, and basic calls. Move into integration/INT and pre-production to test with real authorisation, more realistic data, and formal test packs. Each step should tighten your non-functional standards: timeouts, retries with jitter, circuit breaking, and idempotency keys where available. Keep a close eye on known-issues pages during development so you aren’t debugging a platform-side defect that has already been acknowledged.
For functional testing, construct golden journeys covering book-now, defer, triage, and cancellation. Add nasty-path scenarios: expired tokens, business-function failures, slot races, attachment format errors, and network blips. Automate as much as you can with contract tests that validate payloads against the published OpenAPI and FHIR profiles. Then, before a controlled go-live, run a closed-loop pilot with two or three practices and one receiving service: watch the referral timelines, ask clinicians to record friction, and tweak your defaults and prompts.
During rollout, treat analytics as a clinical safety tool as well as a product KPI engine. Alert on spikes in failed bookings or in “request more information” events; keep a real-time counter of “referrals stuck in limbo” (for example, >7 days without movement). These are the invisible mountains of paper that digital should flatten. A handful of clear dashboards will help clinical leads see progress and will convince sceptics that paperless is not a hollow slogan but a measurable improvement in care coordination.
Because you are integrating with a national service and moving patient data, IG and clinical safety must be part of day one thinking. You will need a lawful basis under UK GDPR, a clear articulation of roles (controller/processor), and a data flow map describing exactly what passes through your service. For clinical safety, align to DCB0129 (manufacturer) and DCB0160 (deployment) standards; maintain a hazard log that is fed by real incidents as you scale. Many hazards are mitigated directly by the e-RS business rules and identity controls, but your software’s UX and operational processes carry the rest.
Change management is where paperless lives or dies. Train users in the why (faster bookings, fewer rejections, more transparent timelines) and in the how (what to enter, what not to enter, how to choose services). Nominate “super users” who can coach colleagues and act as the first line for pathway exceptions. Above all, keep feedback loops short: if a specialist team repeatedly requests missing information, change your referrer forms within days, not quarters. People adopt the tools that adopt their reality.
National platforms evolve: profiles change, endpoints expand, and security policies tighten. Your codebase should assume change and make it cheap. Externalise value sets, employ semver-aware validators in CI, and write a thin adapter between your domain model and e-RS payloads so you can swap in new fields or headers with minimal blast radius. Where the e-RS team publishes updates and guidance, subscribe and adapt quickly—the organisations that treat change as a first-class citizen remain paperless when others are printing again.
At the same time, keep an eye on patient-mediated experiences. The Patient Care flavour of the e-RS FHIR API makes it straightforward to surface referral status in a citizen app. If your product plays in that space, design once for both the clinician and patient lenses so that transitions are consistent and reassuring, not confusing. The closer you get to real-time transparency, the more your paperless referral journey feels like a shared plan rather than an opaque hand-off.
A truly paperless referral workflow isn’t a single integration; it’s a chain of well-thought-out decisions across architecture, UX, governance, and operations. Use the e-RS FHIR API to do the heavy lifting—identity, national service directories, referral state, worklists—and then add value where software shines: validating before sending, smoothing booking and deferral flows, and providing a living timeline that every participant can trust. Do those things well and you will deliver what the NHS wanted when it built e-RS in the first place: referrals that move at the speed of care, not the speed of paper.
Checklist to get started:
Is your team looking for help with e-RS integration? Click the button below.
Get in touch