Written by Technical Team | Last updated 15.08.2025 | 13 minute read
Before you write a line of code, it pays to understand what “GP Connect” actually is and how it fits into NHS England’s broader Spine ecosystem. GP Connect is a suite of capabilities that expose general practice data and services through standardised APIs. At its core are FHIR-based REST endpoints (for things like reading a patient’s structured record and managing appointments) and a messaging pattern that uses MESH for asynchronous document exchange. The “plumbing” in the middle is the Spine Secure Proxy (SSP), which brokers and protects most traffic heading to GP systems. SSP centralises security and policy controls, provides auditing, and ensures consumer systems only reach providers they’re allowed to access. In other words, you rarely call a GP system directly; you talk via SSP, which understands who you are and whether you’re allowed to do what you’re asking.
On the FHIR side, GP Connect capabilities currently centre on access to the patient record in structured, machine-readable form and appointment management. “Structured” is important: rather than scraping HTML, you’re reading coded clinical data that can be safely imported, reconciled, and displayed. That allows richer user experiences—medicines lists that can be filtered and reconciled; coded allergies you can check for contraindications; problems and observations that can be trended. These APIs follow FHIR profiles and interaction patterns tailored for general practice systems, and they publish capability statements that tell you exactly what a given provider endpoint supports.
MESH, by contrast, is for when you need to deliver a payload reliably but not necessarily in real time. Think PDFs of discharge summaries, consultation notes, forms, or ITK3-structured documents that must arrive with legal certainty and operational resilience. It’s essentially a secure, audited, store-and-forward postal service for health and care organisations, with routing handled via mailboxes and workflow identifiers. In a typical GP Connect integration, you’ll combine synchronous FHIR calls for interactive flows at the point of care with MESH for background document flows that need assured delivery.
A final piece of the puzzle is identity. For user-facing flows—such as clinicians launching your app to view a patient’s GP record—you’re expected to use NHS CIS2 authentication. CIS2 provides strong, standards-based authentication for NHS staff, with options ranging from smartcards to platform authenticators. That identity in turn informs authorisation decisions at Spine and the GP systems, keeping data access tightly governed by real-world roles, locations, and data sharing agreements.
Onboarding to GP Connect is not just a technical exercise; it’s governed by information governance, assurance, and registration steps that ensure your solution is safe and compliant. At organisation level, make sure the consuming organisation(s) for your solution have ODS codes, that your intended use case is covered by appropriate data sharing arrangements, and that you understand the patient access model you’re implementing. For example, in a point-of-care scenario in community or urgent care, staff will authenticate interactively via CIS2 and your system will act on their behalf; in a system-to-system scenario, you’ll still need to satisfy legal bases for processing and ensure robust access controls.
Identity underpins nearly everything you do. For user-restricted APIs (the majority of live clinical use), register your application with CIS2 and the NHS API platform, generate a key pair, and publish your public key material as required. This enables modern OpenID Connect-based flows and token issuance. In your application, plan for the full authn/authz handshake: launch context, user authentication, token acquisition, token exchange as needed, and propagation of user attributes required by downstream services. Treat identity as a first-class feature in your architecture and UX—it will influence the shape of your session management, error handling, and audit trails.
Registration with Spine services is another essential track. GP Connect endpoints and identities are discoverable through the Spine Directory Service (SDS), which maintains details such as ASIDs (Accredited System IDs) and endpoint addresses. You’ll need those directory records in place for consumers and providers so that SSP can route requests correctly. If you’re building a provider, you must ensure your endpoint is correctly published and associated with the relevant GP practice(s); if you’re building a consumer, your software and the organisations who deploy it need to be recorded so that your requests are recognised and allowed.
For document exchange, you’ll want to apply for a MESH mailbox (or ensure the relevant mailbox already exists) and complete the certificate setup. Each mailbox has credentials and, for the API channel, X.509 material you own and manage. If your use case is closely tied to a specific GP supplier platform, coordinate with them early: many practices’ mailboxes are managed by their clinical system supplier, and the workflow names you plan to use must be supported on both ends. A short discovery call with the local ICB or practice IT can save days of email ping-pong later.
Finally, understand the NHS test environments and assurance gates. You can expect to work in an integration environment before progressing to assurance and production. Plan test data, test accounts, and the end-to-end evidence you’ll need to show: conformance to FHIR profiles, correct SSP headers and routing, CIS2 user journeys, audit logging, error handling, and performance under realistic loads. Treat these as acceptance criteria from day one, not a box-ticking exercise at the end.
Practical checklist to assemble before sprint 1:
When you start engineering the FHIR integration, design with the SSP in mind. SSP is a forward HTTP proxy that expects specific headers to identify you, the intended interaction, and routing details. Your client calls an SSP endpoint rather than the provider directly, supplying interaction IDs that correspond to the GP Connect API operation you’re invoking and metadata that tells SSP where to send the call and how to audit it. Getting those headers right is table stakes; encode them centrally in your HTTP client so every request is consistent, logged, and testable. It’s also good practice to treat those headers as part of your contract tests, asserting their presence for each API call in CI.
Next, ground your client in FHIR reality. Fetch and cache the provider’s capability statement to understand which resources, interactions, and profiles are supported. Although GP Connect narrows FHIR’s permissiveness with specific profiles, you still benefit from FHIR’s self-describing nature. Use the capability statement to configure optional features dynamically, drive fallbacks (for example, if a provider does not support a bulk section you’d hoped to call), and enrich your telemetry with explicit model versions. Many teams miss the value of this step; embracing capability statements upfront reduces brittle assumptions and helps your app degrade gracefully across the heterogeneity of GP estates.
Payload design and validation deserve special attention. Treat FHIR profiles as code: generate models from the published profiles where you can, enforce required fields and value sets in your domain layer, and validate incoming data with both schema and business rules. The most robust implementations pair automatic validation (e.g. JSON schema or profile-aware validation libraries) with pragmatic guardrails in code—range checks for dates, normalisation of coding systems, and safe handling of partial or absent data. Remember that clinical data often carries caveats and historical quirks; your UI must articulate uncertainty, display provenance where available, and avoid implying completeness when sections are absent or redacted.
Finally, engineer for privacy by design. The safest GP Connect implementations request the minimum data required for the task, filter it immediately to what’s relevant for the user’s current action, and avoid storing content unless absolutely necessary. If you do cache data for performance or offline resilience, time-limit it aggressively and encrypt it at rest with strict key management. Your audit trail should link each retrieval to a user, patient, purpose, and outcome, with enough metadata to support investigations. When in doubt, make the conservative choice—clinicians trust systems that are clear about what they fetch and why.
If FHIR is your interactive conversation with GP systems, MESH is your guaranteed delivery courier. To get started, secure a MESH mailbox and configure the MESH API or client with your mailbox ID, credentials, and certificates. In your design, think in workflows: each document type and business process (for example, sending a consultation summary to a patient’s registered practice) maps to a MESH workflow identifier that both sides recognise. The mailbox model then becomes a routing abstraction: you post a message with a specified workflow and recipient, and MESH handles the delivery, retries, and receipts. This is exactly the kind of boring, reliable infrastructure you want for medico-legal documents.
The mechanics are straightforward but worth engineering well. A MESH message consists of your payload (often a PDF or ITK3-wrapped content), optional control file metadata, and headers that identify the workflow and recipient. You’ll poll for acknowledgements and, where appropriate, track E2E delivery states so your operational dashboards can surface failures proactively. Because MESH is asynchronous, design your user experience accordingly: show clear “sent” vs “delivered” status, provide a resilient outbox, and ensure your retry logic is idempotent. When you’re exchanging clinical documents, consider pairing the MESH flow with an in-product audit note so clinical teams can see when and what was sent without leaving your application.
It’s common to combine MESH and FHIR in a single solution. For instance, your clinician may view structured data via FHIR to drive clinical decision-making, while the action of closing a case triggers a MESH dispatch of a formal summary back to the GP practice. Keep those paths separated in code and observability: one pipeline tuned for low-latency, user-interactive calls; another for durable, retriable deliveries with reconciliation and human-readable receipts.
The fastest projects are the ones that treat assurance as a parallel stream from day one. Start by building a thin “hello Spine” path: a working CIS2 login from a test user, a token your backend can validate, a correctly formed call through SSP to a test provider endpoint, and a single successful retrieval of a benign resource (for example, a capability statement). The goal is not feature richness but proving your end-to-end path and the observability around it. Once this is stable in your integration environment, layer on the GP Connect capabilities you actually need—structured record views, appointments, or specific document flows.
Testing clinical integrations benefits from a mindset shift: think scenarios, not just unit tests. Create realistic patient narratives and datasets—patients with multiple surnames, historic allergies, old problems in remission, repeat medications with synchronised review dates, and edge cases like ceased medicines. Validate that your UI renders these faithfully: no truncation of important codes, clear handling of absent sections, and explicit text where data is not shared. For appointment flows, simulate race conditions, cancellations, and slot unavailability. For MESH, test large payloads, duplicate sends, and mis-routed workflow IDs to harden your error handling and ops processes.
Performance engineering matters because clinicians are unforgiving of slow systems. Measure cold-start time for your FHIR calls through SSP, optimise connection reuse, and leverage HTTP-level caching where permitted. Because SSP is a shared service enforcing policy and logging, your latency envelope will include its processing overhead—measure it, don’t guess. On the UI side, stream sections as they arrive and make progress visible; a partial medicines list is better than a spinner, as long as you clearly label it. For MESH, treat the outbox as a first-class component with telemetry on queue depth, retry rates, and time-to-delivery so operational teams can see and act before clinicians notice a problem.
Security and privacy guardrails should be codified as automated checks. Block deployments if required SSP headers are missing from any request in your contract tests. Fail builds if a change reduces token validation strictness or broadens scopes. Run static analysis for secrets and keys, review logs for sensitive data leakage, and practise key rotation in non-production. In production, make audit trails queryable by patient, user, time, and action; and define a playbook for data subject requests and incident response. Good governance is not a PDF on a shared drive—it’s living code, alerts, and runbooks your team exercises.
Operational readiness essentials for launch include:
If you synthesise the moving parts, a clear path emerges. Stand up your identity flow with CIS2 and register your application on the NHS platform early—everything else depends on it. In parallel, build a simple FHIR client that can call through SSP to fetch a provider’s capability statement, then expand to the specific GP Connect endpoints you need. Design your data handling to be profile-aware and privacy-first, validating and filtering aggressively before you render anything. For document exchange needs, configure your MESH mailbox and workflows, and implement an operationally rich outbox with retries and receipts. Throughout, treat assurance not as an afterthought but as your definition of done: conformance tests, evidencing security controls, and proving your product behaves correctly when reality gets messy.
A well-run onboarding looks like this in practice: within your first sprint, you can authenticate a test user and fetch a capability statement through SSP. In sprint two, you render a safe, partial view of a patient’s medications and allergies from structured FHIR, with logging and audit working end-to-end. By sprint three, you have appointment search and booking in a test practice, along with an operational MESH outbox that can deliver and reconcile a sample PDF to a test mailbox. From there, you focus on fit-and-finish: labelling and clinical safety wrap-ups, performance hardening, and rehearsing support workflows. When you step into assurance, you’re merely proving what your telemetry already tells you: the system is ready.
There’s no single “right” order of tasks for every team, but the most successful implementations share attitudes: they keep the integration edges small and well-tested, they treat identity and audit as core features, they design for heterogeneity across thousands of GP practices, and they make operations visible from day one. If your solution embodies those principles, the mechanics of SSP headers and MESH control files become routine—and your users will experience what they actually care about: fast, safe access to the information they need, exactly when they need it.
Is your team looking for help with GP Connect integration? Click the button below.
Get in touch