Onboarding to GP Connect is not one process. It is two parallel tracks, a synchronous FHIR path for interactive record access and appointment management, and an asynchronous MESH path for document delivery that has to arrive with legal certainty rather than immediately. Most teams that struggle with GP Connect are not struggling with the API calls themselves. They are missing a prerequisite that should have been lined up before sprint one, most often identity or Spine registration, and discovering it three weeks into a build. The order below is not the only order that works, but skipping a step rather than sequencing it later is where most delays come from.

Step 1: Confirm your organisational prerequisites

Before any code is written, the consuming organisation needs an ODS code, a documented lawful basis for processing, a completed Data Protection Impact Assessment, and a data sharing arrangement that covers the use case being built. This is organisational groundwork, not a technical task, and it usually takes longer than any individual engineer expects because it depends on people outside the development team. Start it in parallel with everything else, not after.

At this stage, decide which access model applies. A point-of-care scenario, a clinician in community or urgent care launching an application to view a record, authenticates interactively and the system acts on their behalf. A system-to-system scenario still needs a lawful basis and robust access controls, even without a clinician present at the point of the call. The two models lead to different identity work later, so this decision belongs at the start, not somewhere in the middle of building the FHIR client.

Step 2: Design your identity approach around CIS2

Identity is not a feature to bolt on once the API calls work. For the majority of live clinical use, GP Connect's user-restricted APIs require registration with CIS2 and the NHS API platform, a generated key pair, and published public key material to support OpenID Connect token flows. That registration process, key management, and the shape of the full authentication and authorisation handshake, launch context, user authentication, token acquisition, and token exchange, should be designed before the first FHIR call is built, because it shapes session management, error handling, and audit trails throughout the rest of the application.

Treat CIS2 as core architecture rather than a login screen. A design decision made here late in a project usually means rework in every part of the system that depends on knowing who is asking for data and on whose behalf.

Step 3: Register with the Spine Directory Service

GP Connect endpoints and identities are discoverable through the Spine Directory Service, which holds records such as Accredited System IDs and endpoint addresses. A consumer needs its software and the organisations deploying it recorded so requests are recognised. A provider needs its endpoint correctly published and associated with the relevant GP practices. Without these directory records in place, the Spine Secure Proxy has no way to route a request correctly, regardless of how well the FHIR client itself is built.

Step 4: Set up MESH if the solution needs document exchange

If the solution needs to deliver documents rather than serve interactive views, discharge summaries, consultation notes, or ITK3-structured content that must arrive with assured delivery, a MESH mailbox needs to be secured and its certificate setup completed. Each document type and business process should map to a MESH workflow identifier recognised by both sender and recipient. Where the use case is tied closely to a specific GP clinical system supplier, coordinate with that supplier early, since many practice mailboxes are managed by the supplier and workflow names have to be supported on both ends. A short conversation with the local Integrated Care Board or practice IT team at this stage tends to save considerably more time than discovering the mismatch later.

Step 5: Build the FHIR client against the Spine Secure Proxy

Consuming systems do not call GP systems directly. They call through the Spine Secure Proxy, which expects specific headers identifying the caller, the interaction being invoked, and routing metadata, and which centralises security, policy, and audit. Encode these headers centrally in the HTTP client so every request is consistent, and assert their presence in automated contract tests rather than relying on manual review to catch a missing header.

Fetch and cache each provider's capability statement before assuming what it supports. GP Connect constrains FHIR into specific profiles, but providers still vary in what they expose in practice, and a client that checks the capability statement can degrade gracefully rather than failing outright when a provider does not support a particular section. Treat FHIR profiles as code: generate models from the published profiles where possible, enforce required fields and value sets in the domain layer, and validate incoming data against both schema and business rules. Clinical data carries caveats, discontinued medications, historical entries, redacted sections, and the interface needs to represent that uncertainty rather than implying a complete picture where one does not exist.

Apply privacy by design throughout. Request the minimum data needed for the task in front of the user, filter it immediately to what is relevant, and avoid storing content unless there is a genuine operational reason to. Where caching is necessary for performance, time-limit it and encrypt it at rest. Every retrieval should be traceable in the audit trail to a specific user, patient, purpose, and outcome.

Step 6: Test scenarios, not just individual calls

A capability statement retrieval passing in isolation proves very little. Build realistic patient scenarios instead: patients with multiple recorded surnames, historic allergies, problems in remission, repeat medications with staggered review dates, and ceased medicines that should not be presented as active. Confirm the interface handles absent sections explicitly rather than silently, since an empty section that looks the same as a section that failed to load is a patient safety risk, not a display inconsistency.

For appointment flows, test race conditions, cancellations, and slot unavailability directly rather than assuming the happy path is representative. For MESH, test large payloads, duplicate sends, and misrouted workflow identifiers, since these are the failure modes that surface in production rather than in a demo.

Performance testing matters here in a way it does not always for internal tools. Latency through the Spine Secure Proxy includes its own processing overhead on top of the provider's response time, and that combined figure should be measured directly rather than estimated from the provider API alone.

Step 7: Prove assurance as you go, not at the end

Assurance runs in parallel with development, not after it. A thin working path early, a test user authenticating through CIS2, a validated token, a correctly headed call through the Spine Secure Proxy, and a single successful retrieval of a low-risk resource such as a capability statement, proves the end-to-end path before any specific GP Connect capability is layered on top. From there, structured record views, appointment management, or MESH document flows can be added one at a time, each validated against the same working foundation rather than each requiring its own separate proof that the plumbing works.

Codify security and governance checks as automated tests rather than a document reviewed once before launch. Block a deployment if a required Spine Secure Proxy header is missing from a request in contract tests. Fail a build if a change weakens token validation or widens a scope beyond what was agreed. Make the audit trail queryable by patient, user, time, and action from day one, because that is what makes a data subject request or an incident response workable rather than theoretical.

Where this connects to build work

The pattern underneath every step above is the same one: resolving who is asking, confirming which patient they mean, and proving both of those things to a standard that survives an audit. We built exactly that shape of problem for a primary care technology provider, replacing manual entry of patient demographics at registration with a certificate-secured lookup against the NHS Spine using QuickSilva's Spine Mini Service, including NHS number modulus checks and a full audit trail behind every match. Identity resolution against a national NHS system, with the audit evidence to back it up, was the actual engineering problem there, in the same way it sits underneath every step of a GP Connect onboarding.