Written by Technical Team | Last updated 15.08.2025 | 17 minute read
GP Connect is the national programme that opens up read and write access to general practice (GP) clinical systems in England through standardised FHIR APIs. It allows approved consumer systems—such as urgent and emergency care platforms, integrated care record portals, and patient-facing applications—to retrieve records, book appointments and, increasingly, exchange structured clinical data in a consistent way. Rather than implementing point-to-point integrations with every principal GP system, you integrate once with a national pattern that is mediated by the NHS Spine, giving you scale, governance and a common security model across thousands of practices.
The APIs you’ll encounter fall broadly into three families. Access Record: HTML provides a read-only, human-readable rendering of a patient’s GP record, returned as HTML sections you can embed in an EPR or portal. Access Record: Structured returns machine-readable, coded FHIR resources—such as allergies, medications and problems—that your application can process, reconcile and persist. Appointment Management exposes FHIR-based operations to discover free slots and book, amend or cancel appointments held in the GP system. Each capability is implemented consistently across principal GP suppliers and exposed through the same national gateway so that the authorisation model, headers and routing conventions are uniform for all consumers.
The NHS Spine does far more than act as a network hop. It provides the Spine Secure Proxy (SSP)—a forward proxy that terminates mutual TLS, brokers requests, enforces authorisation, logs and audits traffic and, crucially, isolates GP systems from direct internet exposure. Consumer systems never connect straight to a GP supplier endpoint; instead they present signed tokens and Spine-specific headers to the SSP, which validates, authorises and forwards the request to the appropriate GP system. This brokered pattern centralises security, gives NHS England a single place to apply policy and throttling, and simplifies supplier onboarding because each GP provider only needs to trust the Spine.
FHIR underpins all of this. Most GP Connect capabilities today use FHIR STU3, with GP Connect Access Record: HTML historically aligned to an earlier FHIR generation. While there is industry appetite for FHIR R4 uplift, the programme has communicated that timelines are not yet confirmed; production consumers should therefore target the current STU3-based specifications and plan any R4 migration as an evolution rather than a precondition for go-live.
Security is the first thing to get right, because everything else—reliability, performance, even user experience—depends on your ability to pass the SSP’s checks repeatedly and predictably. Think of the Spine Secure Proxy as a policy enforcement point. Your consumer presents: (a) a mutually authenticated TLS connection, and (b) a signed JSON Web Token (JWT) in the Authorization: Bearer header that asserts who you are and what you are asking to do. The SSP validates the client certificate, verifies the token signature against your registered public keys, inspects the claims (organisation/ASID, purpose, interaction, user context if present), and only then forwards the request to the provider system. The provider is configured to accept connections only from the SSP; even if someone discovers its hostname, direct connections are refused at the TLS handshake.
Routing and authorisation are tied to Spine Directory Service (SDS) entries and ASIDs (Accredited System IDs) that represent the systems you operate and the capabilities they are approved to consume. Your token should match an ASID that has been whitelisted for the specific GP Connect interactions you invoke. There is also an interaction ID for each operation, expressed in a standard header, that the SSP uses to drive authorisation and routing logic. In other words, the SSP checks: “Is this system (ASID) allowed to call this interaction (interaction ID) against that provider (ODS/ASID)?”—and it audits the outcome of that decision for later reporting.
At transport level, you will establish mutual TLS (mTLS) to the SSP endpoint using an approved client certificate. At message level, you sign and present a JWT asserting caller identity and request purpose. At application level, the FHIR request includes a consistent set of Spine headers, including Ssp-From, Ssp-To, Ssp-InteractionID and a correlation ID (often Ssp-TraceID) so that traffic can be traced end-to-end. This layered approach lets the platform enforce controls even if one element is misconfigured: for example, a valid mTLS session without the right interaction ID still yields a clean, auditable rejection.
You also need to plan user-to-system identity. Many GP Connect calls are made “as a system” for direct care purposes and scoped by data-sharing agreements between organisations, recorded centrally and enforced by the SSP. Where user context is required (for example, in workflows that must carry an authenticated clinical user identity), the token will include additional attributes to represent the user and role. Over time, more capability has been made available to patient-facing apps through specific APIs, but those follow their own accreditation route and security profile distinct from direct-care GP Connect traffic. Do not assume that a patient-facing token can be reused for a direct-care API; treat them as separate surface areas with different governance and consent checks.
Key security design checkpoints:
Once security is stable, the difference between a good and a great integration is how well you shape the FHIR requests to the realities of GP data, clinical safety expectations and the performance envelope of the SSP and provider systems.
Start with Access Record: HTML when your users primarily need a human-readable summary of the GP record that you can embed with minimal transformation. It is well-suited to urgent care and shared care record contexts, where clinicians want to see what the GP sees—medications, allergies, problems and recent encounters—without the complexity of merging data into your own models. You can request specific sections and date ranges so that you aren’t pulling unnecessary content, and because the response is HTML, the risk of semantic drift is reduced: you are displaying a supplier-rendered representation, not re-interpreting code systems yourself. The trade-off is that HTML is not machine-processible; you won’t be reconciling codes or running decision support over it. Many programmes use it as a stepping stone to structured data once the user value is proven.
When you need machine-readable content, move to Access Record: Structured. Here you’ll retrieve FHIR resources—AllergyIntolerance, MedicationStatement/MedicationRequest, Condition, Observation, Immunization, Procedure, Encounter and others—profiled to GP Connect requirements so you can automatically reconcile them into your system. Because this is STU3, there are profile nuances and extensions to observe; for example, how medication dosage and status are represented, or how problems versus past medical history are modelled in Condition. Plan your data model mapping explicitly and maintain a versioned translation layer so that supplier or GP Connect profile updates can be handled in one place.
For operational scheduling tasks, Appointment Management is a proven capability used by NHS 111, urgent care and other services. You can search for free slots, read current bookings, and book, amend or cancel appointments via a consistent set of FHIR resources and interactions. Core resources include Appointment, Schedule, Slot, Patient, Practitioner, Location and Organization. The data shape is familiar if you’ve used other FHIR scheduling APIs, but the GP Connect profiles and business rules are specific—particularly around slot types, booking reasons and the need to carry patient identifiers consistently. Build first-class appointment error handling: upstream availability changes constantly, and you will encounter race conditions where a slot visible a moment ago becomes unavailable when you submit the booking request. Your client must gracefully detect that scenario and immediately refresh availability.
Across all capabilities, design with pagination, filtering and incremental retrieval in mind. GP records can be extensive; asking for “everything” will inevitably produce large bundles and slow response times. Use date filters (for example, “all Observations in the last six months”) where supported, and plan to page through results. Think carefully about caching: many requests are read-heavy and tolerate short-lived caching of supplier metadata and SDS lookups, but you must never cache patient-level data in ways that contravene direct-care expectations or data minimisation principles. For write-like operations (such as booking) or where timeliness is safety-critical, avoid caches and always re-fetch the latest state from the provider before acting.
Error handling is a clinical safety feature. Implement exponential backoff with jitter for network and 5xx failures; surface clear, user-centred error messages for clinical users; and log correlation IDs so that support teams can trace a transaction across your platform, the SSP and the GP system. Never “retry blind” a booking that might already have succeeded upstream; use idempotency keys where the API provides them or immediately check the authoritative resource state after a failure response. Finally, remember that the SSP imposes throttling to protect provider systems; design your client with concurrency limits per provider and shape traffic over time to avoid breaching platform rules.
NHS Connect
GP Connect integrations that succeed in production tend to share a handful of architecture patterns. The first is a “thin client, smart edge”: keep the code that actually talks to the SSP small, repeatable and wrapped in testable adapters; push complexity like token signing, header stamping, request shaping and response normalisation into a dedicated gateway or SDK you own. This makes change safer—when a header requirement or profile version changes, you fix and re-deploy one module rather than grep-ing application code across multiple services.
The second is explicit environment separation. Treat INT, TEST and PROD as different worlds with their own ASIDs, client certificates, JWKS keys, SDS entries and routing. Bake those differences into configuration, not code; never allow a build to be repointed to another environment without a formal configuration change. This avoids the classic “it works in test” mystery caused by a token signed with the wrong key or an SDS entry pointing at a retired endpoint.
Your build pipeline should include schema and profile validation of every payload you send and receive. Use a FHIR validation step with the GP Connect profiles so that accidental regressions are caught before integration testing. For Structured data, run unit tests over your mappings: round-trip a representative bundle—medications with dose instructions, allergies with severities, mixed coded/text observations—through your transformation layer and assert lossless handling of codes, dates and statuses. Add contract tests for your client’s token/headers so that every change to the gateway preserves the exact Ssp-InteractionID and other mandatory values.
Testing against realistic data is non-negotiable. The NHS provides test environments and demonstrators for GP Connect; use them to exercise the full handshake, including mTLS, JWT signing and SSP header validation. Your test suite should simulate long GP histories, frequent medication changes and a variety of appointment slot types, and it should deliberately trigger SSP rejections—wrong interaction ID, missing Ssp-To, expired token—so that you can verify error mapping and operator guidance. There are public interactive specs for appointment APIs that help you understand the expected resource shapes and common flows; incorporate those examples into your team’s shared documentation to align engineering and clinical stakeholders.
Operational readiness is as much about observability as it is about reliability. At minimum, capture four classes of telemetry: (1) security events—certificate expiry windows, token signing errors, failed authorisations at the SSP; (2) Spine headers—log your Ssp-TraceID and any SSP-returned correlation value, so incidents can be traced across organisations; (3) FHIR-aware metrics—bundle sizes, resource types per request, pagination depth; and (4) provider-specific latencies—so you can spot when a single GP supplier region is degraded and adapt. In major incidents, the difference between minutes and hours is often whether you can hand a Spine support engineer the exact trace IDs for two failing examples and one successful control.
Finally, plan a service-level strategy for consumers and providers. Consumers: declare a maximum request rate per GP practice and enforce it in code. Providers: understand that you are responsible for your side of the SSP handshake and the authorisation rules you publish; changes to data-sharing agreements or interaction whitelists will have immediate, observable effects on consumers. Build communication pathways so that when authorisation rules change, your partner organisations get proactive notifications. The SSP will faithfully enforce your latest policy; your joint operational model must keep pace.
FHIR gives you a common syntax, but clinical semantics still need careful handling. GP Connect profiles constrain STU3 to reduce ambiguity, yet each GP system reflects decades of clinical practice, local configuration and migration history. That means you should avoid assuming that a given FHIR field always equates to a single concept in your application. For example, MedicationStatement often expresses what is believed to be taken rather than what has been prescribed—your reconciliation logic must consider MedicationRequest (prescriptions), MedicationStatement (taking), and sometimes List resources representing active problems or medications curated by the GP system. Build your UI and decision support to transparently communicate provenance and certainty—clinicians should be able to see whether a medication is active, repeat, last issued, discontinued or historical, and whether that status is derived or explicit.
The same caution applies to problems and diagnoses. A long-standing problem list may contain entries that were originally coded under another GP system and brought across during migration, or text entries that don’t map cleanly to coded conditions. GP Connect profiles aim to regularise this, but data lineage matters. Include Provenance where present, and allow clinicians to drill into source snippets or GP system identifiers so that they can trust and verify the context behind a condition or observation.
For Access Record: HTML, user experience is king. The attraction is fidelity: what you render reflects exactly what the GP system would show. But do not just iframe the content blindly. Provide clear section navigation, highlight allergies and active medications, and ensure the embedded views are responsive and accessible. If you implement date-range filters, expose them in the UI so users understand when they are looking at a “last six months” slice versus the entire record, and always display the retrieval timestamp prominently to address the common “how fresh is this?” question.
For Appointment Management, usability hinges on communicating availability volatility. Present a live view of free slots, but teach users—especially call handlers and front-desk staff—that availability can change while they are on the booking screen. When a booking attempt fails because the slot has just been taken, your UI should recover gracefully by refreshing the list and focusing the cursor where the user left off. Capture booking reasons and contact details consistently; if your workflow spans multiple organisations, carry organisation identifiers clearly so that downstream teams can route follow-ups without detective work.
Clinical safety requires thinking beyond happy paths. Partial data is common: a patient’s GP record may be sparse or heavily populated; sometimes allergies are recorded only as free text; sometimes historical immunisations are incomplete. Build safeguards that temper automation—e.g., only trigger medication alerts when you have sufficient structured data, and visibly flag “unknown” states rather than implying “none”. Every integration should be accompanied by a safety case that documents hazards (for example, stale record views leading to inappropriate decisions) and mitigations (timestamps, refresh prompts, and escalation routes to the GP practice when uncertain).
Because GP Connect is a national integration, you will inevitably operate in an environment where policy and specifications evolve. The safest posture is to treat your consumer as a long-lived citizen of the ecosystem, not a one-off integration. That means you version your own API surface, your mapping rules, your token claims and your client behaviour. When the programme revises guidance—for instance, to tighten security ciphers or clarify profile constraints—you update your client library once and roll it out across the estate with confidence. Keep a close watch on release notes and implementation guides; small clarifications (say, around supplier behaviour for a specific search parameter) can dramatically reduce edge-case support calls.
A perennial question is “When do we move to FHIR R4?” From a purely technical standpoint, R4 brings maturity and a long-term ruleset that many vendors prefer. From a delivery standpoint, the wisest approach is R4-ready designs sitting on STU3-conformant implementations today. Write your mapping code so that resource-level transformations are modular; minimise dependencies on STU3-specific quirks; isolate codesystem transforms; and avoid coupling to minor profile details that are likely to change in an R4 uplift. Monitor official communications about R4 timelines and scope; until there is a confirmed pathway, don’t gate valuable direct-care outcomes on a standard uplift that might be months away.
Governance also covers who is allowed to do what and under what lawful basis. GP Connect is designed for direct care; you must ensure your information governance (IG) posture, audit trails and user interfaces unambiguously reflect that purpose. Make it obvious to clinical users when they are viewing or acting under direct-care access rather than research or planning. If you are building both direct-care and patient-facing capabilities, treat them as separate lines of assurance, security and UX: different tokens, different onboarding, different governance checks—shared engineering where sensible, but never conflated in your access controls.
Finally, integration is never only technology. Build durable relationships with the GP suppliers whose systems you will call and with the NHS teams who own the SSP and GP Connect roadmap. Share telemetry and incident evidence using the same trace IDs you log in production; agree change windows for certificate rotations and SDS updates; and plan joint chaos drills—revoking a key in test, expiring a certificate, tightening a header rule—so both sides build muscle memory for the real thing. A national platform will always have moments of stress; the teams that practise together recover fastest.
Architecting a secure and efficient GP Connect integration is about composure under constraint. You inherit a strong security model—the SSP, mTLS, signed tokens, firm headers—and a clear set of FHIR profiles honed for general practice. Your task is to respect those constraints, build with discipline and observability, and shape user experiences that reflect the realities of clinical work: data that can be messy, availability that can be volatile, and decisions that must be safe.
Start with a rock-solid security foundation: deterministic token generation, immaculate Spine headers, environment-specific configuration and mTLS you can rotate with confidence. Layer on FHIR-centric engineering: validate profiles, map resources transparently and treat provenance as a first-class concept. Make performance a feature: paginate, filter, throttle and back off politely. And above all, invest in operational excellence: trace IDs in every log, alignment with provider teams, and runbooks that your 3 a.m. on-call can execute with a clear head.
Do those things, and you’ll find that GP Connect’s promise becomes real: one integration pattern, one security gateway, and access to the core of primary care at national scale—reliably, safely and with the confidence that comes from aligning with the Spine.
Is your team looking for help with GP Connect integration? Click the button below.
Get in touch