Written by Technical Team | Last updated 17.10.2025 | 12 minute read
GP Connect Access Record: Structured is a national capability that lets authorised systems retrieve coded, machine-readable slices of a patient’s general practice record from the GP system where they’re registered. Unlike a free-text print-out or an HTML view, the payloads returned here are FHIR resources that you can parse, store, reconcile and reuse in downstream workflows. In other words, it’s designed for safe, standards-based data ingestion rather than simple on-screen viewing. At a high level, consumer systems make RESTful calls that are brokered through NHS Spine to the relevant GP principal system, and receive resources including:
The “structured” aspect matters. Coded entries preserve clinical semantics, enable deduplication, and support decision support and analytics. If you’re building an urgent care, virtual ward or medicines reconciliation workflow, the difference between a page of prose and a bundle of codified records is profound: you can merge, alert and transform with confidence. The API gives you a consistent interface across GP suppliers, so you don’t have to hand-craft integrations for each. Calls are intermediated by the Spine Secure Proxy (SSP), which standardises transport, security and audit concerns.
In practice, the capability sits alongside related GP Connect products. “Access Record: HTML” renders a clinician-friendly read-only summary, while “Access Record: Structured” is the machine-readable sibling aimed at system-to-system exchange. For patient-facing scenarios there are dedicated specifications which follow the same family of FHIR profiles but adapt guidance for citizen access. Understanding where each fits will help you sequence features sensibly and pass assurance efficiently.
Behind the scenes, there’s a lot of national plumbing doing the heavy lifting. The SSP brokers requests, authenticates clients, enforces information governance, and provides centralised audit and throttling. Provider systems, for their part, need only accept inbound calls from SSP and validate the expected headers and token claims; consumers need to present correctly formed JWTs and use the Spine routing model. This separation is what lets a single consumer integrate once and reach thousands of practices reliably.
Before you write a line of code, take time to map the assurance landscape. You’ll need a legitimate use case, an onboarding route with NHS England, and appropriate organisational approvals for handling patient data. On the technical side, you will need SDS/ASIDs, access to the Spine Secure Proxy, conformant TLS mutual authentication, and the ability to mint and sign a JSON Web Token (JWT) containing the mandated clinical provenance and audit claims. GP Connect uses STU3 for Access Record: Structured, and the SSP expects specific request headers that bind your interaction to both the target endpoint and the authorised address space.
At transport level, the SSP operates as a forward proxy. Consumer systems send their FHIR requests to SSP and include a small, well-defined set of HTTP headers. These signal the caller’s ASID, the target GP system’s ASID, and the specific interaction you’re invoking. Provider systems are expected to validate that the Ssp-To ASID corresponds to their allocated address space, that the Ssp-InteractionID matches the endpoint, and that an authorisation bearer token is present and well-formed. This pattern centralises access control while keeping on-premise GP systems comparatively simple.
For authorisation and clinical audit, GP Connect uses a JWT carried as an OAuth2 Bearer token. The token encapsulates who is asking, on whose behalf, for what purpose and from which organisation and device. It is short-lived and must be signed with an approved key pair. The payload includes references to FHIR resources for the requesting practitioner and organisation, plus claims that explain the reason for request and the legal basis—details that support cross-organisational provenance and audit trails. While the exact field list is set out in the specification, design your token service to be flexible and to log a verifiable chain of custody for each call.
To make onboarding painless, assemble your evidence early: information governance paperwork, data flow diagrams, a security design describing how you protect keys and tokens, and your end-to-end logging approach. Provision your non-production ASIDs and certificates to exercise against Opentest (the “orange” environment) and use the demonstrator tools and Swagger UI there to iterate quickly while you’re waiting on supplier endpoints. Having a working Postman collection and example responses will accelerate conversations with assurance and clinical safety teams.
Checklist to get started confidently:
From a developer’s vantage point, the capability is a well-behaved FHIR STU3 surface with tight profiling. You query by a patient identifier and retrieve logically grouped, clinically meaningful bundles whose entries are adorned with code systems and extensions agreed nationally. What you get back is not just raw codes; it’s UK-specific profiling with consistent value set binding and cardinalities tuned for primary care. Treat the profiles as executable contracts: you can validate instances against them as part of your CI pipeline to catch mapping drift early.
The most frequently used resources will likely be MedicationStatement (current and past medicines), AllergyIntolerance (with criticality and reaction detail), and Condition (diagnoses and long-term problems). Immunization, Observation and DiagnosticReport round out the picture—immunisation schedules, vital signs and pathology results. In many record journeys the GP system will return a “structured record view” that is essentially a curated set of these resources for the patient, and you’ll need to reconcile them against data you already hold. Make sure to preserve identifiers (.identifier.value) and linkages (.basedOn, derivedFrom) so you can detect duplicates or updates over time.
Although FHIR is consistently shaped, there are nuances worth planning for. Observations may encapsulate single results or panels; diagnostic reports may reference observations rather than duplicating them; medications may appear as both authoritative prescriptions and inferred statements. A robust ingestion pipeline will normalise common patterns (for example, extracting numerics and units into a canonical store) without losing the source artefacts. It’s also a good idea to design an “as-received” storage layer—often simply JSON blobs keyed by resource type and ID—alongside your domain tables to support forensic audit and future reprocessing when profiles evolve.
Terminology is another consideration. Expect SNOMED CT codes throughout, with occasional legacy coding in historical entries. Unless you’re building a clinical system that needs full terminology services, a pragmatic approach is to store the code and display string verbatim while maintaining a translation table for the handful of concepts you render or alert on. If you do wire in a terminology server, cache aggressively and version your value sets; national code systems update regularly and you don’t want a midnight change to ripple into your rendering logic unnoticed.
Finally, model consent and clinical safety in your data design. Even when you receive a bundle lawfully, that does not automatically mean all downstream uses are legitimate. Tag every resource with the provenance from the JWT (requesting organisation, practitioner, reason for request) and the legal basis you asserted at call time. It’s not just good governance—those tags help you answer future IG queries quickly and demonstrate traceability during assurance.
It helps to picture the end-to-end control plane. Your consumer application (cloud or on-premises) holds client certificates for Spine and knows how to talk to the SSP over mTLS. When you need a patient’s structured information, your backend first mints a short-lived JWT bearing the clinical provenance claims for the user and organisation, then issues a FHIR request to the SSP with the correct headers and the token in the Authorization: Bearer header. SSP validates the connection, checks authorisation and routing, and forwards the request to the registered GP system. The provider validates the SSP, validates the headers and token, authorises the request according to local policies, and returns the FHIR bundle back through SSP to you. Each hop is audited.
There are a few popular integration patterns. For urgent care and pharmacy use, a real-time retrieval on demand often makes sense: you pull a fresh structured record at the point of care and cache lightly for session continuity. For virtual wards or longitudinal shared care, a scheduled synchronisation works—retrieve deltas or the full view on a cadence, reconcile into your longitudinal store, and expose a normalised graph to your application. Whichever you choose, make sure the user interface conveys record freshness clearly and logs the provenance of the view shown.
Development and test environments deserve deliberate design. Use Opentest to validate the basics: mTLS, SSP headers, JWT construction, and the shape of responses against test patients seeded across PDS and the GP Connect reference implementations. The publicly available demonstrator Swagger can be a fast way to trial calls and inspect payloads before you wire up your own client. When you move to supplier test sandboxes, expect idiosyncrasies—some will strictly validate tokens and headers, others will be more lax. Treat the strictest as the baseline and automate conformance checks so you don’t regress.
On the testing front, think beyond “does the API return 200 OK?”. For unit tests, use local JSON fixtures that represent real-world complexity—multi-reaction allergies, medications with discontinuation reasons, observations with interpretation flags, historical immunisations. For contract tests, integrate a FHIR validator step into CI, pointing at the GP Connect profiles. For integration and E2E tests, simulate full journeys including JWT minting and SSP headers, and assert on your audit trail as well as on the FHIR content you store. If you operate in multiple clouds or regions, include chaos and latency tests to see how your timeouts and retries behave under strain.
Observability and audit are first-class concerns in production. Log spine trace IDs and map them to your internal request IDs. Index JWT fields you might need for investigations (requesting organisation, practitioner, reason for request) but avoid logging token bodies wholesale. Ship SSP-level metrics (success rates, response times, throttling) to your dashboard and correlate with your application metrics so you can tell quickly whether an outage is local, supplier-specific or national. At the UI layer, give clinicians clear error states with actionable advice, while keeping raw error detail in the logs for your team.
A practical approach to environments and testing:
Once you’re through assurance and exchanging data, attention turns to making the experience fast, dependable and safe at scale. Although the SSP is designed to throttle and protect GP systems, you remain responsible for being a good citizen. That begins with idempotent clients, conservative retry policies, and back-off strategies that respect provider capacity. Batch what you can within the confines of the API’s interaction models, and prefer incremental retrieval patterns over repeated full fetches when users open the same patient within a short window.
Caching is a nuanced topic. For point-of-care scenarios, brief session caching (say, a few minutes) prevents unnecessary re-fetches if a clinician navigates between tabs or returns to a patient’s record during the same encounter. For background synchronisation, be explicit about your refresh policy and let users see when data was last pulled from the GP system. Never silently show stale data as if it were live; the UI should surface “last updated” timestamps prominently and provide a one-click refresh where appropriate. Hydrate caches only with fully validated bundles to avoid polluting downstream consumers with malformed content.
Error handling deserves thoughtful design. Expect transient network errors, token issues and supplier maintenance windows. Distinguish between authn/authz failures (which the user cannot fix), clinical preconditions (for example, a patient not registered at the target practice), and transient transport errors (which a retry may resolve). Your client should parse and categorise error responses and present clear, user-friendly messages alongside audit-useful detail hidden from the UI. Resist the temptation to blanket-retry on every failure; you’ll do more harm than good during national incidents.
From a clinical safety perspective, the main risk is misinterpretation rather than raw availability. Medication statements represent the GP-recorded view at a point in time; they may not reflect dispensing or adherence. Allergies and conditions may be historical or inactive. Build interfaces that make status explicit (“active”, “entered in error”, “resolved”), highlight missing critical fields (for example, unknown reaction details), and let clinicians click through to source details when needed. Where your product renders composite views (for instance, a consolidated medicines list), make it obvious which entries came from GP Connect and when.
Security hygiene continues after go-live. Keep JWT lifetimes short, implement key rotation, and monitor for clock skew that might invalidate tokens unexpectedly. Protect private keys with HSMs or managed key vaults. On the inbound side, validate all SSP headers strictly and reject requests that are out of policy. Plan for incident response: how you will revoke credentials quickly, what telemetry you need to determine blast radius, and how you will communicate with customers if a national dependency experiences an outage. The combination of robust controls and transparent comms builds trust with clinicians and patients alike.
Is your team looking for help with GP Connect integration? Click the button below.
Get in touch