Written by Technical Team | Last updated 02.08.2025 | 8 minute read
Integrating with the NHS Spine is a complex yet essential step for healthcare systems aiming to deliver safe, timely and connected patient care. At the heart of this process lies a sequence of services—PDS, SDS, and GP Connect—that together enable accurate patient identification, secure endpoint discovery, and authorised access to clinical information. Understanding how these components work in sequence is critical for developers, integrators and IT teams building solutions that must comply with NHS interoperability standards while ensuring security, governance and clinical safety. This article provides a detailed, step‑by‑step exploration of the end‑to‑end integration journey, from tracing a patient in the Personal Demographics Service through to retrieving their record using GP Connect.
The journey begins with the Personal Demographics Service (PDS), which is the central patient demographic database for the NHS in England. It is the authoritative source for NHS numbers, ensuring that patient identities are verified and correctly linked to their clinical records. For any GP Connect consumer application, the PDS trace is not optional—it is a critical foundation for ensuring that subsequent requests are accurate and legally valid.
A PDS trace allows the system to confirm that a provided NHS number is genuine, current, and correctly associated with a patient. In practice, this protects against misidentification, which can lead to clinical safety risks if records are requested for the wrong individual. In addition to verifying the NHS number, the PDS response typically returns organisational information, including the ODS code of the patient’s registered GP practice. That ODS code is vital, as it dictates which system’s GP Connect endpoint the consumer application should target.
While some consumer systems may consider caching patient demographics or relying on pre‑configured lookups, doing so risks acting on outdated or incomplete information. Patient registrations can change frequently, particularly for individuals moving between areas, care homes, or temporary residences. Therefore, real‑time PDS queries are strongly recommended. This ensures that the downstream GP Connect requests reach the correct practice system and that the consuming application is operating with up‑to‑date demographic context.
Once the ODS code has been retrieved through PDS, the next stage is to query the Spine Directory Service (SDS). This service functions as a secure directory of all accredited systems on the Spine, containing details such as Accredited System IDs (ASIDs), party keys, and service root URLs for FHIR endpoints. Without this directory look‑up, a consumer application cannot reliably know where or how to send GP Connect requests.
A typical sequence involves first retrieving the Endpoint resource using the ODS code and the required GP Connect interaction ID. The Endpoint response provides key technical details, including the message handling system (MHS) party key and the base FHIR service root URL that the practice uses to expose its GP Connect capabilities. This step bridges the gap between knowing the patient’s registered practice and being able to connect to its systems in a programmatic, secure manner.
After resolving the Endpoint, the system must then query the Device resource in SDS. The Device response contains the practice’s ASID, which is the unique identifier required for authorisation and routing of messages through the Spine Secure Proxy. Together, the Endpoint and Device calls provide the consumer system with the exact information needed to address future GP Connect requests correctly.
It is important for implementers to recognise that SDS behaviour differs across sandbox, integration, and live environments. For instance, sandbox environments may return only mock data, while integration and production systems supply fully populated identifiers, including the essential nhsMhsEndpoint elements. A robust integration strategy should be prepared for these differences, ensuring that the system can adapt to test, assurance, and live deployments without unexpected failures.
With both the ASID and service root URL obtained, the consumer system can progress to the next step: retrieving the provider’s CapabilityStatement. This is performed via a GET request sent through the Spine Secure Proxy (SSP). The SSP acts as a broker and gatekeeper, enforcing both technical and governance rules for all traffic flowing between consumer and provider systems.
The CapabilityStatement provides a structured description of the FHIR interactions and profiles supported by the provider. By interrogating this resource, a consumer application can discover whether the practice supports Access Record Structured, Appointment Management, or other GP Connect capabilities. This knowledge is vital for runtime decision‑making, as not all providers expose the same set of operations.
Caching the CapabilityStatement for the duration of a session can be beneficial, reducing unnecessary repeated requests. However, consumer systems must also handle the possibility that a provider may change its capabilities between sessions. Designing the integration logic to dynamically react to capability differences ensures a more resilient and future‑proof solution.
Once capabilities have been confirmed, the consumer application is ready to issue live GP Connect FHIR requests through the Spine Secure Proxy. Each request must include a number of mandatory headers, including Ssp‑From (the ASID of the consumer), Ssp‑To (the ASID of the provider), and an authorisation header containing a valid JWT bearer token. These headers ensure that only properly accredited and authorised systems can make calls, and that all requests are logged with the correct provenance.
An example of a common request is the Access Record Structured operation. Here, the consumer constructs a FHIR Parameters resource specifying which elements of the patient record are required, such as medications, allergies, or conditions. The request is then POSTed to the provider’s GP Connect endpoint. If successful, the provider responds with a FHIR Bundle containing the requested resources.
Another frequent interaction is appointment management. A consumer system may query available slots, retrieve appointment details, or even create bookings, depending on the capabilities exposed by the provider. As with record access, these operations must be addressed through the SSP with the appropriate headers and security tokens.
Robust error handling is a critical component of this stage. Providers may respond with FHIR OperationOutcome resources to indicate issues such as missing mandatory elements, unsupported operations, or invalid request parameters. A well‑designed consumer application will interpret these responses gracefully, surfacing meaningful error messages to clinicians or system administrators rather than generic failures.
Secure integration with the NHS Spine requires more than just technical compliance; it also demands adherence to strict governance and clinical safety standards. Both consumer and provider systems must be properly registered in the Spine Directory Service with matching ASIDs and accredited interactions. In addition, formal data sharing agreements must be in place to authorise the flow of patient information between organisations.
Every request made through the SSP must include a valid JWT constructed by the consumer system. This token contains critical claims such as the issuing system, the user identity, and the intended audience. The scope claim is particularly important, as it determines which resources and operations the consumer is authorised to access. SSP verifies these claims and logs the details for audit purposes before allowing the request to proceed.
Clinical safety is another essential consideration. Implementers must work within the frameworks defined by standards such as DCB0129 and DCB0160, ensuring that hazard logs, risk assessments, and safety sign‑offs are in place. This helps guarantee that patient data is handled responsibly and that any potential clinical risks introduced by the integration are identified and mitigated.
Audit logging should also not be overlooked. Systems should capture key details such as consumer and provider ASIDs, timestamps, request identifiers, FHIR resource types accessed, and the user identity associated with each request. This information provides a comprehensive trail for both governance compliance and troubleshooting, ensuring transparency and accountability throughout the integration process.
While the sequence of PDS, SDS, and GP Connect operations may appear straightforward in theory, real‑world implementations often encounter challenges that must be anticipated and addressed.
A common issue is when a patient record cannot be located at the provider system after a PDS trace confirms the NHS number. This can occur if the patient has recently registered with a new GP practice and the provider’s systems have not yet fully synchronised. In such cases, consumer applications must present clear, informative messages rather than generic errors, helping clinicians understand the situation and avoid clinical risk.
Another challenge arises when multiple ASIDs exist for a single ODS code. This situation may occur in organisations hosting multiple GP systems. Consumers must be coded to select the ASID linked to the declared interaction ID and to safely handle ambiguous scenarios without defaulting to an incorrect system.
Differences between sandbox, integration, and live environments can also cause unexpected behaviour. For example, some test environments may not return complete SDS payloads, leading developers to mistakenly believe their integration logic is failing. Awareness of these environmental differences is key to a smooth implementation journey.
Finally, there is the risk of capability mismatches. Not all GP systems enable every GP Connect capability, and the availability of interactions can vary between providers. Consumer applications should dynamically adapt to the capabilities advertised in the provider’s CapabilityStatement and inform users when a requested function is unsupported, rather than hard‑coding assumptions.
By anticipating these real‑world challenges and designing systems to handle them gracefully, integrators can create resilient, user‑friendly solutions that deliver consistent value across varied healthcare settings.
Is your team looking for help with GP Connect integration? Click the button below.
Get in touch