Written by Technical Team | Last updated 09.09.2025 | 12 minute read
Modern NHS platforms increasingly expose functionality and data through APIs, and that is transforming how clinical software is built and deployed across primary, secondary, and community care. For developers, “NHS API integration” usually means connecting patient-facing or staff-facing applications to national services (like NHS login, the Personal Demographics Service and National Record Locator), to GP IT estates through GP Connect, and to messaging infrastructure like MESH. Doing this well is as much about identity, safety and information governance as it is about HTTP and JSON.
This guide explains the moving parts you will encounter, why they exist the way they do, and how to design a robust, compliant, and maintainable integration. It focuses on practical engineering concerns: authentication patterns, reference architectures, standards like FHIR R4, how Spine and the Spine Secure Proxy fit in, and what you need for onboarding and assurance. Along the way you’ll see strategies to avoid brittle builds, and how to ship features that are fast, safe and production-ready within NHS constraints.
Good NHS API integrations are opinionated: they lean into FHIR where appropriate, respect rate-limits, treat identities differently for citizens and staff, and model clinical risk from the outset. If you absorb nothing else from this article, hang on to that. Everything else flows from it.
When people say “NHS APIs”, they mean a family of services with different histories, technologies and access routes. Some APIs are open over the public internet, some sit behind the Health and Social Care Network (HSCN), and others are brokered by Spine components such as the Spine Secure Proxy (SSP). Most modern clinical APIs are FHIR-based; some legacy interfaces still exist in HL7 V3, and a few are moving targets as programmes uplift to FHIR R4.
At the core of citizen identity is NHS login, which uses OpenID Connect (OIDC) on top of OAuth 2.0. NHS login supports multiple identity proofing levels (commonly referred to as P0, P5 and P9), exposed to relying parties via Vectors of Trust; you request and evaluate the vector that aligns with the sensitivity of your user journeys. For example, booking a routine appointment might only require medium proofing, while viewing a full GP record demands high proofing.
For staff identity, NHS Care Identity Service 2 (CIS2) also uses OIDC and provides standard scopes and claims for user identity, role selection and national RBAC access. CIS2 enables modern authenticators beyond smartcards and is the route to staff-facing national services. Your application consumes CIS2 tokens and typically combines them with local authorisation policy to grant least-privilege access to clinical features.
If your use case requires data exchange rather than a live REST call, you’ll encounter MESH (Message Exchange for Social Care and Health). MESH runs on Spine infrastructure and is used for reliable, secure transfer of structured messages and larger files between organisations—think results flows, bulk operations, or nightly jobs where a queue-based approach is pragmatic. From a developer standpoint, you integrate with an API or a client, exchange payloads in agreed formats, and operate mailboxes.
On the data side, FHIR UK Core (R4) offers the baseline clinical models across the UK; national APIs and implementation guides then constrain those models for specific workflows such as GP Connect Access Record, Pathology, or National Record Locator (NRL). As a consumer, you should code to the profile(s) declared by the API—not just the raw international FHIR resource—so your validation, search parameters and extensions match what providers actually produce.
GP Connect remains a primary route into GP records and appointments. It is brokered via the Spine Secure Proxy, and consumers typically must be on HSCN for certain capabilities. Many GP Connect capabilities use FHIR STU3 today (with programme guidance about future uplifts), whereas newer initiatives align with R4 and UK Core. That mix matters when you design resource mappers and validation.
In practice, your product will use a subset of these. A citizen-facing mobile app might use NHS login and PDS to confirm patient identity, call GP Connect to fetch a medication summary, and rely on NRL for specific document retrieval. A staff dashboard might use CIS2, PDS, and MESH to orchestrate inter-trust referrals overnight.
The identity split is fundamental: treat citizens and staff differently. For citizens, implement OIDC against NHS login and request an appropriate Vector of Trust. Design for “step-up” flows: users who arrive at P5 can trigger an on-demand identity upgrade to P9 before you expose sensitive features like historic results or coded entries. Handle claims carefully: store just enough to manage sessions and audit; don’t persist unnecessary identity data.
For staff, integrate with CIS2 as your OpenID Provider. You’ll receive claims for user identifiers and, optionally, a role selection step that resolves to a specific organisational context and role. Map these into your application’s authorisation model—ideally policy-as-code—to enforce granular access. Remember that staff tokens represent professional actions; combine them with your business rules to restrict dangerous paths such as bulk downloads or mass updates on clinical data.
Transport and perimeter controls vary by API. Some endpoints are internet-accessible via the NHS API Platform with API-key or OAuth patterns; others require HSCN and Spine brokering. The Spine Secure Proxy sits in front of GP Connect providers and is responsible for trust brokering, auditing, and access control. If you are consuming GP Connect, plan for SDS lookups (ASID and endpoint discovery), SSP headers, and environment-specific certificates as part of your connectivity code.
Rate limiting is enforced at the gateway and sometimes at the programme level. Your client can be throttled based on environment, API and authentication mode. In design terms, you should assume burst protection (“spike arrest”) and quotas, incorporate retry-after handling, and build idempotency into your write operations. Don’t treat 429 responses as edge cases; they are an everyday operational reality under load.
Finally, design for multi-tenant isolation even if you don’t plan to go multi-tenant on day one. That means scoping caches by token/organisation, scoping audit logs, and ensuring any local persistence (e.g., of FHIR resources for offline UI) is partitioned. It’s tempting to ship a monolith with a single global in-memory cache; it’s harder to pass assurance and scaling tests later if you do.
Compliance in the NHS context is practical engineering. It’s about choosing a lawful basis, modelling clinical risks, implementing controls, and proving you did so. Start by determining your lawful basis under Article 6 and a valid condition for special category data under Article 9 of UK GDPR. If your product touches confidential patient information, document precisely how you limit, protect and audit that processing. You will almost certainly complete the Data Security and Protection Toolkit (DSPT) as part of onboarding or commissioning.
Clinical safety is a software development activity, not a paper exercise. DCB0129 applies to manufacturers (you); DCB0160 applies to deploying organisations (your customers). You should maintain a Clinical Safety Case Report and a living hazard log that tie risks to concrete mitigations in code, configuration and operations. For example, if your UI lets staff filter records, show the currently selected organisational context and role from CIS2 prominently to reduce wrong-patient or wrong-context errors.
Understand and implement the National Data Opt-out where applicable. The policy applies to uses beyond individual care (for example, planning and research). Many organisations satisfy batch checks using the MESH-based “Check for National Data Opt-outs” service: submit NHS numbers and receive a filtered list for downstream processing. Your product should make it easy for controllers to apply opt-outs when appropriate and to prove they have done so.
Meet the standards your API partners expect in data content. For clinical coding, that usually means SNOMED CT for problems and observations and dm+d for medications. If you transform or persist coded data, keep the original code system and code; never down-code to free text. For organisational identifiers, use ODS codes and keep them current through automated syncs rather than manual spreadsheets. If you rely on reference data from TRUD, ensure licensing (and any downstream sublicensing) is respected and that you have a process to apply regular updates.
Your privacy design should be defensive by default. Minimise scopes and claims requested from identity providers. Prefer on-demand retrieval to bulk replication unless a programme requires local storage (for example, for offline ambulance use cases). If you must cache, define strict TTLs by resource type and data sensitivity, encrypt at rest, and tag all records with provenance so you can purge cleanly on a data subject request.
A robust architecture treats national services as external, versioned, and rate-limited dependencies. The simplest stable pattern for many products is:
Within that pattern, use “pure” adapters per API so capabilities can evolve independently. Your GP Connect consumer adapter can handle SDS lookups, SSP headers and capability statement checks; your PDS adapter can own search rules and automatic NHS number verification; your NRL adapter can resolve pointers and orchestrate document retrieval; your MESH adapter can implement mailbox polling and error recovery. This separation prevents your UI or business logic from becoming a maze of programme-specific conditionals.
For GP Connect specifically, plan for provider diversity. Capability statements may differ between principal GP systems and across versions. Rather than hard-coding expectations, fetch and cache each provider’s capability statement and interrogate it before calling interactions. Where a capability is missing, degrade gracefully in your UI: tell users what is available from the patient’s registered practice today and what is not.
For messaging use cases on MESH, treat mailbox operations like you would any durable queue: implement poison-message handling, dead-letter workflows, and replay. Encrypt payloads at source before submission if you are dealing with especially sensitive content, even though MESH encrypts in transit.
Onboarding is a programme-driven process. The NHS API and integration catalogue signals what access mode and onboarding you need: some APIs are open internet with simple registration, others require HSCN, and some involve formal assurance (for example, Common Assurance Process for certain legacy HL7 V3 services). Expect to provide evidence of DSPT completion and clinical safety artefacts, and to pass scenario-based testing.
Performance is part of assurance. The API platform enforces rate limits, sometimes with policies such as SpikeArrest in Apigee. Your non-functional testing should simulate realistic traffic patterns, including short-duration bursts, and confirm your retry logic respects Retry-After. You should also measure end-to-end latency as users experience it: identity flows, token exchange, FHIR retrieval, rendering, and any background prefetch or cache warming you do.
Plan your test data story early. National sandboxes vary in fidelity; some have rich fixtures, others rely on mock servers or minimal example patients. Create safe, synthetic datasets for your own testing and use feature flags to avoid “test logic” leaking into production. Where a programme provides a demonstrator (for example, GP Connect), use it to validate your understanding of request semantics and error contracts before tightening timeouts against real systems.
For live operations, define runbooks for identity outages, SSP issues, and MESH backlogs. When CIS2 or NHS login is degraded, your application should degrade sensibly: clearly communicate which functions are unavailable and allow users to complete tasks that do not require fresh tokens. For MESH backlogs, back-pressure your own ingestion and surface status to downstream systems to avoid cascading failures. Keep a playbook for ODS anomalies and organisational changes; ODS codes and endpoints change over time and are a common source of subtle production bugs.
Finally, treat documentation as part of your product. Developers integrating your platform need to know which proofing levels you request, how you cache, how you apply opt-outs, and what audit trails exist. Good documentation reduces onboarding friction with commissioners and speeds security review. It also pays dividends when you uplift to new profiles (for example, FHIR R4 UK Core) or add new capabilities like NRL pointers for mental health crisis plans.
Is your team looking for help with NHS API integration? Click the button below.
Get in touch