The GP Connect capability statement for one practice's clinical system lists different sections than the practice down the road running an older version of the same software. Build against one and assume it is the standard, and the second practice breaks your integration in its first week live.

That is what most explainers of 'NHS API integration' miss. There is not one NHS API - there is a scatter of services built at different times, on different transport rules, each with its own idea of what a patient identity even is. Getting this right is less about REST and JSON, more about identity, safety and information governance, with the code as the easy part underneath.

If you take one thing from this guide, take this. Good NHS integrations lean into FHIR where it is the standard, respect rate limits as a fact of life rather than an edge case, treat citizen and staff identity as separate problems, and model clinical risk from day one, not at the end. Everything below follows from that.

It is several APIs, brokered differently

Some services sit on the open internet. Others sit behind the Health and Social Care Network (HSCN). Others are brokered through Spine components like the Spine Secure Proxy (SSP), which handles trust, auditing and access control in front of GP Connect whether you have planned for it or not.

Most current clinical APIs are FHIR-based. Some legacy interfaces are still HL7 V3. Some programmes are mid-uplift to FHIR R4 right now, so the version you build against today may not be the version live in eighteen months.

Citizen identity runs through NHS login, which uses OpenID Connect on top of OAuth 2.0 with proofing levels (commonly P0, P5, P9) exposed as Vectors of Trust; a routine booking might need only medium proofing, a full GP record needs high proofing. Staff identity runs through CIS2, also OIDC, resolving to national RBAC access.

FHIR UK Core (R4) is the baseline clinical model, but national APIs constrain it further per workflow. Code to the profile the API declares, not the raw international resource, or your validation and search parameters will not match what the provider produces.

Where these typically sit in a real build:

Most products need a handful of these, not all of them. A citizen app might use NHS login and PDS to confirm identity, GP Connect for a medication summary, NRL for a specific document. A staff dashboard might lean on CIS2, PDS and MESH for overnight inter-trust referrals. Knowing which subset you need is most of the design work.

Identity is the part that fails

Treat citizens and staff as different problems, because the standards do.

For citizens, design for step-up. A user arriving at P5 should be able to trigger an on-demand upgrade to P9 before you show them historic results or coded entries, rather than gating the whole journey behind the highest proofing level from the start. Store only what you need for session and audit; identity data you do not need to keep is a liability sitting in your database, not an asset.

For staff, a CIS2 token proves who someone is and which role they picked. It says nothing about what your application should let them do with that role. Writing that authorisation logic as policy your team can read and test, rather than burying it in conditionals, is what stops a locum with the wrong role selection from bulk-exporting a caseload they should not see.

Transport varies by API and this catches teams out consistently. Some endpoints are internet-facing with API keys or OAuth. GP Connect requires HSCN and SSP brokering, which means SDS lookups, ASID and endpoint discovery, and environment-specific certificates as part of your connectivity code, not an afterthought before go-live.

Rate limiting is constant, not an edge case. Assume burst protection and quotas from day one, and build retry-after handling and idempotent writes into the design. Design for multi-tenant isolation even if you are not planning to go multi-tenant yet, and scope caches and audit logs by organisation from the start.

Compliance is engineering, not paperwork at the end

Start with your lawful basis under UK GDPR and, if you touch confidential patient information, document precisely how you limit, protect and audit that processing; you will almost certainly need a completed Data Security and Protection Toolkit (DSPT) as part of onboarding. DCB0129 applies to you as the manufacturer, DCB0160 to whoever deploys your product, and both want a Clinical Safety Case Report and a hazard log tying real risks to real mitigations in your code, not a policy statement bolted on before submission.

A hazard log produced during design constrains the architecture and changes what gets built. One written at the end, after the decisions it should have shaped are already made, is thin by construction.

National Data Opt-out needs the same treatment wherever your processing goes beyond individual care into planning or research. Most organisations run this as a MESH batch check: submit NHS numbers, get back a filtered list. Build it into your data pipeline from the start, rather than retrofitting an opt-out check into a system that was never designed to filter.

Coded data should stay coded: SNOMED CT for problems and observations, dm+d for medications, ODS codes for organisations, kept current through automated syncs rather than spreadsheets. Down-coding to free text to simplify your own schema is a decision you will regret the first time someone needs to trace a record back to its source.

Where builds break

Multi-tenancy retrofitted is close to a rewrite. Tenant isolation enforced at the database level, so Practice A can never see Practice B's patients even if someone writes a bad query at two in the morning, is a day-one decision or a very expensive later one.

GP Connect capability statements differ between principal GP systems and across versions of the same system. Fetch and cache each provider's statement, check it before calling an interaction, and degrade the UI when a capability is not there for that patient's registered practice. Treating 'what GP Connect can do' as a fixed list is the single most common reason integrations work in the demo and fail on the second practice.

The architecture that survives is adapters. One adapter per API: a GP Connect consumer owning SDS lookups, SSP headers and capability checks; a PDS adapter owning search rules and NHS number verification; an NRL adapter resolving pointers; a MESH adapter handling mailbox polling and error recovery. The alternative is business logic riddled with programme-specific if-statements.

What decides whether it survives production

Keep environment credentials, API keys and rate limits as configuration, not code, across sandbox, integration and production, and separate application-restricted calls from user-restricted OIDC flows, with JWKS rotation so a key rollover does not take you down. Wrap national API calls in circuit breakers with exponential backoff and jitter on 429s and 5xxs, log every outbound call with a correlation ID (never full patient payloads by default), and treat MESH mailboxes like any durable queue, with poison-message and dead-letter handling.

Onboarding is a programme, not a form

Access mode drives your timeline: simple internet-facing registration is fast, HSCN access and formal assurance are not, and no amount of good engineering shortens a queue that is calendar-bound rather than effort-bound. Expect DSPT completion and clinical safety artefacts as standard, and scenario-based testing before go-live. Build your evidence pack as you go, not the week before submission: the certificate, the safety case, the DPIA, a named Clinical Safety Officer.

Build your own synthetic test data early rather than waiting for a fixture-rich sandbox that may not arrive. Once live, keep runbooks for identity outages, SSP issues and MESH backlogs, degrade sensibly, and keep ODS syncs automated rather than manual.

The line that makes you a medical device

Transcribing what a clinician said is not a medical device function. The moment your tool interprets a specific patient's data to inform a diagnosis or treatment decision, it is one, legally, and someone is accountable for that claim. This line gets crossed by accident more often than by design, a feature that starts as 'summarise the results' can drift into 'flag which results need attention' without anyone deciding that on purpose.

A short checklist before you call it done

• Identity. NHS login and/or CIS2 designed with step-up and role-selection flows matching your real user journeys, with minimal scopes requested.
• Data access. PDS FHIR for search and verification, combined with GP Connect or NRL for clinical content. Source system, profile and version persisted alongside anything cached.
• Governance. DSPT complete, DCB0129 artefacts maintained as living documents, National Data Opt-out implemented wherever it applies.
• Engineering. One adapter per API, rate limits and transient errors assumed by design, responses validated against the declared FHIR profile, environment config externalised.
• Onboarding. Access mode confirmed against the NHS API and Integrations Catalogue, assurance timeline budgeted as calendar time, not effort.