Written by Technical Team | Last updated 30.09.2025 | 15 minute read
Across the NHS, “legacy” referral workflows still exist in many guises: a GP dictating a letter and a secretary uploading a PDF; a practice sending a referral into a generic mailbox and phoning the hospital to chase; a provider clinician checking several systems to see if supporting images have been received. These patterns grew organically around paper, email and portalled systems. They often depend on tacit knowledge to bridge gaps—who to call, which worklist to check, which fields are mandatory in a given form—and they struggle under volume and variance.
The NHS e-Referral Service (e-RS) was designed to remove that friction by providing a national platform for creating and managing referrals, triage and booking. What’s changed in the last few years is not just the web front-end, but the depth and breadth of the public FHIR APIs that now let you build that experience directly into GP and provider systems. You no longer have to swivel-chair between products: you can ask the API for worklists, retrieve clinical context, upload or download attachments, offer appointments or defer to triage, and exchange Advice & Guidance—all from within a single clinical workflow.
It’s common to think of “migration” as just re-wiring old screens to new endpoints. In reality, the biggest pay-off comes from mapping intent (what the user is trying to achieve) to the e-RS capabilities that express that intent safely and audibly. That means understanding access modes, FHIR resource shapes and the sequence of operations that replace handwritten lists, inbox folders and local spreadsheets with deterministic API steps. The rest of this article walks those mappings and patterns in detail, highlighting where behaviours differ from “how we’ve always done it”.
A good migration starts with a mental model of the platform. The e-RS FHIR APIs are split into referrer and provider capabilities, with cross-cutting foundations for search, identity, attachments and audit. At their heart are FHIR resources you’ll recognise—ServiceRequest for the referral, DocumentReference for the referral letter and supporting files, HealthcareService for bookable or triageable services, Appointment/Slot/Schedule for booking, CommunicationRequest/Communication for Advice & Guidance—and e-RS-specific operation-based endpoints to drive worklists and state transitions. That combination gives you both RESTful retrieval and high-level “do the thing” operations that mirror the clinical intent.
Identity and authorisation are explicit. e-RS supports user-restricted access (a healthcare worker is present, authenticated via NHS Care Identity Service 2, and actions are attributable to their role) and application-restricted access (no person in the loop; read-only, unattended tasks). As a rule of thumb, anything that changes a referral—creating, booking, triaging, accepting, rejecting—must be done in user-restricted mode. Background reads such as refreshing a worklist cache or pre-loading metadata can be performed in application-restricted mode where a read is permitted.
Several “families” of endpoints underpin common screens. Session and role endpoints initialise a professional session and determine what a user can do; reference data endpoints resolve e-RS pick-lists; search endpoints find services; clinical referral information endpoints retrieve the referral header, clinical narrative and attachments; worklist endpoints surface queues like “Referrals for Review”. Even if your legacy workflow didn’t have a named step for each, you’ll often discover that an equivalent informal step existed—someone eyeballed a shared inbox (worklist), asked a colleague which clinic to choose (reference data), or double-checked the patient letter (attachment metadata). The API makes these explicit so they can be automated and audited.
Importantly, versions of the API matter. Earlier e-RS integrations used FHIR DSTU2/STU3 endpoints and, before that, HL7 v3 and SOAP patterns. Current guidance steers new work to the FHIR APIs exposed via the NHS API platform, with specific migrations—for example, moving from STU3 Retrieve Attachment (A006) to the R4 Retrieve attachment (A042) to support downloads over 5MB. Treat version-to-version migrations as part of your plan: they bring behavioural differences, new payload shapes and occasionally new sequencing rules.
Finally, e-RS is a national platform, and the integration process reflects that. You’ll register your application on the API platform, choose access modes, request integration environment access, and work through onboarding with clear acceptance criteria. Your network topology (Internet/API platform vs HSCN-only variants) also affects the route you take. That structure is not ceremony for its own sake; it ensures your software is safe, performant and supportable in the live estate.
The easiest way to plan a migration is to start with the familiar. Below are common legacy scenarios and how they translate into deterministic, auditable e-RS API flows. Where endpoint identifiers are mentioned, treat them as anchors to the family of operations you’ll need to orchestrate; always verify current versions in the API catalogue during build.
Scenario: “We write a referral letter, attach bloods and send to the hospital’s generic mailbox.”
In FHIR, the letter and supporting artefacts are DocumentReference instances linked to the referral. Your UI first searches for appropriate services and builds a shortlist, then creates the referral (ServiceRequest) and uploads attachments. Avoid treating attachments as a single “PDF blob”: discrete files with accurate content types and metadata improve downstream triage and are easier to re-use if a service converts Advice & Guidance into a referral.
Scenario: “We book a first outpatient appointment, and if no slots are available we ask the provider to offer one.”
Legacy flows often had a “book or phone” fork. With e-RS, your software retrieves appointment slots and either books an Appointment or defers to the provider for triage. In practice, your logic is: shortlist services → retrieve slots → if slot available, book; otherwise, defer with the right reason code so the provider can pick it up promptly. Keep in mind that the ability to call search/booking endpoints is role-sensitive; ensure the authenticated user’s role aligns with the action you’re taking.
Scenario: “Our secretary checks a tray of new referrals and prints what the consultant needs.”
Replace the paper tray with worklists. The e-RS API exposes operation-based worklists (for example, Referrals for Review) returning a List of items and key attributes for triage. Your system polls or user-refreshes the worklist, fetches the referral header and clinical narrative, and downloads attachments on demand. The “print pack” becomes a one-click bundle of the ServiceRequest summary plus selected DocumentReference binaries—something you can render as a PDF locally if your clinicians still need paper for ward rounds.
Scenario: “We email specialists for advice and copy-paste replies into the record.”
Use Advice & Guidance (A&G) capabilities. The API lets a provider surface A&G worklists, fetch summaries and conversation threads, respond, and—where permitted—convert an A&G thread into a referral. That solves two legacy issues at once: clinical governance (who said what, when) and structured conversion (no re-typing). If your product serves referrers, the inverse applies: you can create and follow up A&G requests without losing context to email silos.
Scenario: “We drag-and-drop clinic letters into a network folder for the booking office to find.”
This is essentially an attachment-distribution pattern. Instead of a shared drive, rely on DocumentReference plus the retrieve-attachment operation. Be aware of the migration from STU3 A006 to R4 A042 for larger files; checking your maximum document sizes and download approach (streaming, resumable if supported) is part of hardening your build. If you previously relied on filename conventions to carry meaning, move that into FHIR metadata and e-RS extensions so it survives system boundaries.
Scenario: “We maintain a spreadsheet of services and clinicians we ‘know’ will take a given condition.”
Translate this into service search and business rules. e-RS surfaces services with clinical term associations (SNOMED CT) and other attributes via HealthcareService and related endpoints. Rather than free-text picking, your UI can drive from coded problems to candidate services. Where local knowledge still matters, store it as configuration that augments the search results (for example, flagging services your organisation prefers) rather than replacing them. That way, referrals continue to land where they should if a named consultant rotates or a provider changes access rules.
Here’s a compact reference you can adapt into a team design note:
Those flows won’t be pixel-for-pixel replicas of your legacy screens, and that’s the point. A good migration pares back UI chrome and focuses on the minimal clicks that achieve a safe, auditable outcome with the right codes attached.
A solid technical pattern balances developer ergonomics with platform rules. In e-RS, that starts with choosing the right access mode per feature. User-restricted mode uses CIS2 to authenticate the healthcare worker via OAuth/OIDC, making authorisations attributable to their current role membership. Your app obtains an ID token from CIS2 and exchanges it for an access token at the API platform before calling e-RS endpoints. Application-restricted mode uses a signed JWT pattern for machine identities, suitable for read-only unattended calls. Mix them carefully: for example, you might refresh a provider worklist cache application-restricted, but fetch clinical detail and perform actions only when a logged-in user opens a referral.
Network topology and variants still matter. The mainstream route is the Internet-facing NHS API platform, but an HSCN-only variant of the e-RS FHIR API exists (and older HSCN-only integrations may be in use). Knowing your deployment landscape—GP practice systems, acute trust networks, cloud workloads—helps you choose the right connectivity and plan for things like smartcard authentication if required by a given role. Treat HSCN-only integrations as legacy constraints you’ll unwind where possible, keeping an eye on official guidance about deprecation and platform route-maps.
Audit logging is not optional. Partners integrating with the e-RS FHIR API must create and maintain audit logs in their application. Those logs should capture who did what (user identity and role), to which referral (UBRN or unique identifier), when (with precise timestamps), from where (client and network context), and with what outcome (success/failure, OperationOutcome details). That’s not just for cyber and platform support; it’s what lets you satisfy subject access requests and investigate incidents quickly. Bake an audit façade into your SDKs so every call path can log consistently without copy-pasting boilerplate across services.
Environments and onboarding are straightforward once you frame them as a pipeline. Register your organisation and application, pick your access modes, decide on your connection topology, and request integration environment access (INT). Use the INT professional UI to seed test data where the APIs require it—for example, defining services bound to clinical terms so search queries return results. Work through the integration criteria before you target production. Treat “path to live” not as gatekeeping but as codified acceptance tests that harden your solution.
Keep an eye on versioned migrations. The platform publishes migration guides—such as the move from STU3 attachments to R4—and deprecation notes for older endpoints. Build feature toggles so you can switch endpoints with low risk, and maintain payload mappers that pin the exact FHIR profile versions you’ve implemented. Doing this early saves you from “big-bang” rewrites when an endpoint transitions or a bug fix changes an OperationDefinition parameter.
A migration succeeds or fails on detail. These recommendations are drawn from common snags teams hit when moving real-world workflows onto the e-RS API surface.
A few migration pitfalls are worth calling out in more depth. First, endpoint deprecations are live issues, not footnotes. Teams still discover that a previously working STU3 endpoint behaves differently in INT vs production, or that an older operation is flagged as deprecated after a release. Keep your dependency on specific A-numbers behind a service layer and prefer capability-driven code (“retrieve attachments for UBRN”) to hard-coding endpoint identifiers in feature modules. Where a migration guide suggests replacing multi-function endpoints (for example, “create and send for triage”) with a more explicit two-step flow (create, then book/defer), your UI should mirror that explicitness. Users actually benefit from seeing the state move through recognisable steps when something goes wrong.
Second, role semantics are stricter via API than in some web flows. Teams are sometimes surprised that the same human, wearing a provider hat in the web UI, cannot call certain referrer-side endpoints via the API without the appropriate role. Make role switching and visibility obvious in your application—show which role is currently active and grey out actions that the role cannot perform. It’s better to be up-front than to “let them try” and respond with a 403.
Third, test Advice & Guidance as a first-class flow rather than a side project. A&G is now central to demand management and often the fastest path to expert input. Ensure your implementation supports retrieving the conversation thread, composing responses with attachments, and—where enabled—converting an A&G to a referral without losing continuity. Provide clinicians with a single timeline view so they don’t have to guess which file or message is current.
Finally, plan your cutover. Dual-running is attractive but can create split-brain behaviours: a secretary still uses the inbox “because it’s faster”, or a clinician responds to an email instead of the A&G thread the provider monitors. Short, decisive cutovers work best when the product experience is clearly superior and when you’ve rehearsed edge cases in INT. Publish the “why” (auditability, speed, reduced rework) as widely as the “how”.
If you strip legacy workflows down to intent, four big buckets remain: find the right service, create the referral and attach the right context, progress the referral (book, defer, triage, accept, reject), and collaborate (Advice & Guidance, conversion). The e-RS API surface maps cleanly to those buckets—with search and shortlist endpoints for discovery, ServiceRequest and DocumentReference for creation and context, booking/deferral/triage operations for progression, and Communication* resources for collaboration. Your migration is about choosing the right access modes, sequencing those operations into minimal-click flows and making everything observable via audit and telemetry. The result is a safer, faster and more maintainable referrals experience.
The prize is not just performance or paper saved; it’s a future where your referral pathways are explicit code, not implicit lore. When the API adds a new function or tightens a rule, you ship a small change with confidence. When a hospital consolidates services, your searches adapt. And when patients ask “what’s happening with my referral?”, you can answer using data you trust rather than a best guess.
Key resources to check during delivery (and to bookmark for your team): the e-RS FHIR API catalogue and endpoint list for capability scope, the security and authorisation guides for token patterns, the migration guides for version changes, the Advice & Guidance flow descriptions for collaboration, and the integration environment access page for your path-to-live steps. Those pages are living documentation; review them at the start of each milestone to catch subtle but significant updates.
Is your team looking for help with e-RS integration? Click the button below.
Get in touch