A working map for teams building against national NHS services

Your application never talks to 'the NHS'. It talks to Spine for identity and transactions, GP Connect through a Spine proxy, PDS as a separate lookup, and MESH quietly moving documents underneath all of it. Build against any one of these as if it were the whole picture and the other three still need building, usually discovered the week you thought you were done.

Knowing which national service does what, and how they chain together, is the difference between a clean go-live and months of rework nobody budgeted for.

Spine is the plumbing, not a single API

Spine verifies identities, moves messages and coordinates transactions between organisations. Some services sit directly on it, the Electronic Prescription Service being the clearest example. Others are brokered through a Spine-managed gateway, notably GP Connect via the Spine Secure Proxy. Others again are Spine adjuncts you'll only notice when something breaks, like the Spine Directory Service, which tells your application where to send traffic and which certificate to use.

FHIR is steadily becoming the shared language across all of this, from GP Connect's clinical record access to the Booking and Referral Standard. Even where a service still moves payloads the old way, MESH being the obvious case, the content inside is increasingly FHIR-profiled. Clean FHIR mapping early in your architecture pays for itself: less custom code, clearer tests, easier evolution as the underlying services change shape.

Identity splits into three systems

CIS2 is workforce identity. It authenticates staff, asserts role and permission claims, and gives you national-standard traceability of who did what. Build role-based access against CIS2 claims from sprint one; retrofitting it after the features exist is expensive and a common reason assurance reviews stall.

NHS Login is citizen identity: OpenID Connect with progressive proofing levels, built for mobile and web, and the same service behind the NHS App. Treat an NHS Login token as more than a sign-in. It is your consent artefact for every subsequent call you make on that citizen's behalf, whether that's a PDS lookup or a GP Connect read.

NHSmail is not an identity provider for APIs, but it shows up in real deployments anyway. It is the standard secure email ecosystem for NHS organisations, and teams use it for operational notifications, resilience fallbacks and onboarding, especially in early rollout phases before every partner is API-ready.

The patient workflow is a chain

PDS is almost always your first clinical integration. It resolves and validates NHS numbers and demographics, and using it well is less about identity for its own sake and more about safer patient matching, fewer duplicate records, fewer misfiled documents downstream.

GP Connect is the usual next link: Access Record HTML for a human-readable view a clinician would recognise, Access Record Structured where you want computable FHIR resources to reason over programmatically, and Appointment Management where a permitted service needs to book directly into general practice. Where a snapshot matters more than the full record, the Summary Care Record gives a time-critical view of medications and allergies for direct care. The access model is deliberately conservative: you'll need to show a legitimate relationship and an auditable reason before you get near it.

Once a decision is made, e-RS and BaRS move the patient on. e-RS covers planned care, referrals, triage and secondary care bookings. BaRS is newer and aimed at the messier first-contact routes, 111, 999, urgent and community services, using the same FHIR patterns but built to tolerate both instant and delayed responses. When the episode ends, Transfer of Care sends a structured discharge summary or clinic letter back to general practice, replacing what used to be a PDF nobody's system could file automatically. The Patient Care Aggregator is the newest piece, aiming to give citizens one consolidated view of their own care built on the same underlying data clinicians already trust.

Map that whole chain before you commit to a single API. Where identity is proven, which consent applies, and where data gets cached will shape your architecture more than any individual endpoint.

Transactions and messaging need different transport, not different APIs

EPS is the sharpest example of why state matters more than payloads. A prescription moves through deterministic transitions, prescribed, signed, released, claimed, dispensed, completed, and Spine holds the source of truth throughout. Get the state machine wrong, cancellations and replacements included, and you don't have a bug, you have a patient safety incident waiting to happen.

Where GP Connect doesn't reach, IM1 fills the gap: a formal pairing process with individual GP system suppliers for capabilities like record writes, tasks and documents. It's bilateral work per supplier, not a shortcut, so treat it as a complement to national provision rather than a substitute for it. MESH remains the workhorse for document exchange, pathology, screening, GP Connect's 'send document' capability, Transfer of Care. It behaves differently from REST, you post to a mailbox and poll for acknowledgement, but its reliability under patchy connectivity is exactly why it's still the default for anything that can tolerate near-real-time rather than instant. SDS sits underneath all of it, telling you where to send traffic and which certificate to use, so you're never hard-coding an endpoint that changes the next time a practice migrates system. NHS Notify handles the templated reminders and updates that keep DNA rates down, wired into your consent model rather than bolted on beside it.

The architecture that survives contact with all of this is one adapter per national service, each owning its own state handling, retries and error recovery, so a change to one doesn't ripple through the rest of your codebase.

Build the safety case before the first line of code

The fastest teams treat NHS integration as a product capability, not a sequence of tickets. Start with a clinical safety case that flows from your actual user journeys; it forces clarity about which national services you truly need, which roles must access them, and what evidence of consent you'll present, before you've written anything you'd have to unwind.

Testing needs to inject failure, not just replay happy paths: timeouts and partial results for FHIR calls, mailbox outages and duplicate deliveries for MESH, every cancellation and replacement edge case for EPS until the state machine is provably solid. Keep correlation IDs on every outbound call and metrics that encode clinical outcomes, not just uptime, so an incident review has something to work from besides guesswork.

Assurance goes faster when you can show your working: sequence diagrams per user journey, a DPIA that maps fields to lawful bases, hazards tied to specific UI behaviours, and role mappings from CIS2 or NHS Login claims to features in your app. When an assessor asks why you need SCR access at a particular point, that dossier should make the clinical rationale obvious without a meeting.

A short checklist before you commit to a go-live date

• Onboarding paths. Confirm supplier onboarding steps and queue times per service, sandbox through to live, before you promise a date.
• Data residency and hosting. Check UK residency, DSPT alignment and cloud assurance early, since these block approval late if left until the end.
• Versioning. Plan for FHIR and schema changes explicitly so an upstream upgrade doesn't force an urgent re-assurance.
• Operational ownership. Name who monitors each integration and responds to Spine or MESH incidents before you go live, not after the first one.
• Evidence pack. Keep architecture diagrams, dependency lists and data flow summaries current; procurement and ICS partners will ask for them.