Written by Technical Team | Last updated 15.08.2025 | 20 minute read
The NHS e-Referral Service (e-RS) is where a huge amount of NHS operational reality meets integration pragmatism. If you are building a product that needs to create, manage or triage referrals — or to surface referral context in a clinician’s workflow — the e-RS FHIR APIs are your route in. Yet the very first decision you must make is not “which endpoint shall I call?”, but “how am I allowed to call it?”. In other words: which authentication mode is appropriate, and what access level and environment do you need to progress from a prototype to a live integration?
This guide walks through the e-RS landscape in plain language and then goes deep on authentication modes, access levels and the practical steps that unlock the “path to live”. It’s written for delivery teams who want an authoritative, implementation-minded view rather than broad marketing soundbites, and it uses British English throughout.
At its core, the e-RS FHIR APIs expose the national platform used by primary and secondary care organisations in England to create and manage referrals. The public API catalogue sets out the overall purpose: create paperless referrals, interact with worklists, manage triage and advice, and retrieve metadata and attachments. Although each endpoint does something specific, a helpful way to think about the API surface is to group it by intent: initiation (search services, create referral, book slots), management (update status, reject/redirect, upload documents), and consumption (retrieve worklists, read referral context and attachments). The official specification has moved forward in recent years and is maintained on the NHS developer platform with an OpenAPI-driven presentation.
A second strand in the landscape is the “Patient Care – FHIR API”. This supports an aggregator pattern where an integrated consumer can retrieve a patient’s referrals and, in certain situations, retrieve service information for that referral. The design assumption is that you’re acting on behalf of a person rather than a healthcare worker, which is why it sits alongside rather than inside the professional e-RS API set. Understanding the distinction is vital when you’re scoping features for citizen-facing applications versus clinician-facing tools.
It’s also important to separate the modern, internet-accessible APIs on the NHS API platform from legacy network-bound variants. There is an older HSCN-bound FHIR API that is still operational but is explicitly deprecated for new integrations; it required smartcard (CIS) authentication and is not compatible with CIS2. For new development you should target the API platform versions accessible over the internet, and plan your security accordingly. This distinction has practical consequences for your networking and identity choices.
Finally, keep in mind that e-RS is a living service with programme-level updates and release notes. Subtle shifts — such as which endpoints are available with which access mode — can alter your architecture. Build your planning assumptions from the API platform documentation first, and treat everything else as context rather than canonical truth.
The e-RS APIs expose two distinct access modes. Choosing the right one is not simply a technical taste test; it locks in what you can — and cannot — do, and it shapes how you evidence governance, identity, and audit. The NHS API platform documentation is unequivocal: e-RS permits application-restricted (unattended) and user-restricted modes. No other patterns are supported for e-RS.
Application-restricted (unattended) is designed for software-to-software interactions where no human is present at the moment of the call. In this mode, you authenticate the application itself using a signed JWT (JSON Web Token). Because there is no person to attribute actions to, endpoint scope is constrained: historically this mode was read-only for operational safety reasons. If you’re building batch synchronisation, population-level dashboards, or trust-level operational reports, this is frequently the right fit, because it allows organisational context without invoking a user login dance. The catch is that you can’t behave like a clinician when nobody is logged in; you have to respect the smaller, safer capability envelope.
User-restricted mode is for everything that should be attributable to a person who is currently using your system. Here, the end user must be a healthcare worker authenticated via NHS Care Identity Service 2 (CIS2), using the OAuth 2.0/OpenID Connect patterns described by the API platform. This is the mode you’ll need for creating or altering referrals and for actions that depend on the actor’s role membership (e.g. which worklists they are allowed to see or which triage operations they can perform). Because you are asserting a person and their roles at the moment of the call, the e-RS platform can enforce fine-grained authorisation and audit fully.
A nuance that catches many teams is that application-restricted is no longer entirely read-only. For a limited, controlled subset of operations, NHS England has enabled write-back from unattended processes — notably the ability to record a triage outcome (A028), reflecting the service’s push on referral automation. The direction of travel remains cautious: the platform adds write capabilities to unattended mode where there is a robust safety case and clear organisational accountability. If you are aiming to use unattended write operations, read the release note carefully and make sure your use case aligns.
With those fundamentals established, how do you decide which mode to adopt for a given feature? A simple rule of thumb is to match the mode to the decision-maker and the risk. If a clinician is making a decision in the moment — accept, reject, convert advice to referral — use user-restricted with CIS2. If a system is aggregating, listing, or reconciling data at an organisational level, application-restricted may be appropriate. Many real-world integrations deliberately implement both modes in the same product so they can separate background jobs from foreground clinical actions. The NHS onboarding materials explicitly steer you to choose your access mode early because it affects registration, security build, and integration criteria.
When to choose which mode:
Two operational gotchas deserve mention. First, if you plan to retrieve a referral worklist in application-restricted mode (A008), you’ll need to supply a Service ID that corresponds to the provider service for which you want the list. Maintaining a reliable mapping of your organisation’s ODS code(s) to service IDs is therefore part technical integration and part operational housekeeping. Second, even in user-restricted mode, you must ensure the user’s roles actually authorise the action you’re requesting; the API will enforce this, but your UX should guide the user toward permitted flows to avoid dead ends.
Once you’ve picked a mode, the next set of decisions revolves around where you integrate and what level of access you need at each stage. Think in terms of environments (sandbox/mock, integration, production) and access levels (what a given mode can call, and under what organisational identity). The e-RS team’s onboarding materials summarise the prerequisites for getting into the integration test environment: validate your use case, pick your access mode, review the integration criteria, decide your connection topology, register with the programme, and register your application(s) on the API platform. This isn’t red tape for its own sake — each step feeds a downstream control (for example, your topology choice determines how you’ll present your software inside customer organisations).
The integration environment (often referred to as “INT”) is where you do your first end-to-end interactions against representative data on the NHS API platform. To make calls here, you must enable the appropriate e-RS API products in your developer account — in practice, that means enabling “e-Referral Service – Healthcare Worker (Integration Testing)” for user-restricted, and “e-Referral Service – Application Restricted (Integration Testing)” for unattended mode. This is where you prove your token flows, scopes, and endpoint usage work as expected.
A quick word on networking. Modern e-RS API integrations are internet-accessible through the NHS API platform; you do not need a private HSCN connection for these. There remains a deprecated HSCN-only variant of the FHIR API for existing users, but it’s not available for new integrations and used older authentication constraints. If you come across documentation that assumes HSCN, double-check you’re reading the right page for the current internet-hosted platform. This matters if you’re writing deployment guides for Trust IT teams who may still reach for HSCN as a default.
Access levels themselves vary with access mode. In user-restricted mode, the breadth of the API is open to you, governed by the user’s CIS2-asserted identity and roles. In application-restricted mode, the platform intentionally limits the endpoint set to organisationally safe operations. Recently, NHS England has extended unattended capability in specific areas (for example, recording triage outcomes as part of referral automation), but these are explicit exceptions in a controlled rollout. Check release notes and the “Maintain” stage documentation so you can align your product’s behaviour with the current allowances.
Where you host your software and how it “sits” inside an NHS organisation is captured by your connection topology. The NHS developer guidance calls this out because topology directly affects identity, audit and the blast radius of any compromise. Whether your app is centrally hosted SaaS with tenant-level separation, a trust-hosted deployment behind hospital firewalls, or a hybrid model with lightweight desktop clients, you need to configure the combination to meet the platform’s security expectations and your customers’ information governance standards. Plan this early; it’s much harder to refactor late in the day.
A simple, environment-aware path to e-RS live:
Security in healthcare integration is not something you “add later”. With e-RS, your identity model sits at the intersection of platform capability and local governance. For user-restricted integrations, you’re asserting a person with CIS2 — and that means you should design your UX and back-end to capture the asserted identity (subject ID, authentication method, role claims) and associate it with each action taken through your software. That way, audit trails can be reconstructed easily during incident response or clinical safety investigations, and users can understand why certain actions were permitted or blocked.
For application-restricted workloads, think “organisation-as-actor”. You’re acting on behalf of an NHS trust or provider service, so everything you do must defensibly align with that service’s scope. That is most obvious in worklist retrieval: the API expects you to specify a Service ID, and your logic needs to pull the correct worklist for the correct service and never bleed data across organisational boundaries. Maintaining a current mapping of ODS codes to service IDs is therefore an operational responsibility, not merely a developer convenience; you can’t rely on a static list hard-coded at build time.
Governance and “evergreen” engineering are part of the e-RS expectation set. As the platform evolves, endpoint shapes and allowances change — for example, the deprecation of an older attachment endpoint and the introduction of a new FHIR R4 download route, or the extension of unattended capability to new operations. Your release process should include watching the SCAL change log and release notes, assessing the impact on your product, and scheduling updates well ahead of deprecation dates. That is not just good engineering practice; it’s a condition of being a responsible partner.
Finally, design your error handling and observability as if you’ll one day be debugging across organisational lines — because you will. Clear correlation IDs, structured logs that include token claims (without revealing secrets), and metrics that separate user-restricted and unattended traffic will save days of effort when a trust’s integration team asks why last Tuesday’s worklist sync missed one service out of twenty.
Create a two-column table in your internal wiki with “features” on the left and “authentication mode” on the right. For instance, “create referral” and “respond to Advice & Guidance” belong to user-restricted (CIS2) because they represent clinician actions that need person-level attribution. “Generate worklist-based dashboards” or “pre-load clinic rosters” likely belong to application-restricted (unattended) because no individual is making a clinical decision at call time. If in doubt, lean toward user-restricted; it is easier to add unattended jobs later than to retrofit person-attribution into a workflow you initially built as a background process. The official guidance makes it clear that e-RS only allows these two modes and that unattended will remain scoped to safer operations, a principle you should encode in your architecture from day one.
For user-restricted, your app will need to implement the CIS2 combined authentication-and-authorisation flow using OAuth 2.0 and OpenID Connect. In practice that means your frontend handles the redirect to NHS Identity, your backend performs token exchange and verification, and both layers are designed to cope with token refresh and session expiry in a way that doesn’t leave a partially completed referral action hanging. Use the claims returned to tailor UX — for example, show only the worklists the user’s role permits — rather than optimistically letting them try and then fishing a 403 out of the response. For unattended mode, implement signed JWT client authentication meticulously, clock-skew-proof your server time, and rotate keys regularly. Do not base your unattended integration on the assumption that today’s read/write envelope will always be the same; watch release notes and be ready to adopt newly permitted operations such as triage outcome writeback.
The NHS platform gives you a clear run-up: a mock/sandbox experience for early experiments, the integration environment where your product interacts with realistic endpoints, and production once you’ve satisfied the programme’s assurance. Your internal release cycle should mirror this. In integration, enable the Healthcare Worker (INT) and Application Restricted (INT) products as needed, and verify all token flows before you wire up complex UI. Build smoke tests that hit key endpoints daily; they become canaries for platform or configuration drift. When you move to production, make sure your incident playbooks identify whether a failure is mode-specific (for example, only unattended jobs are failing because the signed-JWT issuer configuration expired) so you can triage quickly.
One of the biggest risks in health IT is boundary leakage: showing the wrong patient, booking in the wrong clinic, or pulling a worklist for the wrong service. In unattended mode, this shows up in your handling of Service IDs and ODS codes; in user-restricted mode it shows up in your use of role claims. Bake in guard rails. For example, in a trust-multi-tenant SaaS, require an explicit trust selection tied to the organisation’s ODS code at login, scope every call by that identifier, and validate that a returned Service ID belongs to that ODS code before you display or act on it. When reconciling worklists or attachments, log which organisational context each record came from and prove, in audit, that you never joined across contexts. The API’s permissioning helps, but the responsibility for safe presentation is yours.
The e-RS team regularly updates access allowances and deprecates older endpoints. A recent example: the historical retrieve-attachment endpoint is being deprecated in favour of a FHIR R4 download route, and unattended mode has been expanded in a targeted way to allow recording triage outcomes. Your codebase should treat API shapes as versioned contracts; wrap calls in adapters that you can evolve without touching every screen, and keep your platform documentation “living” by linking directly to the NHS pages your team must review as part of release gating. Also read the “Maintain” stage carefully; it spells out expectations around patching, monitoring and endpoint change management — commitments your customers will expect you to honour.
A robust onboarding story contains a clinical safety case and an operational one. Clinically, write down why a given action requires a person and therefore must be user-restricted; operationally, write down how you will monitor unattended jobs, how you will detect partial failures (for example, one service’s worklist failing while others succeed), and who will be paged if tokens fail to refresh. The NHS programme will ask for your integration criteria evidence — particularly if you’re using unattended mode, which carries additional responsibilities. Build those artefacts in parallel with your code, not as a frantic paper chase after the fact.
If you encounter documentation, demos or third-party articles that assume HSCN-only connectivity and older authentication mechanisms, pause and verify whether they refer to the deprecated variant of the e-RS FHIR API. New integrations belong on the internet-accessible NHS API platform. If you’re migrating an existing customer from HSCN to the API platform, involve the trust early; the switch alters their network posture, identity flow and sometimes their internal support model. It’s rarely a big-bang migration; adopt a dual-run strategy where possible.
In practice, the most productive integrations pair modes. Consider an outpatient clinic app used by secondary care clinicians. During the day, clinicians log in using CIS2 and perform rich user-restricted actions: accept, reject or redirect referrals; request more information; convert Advice & Guidance into a referral; and upload attachments. Overnight, an unattended job runs that pulls the next day’s referral worklists for each service, pre-caches key metadata and attachments, and flags records missing mandatory fields ready for morning triage. The daytime actions are indelibly tied to a person. The overnight job is organisational. The product remains coherent, and the auditing is cleaner because you don’t blur boundaries.
e-RS leans on the concept of the service — discrete provider services with their own identifiers that act as the locus of worklists and actions. For user-restricted flows, the platform will filter what a user can see and do based on their roles and service associations. For unattended flows, your application must present the correct service IDs and never assume that because an ODS code is right, the service context will “just work”. Build administrative screens that help your customer map services to their internal teams and clinic codes, and schedule regular reconciliations so your mapping does not drift. The community forum discussions underline how central service IDs are to reliable unattended retrieval.
Before you ask for production access, make sure your product demonstrates: (1) correct token handling under stress (refresh, expiry, revocation), (2) safe retries with idempotency where applicable, (3) human-readable audit entries with user IDs for user-restricted calls and organisational identifiers for unattended calls, (4) robust input validation for attachment handling and triage updates, and (5) rate-limiting behaviour that degrades gracefully. These are the kinds of behaviours reviewers will probe during assurance, and they are the behaviours that keep patient pathways safe when, inevitably, something fails at 3am.
The e-RS roadmap continues to push on referral automation and improving the end-to-end lifecycle. That’s why seemingly small changes — like allowing unattended writeback for triage outcome — matter: they are signals. If your product depends on unattended write actions, engage with the programme early, write clear user-restricted fallbacks, and monitor the release notes so you know when new endpoints enter or leave scope. The “Maintain” stage explicitly calls out patching and endpoint changes as your responsibility, not just the platform’s. Build a culture where your team reads those pages as part of sprint Review.
Begin with a single page that answers five questions: What outcomes will your product deliver inside e-RS? Which authentication mode maps to each outcome? Which environment do you need next (integration vs production)? What topology will you deploy to customer organisations? How will you prove audit and governance? With that in hand, register your application(s) on the NHS API platform, enable the relevant integration API products, and implement your token flows. In parallel, draft your unattended governance artefacts if you plan to use that mode: monitoring runbooks, incident plans, and a service-ID mapping process owned jointly by you and each customer. As you start calling e-RS in integration, instrument every call with correlation IDs and keep a living record of which endpoints you use so you can assess change notices quickly. When you’re ready to seek production access, your best ally is a clean, demonstrable story that shows the platform team you understand the spirit — not just the letter — of e-RS’s authentication and access model.
If you remember only three things from this guide, make them these:
First, choose the authentication mode that matches the nature of the action: unattended for organisational, machine-time operations; user-restricted (CIS2) for person-at-keyboard, clinical decisions. This is not an incidental choice — it determines which endpoints are available, how you evidence audit, and how you present risk to your customers. The official documentation is explicit about the two modes allowed for e-RS and the signed-JWT requirement for unattended.
Second, treat access level as a moving contract. The e-RS team is iterating within a safety envelope — expanding unattended to include triage outcome recording is a case in point — and deprecating older shapes (like the historic attachment retrieval) as better FHIR-native options arrive. Your engineering must anticipate change, and your product governance must own the “Maintain” story: patching, endpoint changes, and clear communication with customers.
Third, anchor your onboarding in environments and topology. Your practical next steps are to register and enable the right API products in the integration environment, wire up CIS2 and/or signed-JWT flows, and document the way your software sits within an organisation. That documentation should be robust enough that a Trust IT team and an information governance lead can say, “we understand what this product does, who it acts as, and what it cannot do,” before you ever touch live data.
Consider those three, and you’re well on your way to a resilient, future-proof e-RS integration that feels native in a clinician’s day and safe in an information governance review.
Is your team looking for help with e-RS integration? Click the button below.
Get in touch