Written by Technical Team | Last updated 06.02.2026 | 10 minute read
Integrating with the NHS Spine is rarely a single-step exercise. In most production-grade NHS pathways, systems must dynamically discover where to send requests based on organisational context, supported services, and accredited deployment details. The NHS Spine Directory Service (SDS) exists to solve this exact problem by acting as the authoritative source of truth for Spine-connected systems and their routing metadata.
The Spine Directory Service FHIR API exposes this directory capability using a FHIR R4-aligned REST interface. Rather than storing clinical data, it focuses on system metadata and connectivity, allowing applications to discover accredited systems and resolve the correct endpoints for a given organisation and interaction. For developers working on GP Connect consumers, Spine intermediaries, or any solution that relies on dynamic routing across NHS organisations, SDS becomes a foundational dependency.
This article explores how to integrate with the SDS FHIR API end to end, not just at the level of individual endpoints but as a coherent workflow. It explains how to design a reliable discovery process, how to structure requests and interpret FHIR responses safely, and how to operationalise endpoint discovery so it performs predictably in real NHS environments.
The core responsibility of SDS is to answer one deceptively simple question: where should this request be sent? The answer depends on more than just an organisation code. It is shaped by the interaction being performed, the system accredited to support that interaction, and the technical routing configuration associated with that system.
In SDS terminology, systems are registered as Accredited Systems, each identified by an Accredited System Identifier (ASID). An ASID represents a specific deployment of a system at a specific organisation, rather than a product in the abstract. This distinction is critical because the same supplier solution deployed at different GP practices or trusts will usually have different ASIDs, even though the software is identical.
The SDS FHIR API represents these accredited systems using the FHIR Device resource. Although the name may suggest physical hardware, in this context Device is simply the FHIR container chosen to represent a registered system. The Device resource typically includes identifiers such as the ASID and the Message Handling System (MHS) Party Key, along with extensions that describe which service interactions the system supports.
Routing information itself is exposed through the FHIR Endpoint resource. Endpoints describe where and how messages or API calls should be sent, including the address to call and supporting metadata needed for reliable communication. Together, Device and Endpoint form a two-step discovery process: first identify the correct accredited system, then resolve its routing details.
A common mistake is to treat SDS as a static directory that can be queried once and forgotten. In reality, it should be considered a runtime capability. Systems change, organisations migrate suppliers, and routing details evolve over time. A well-designed integration treats SDS as a dynamic dependency that must be queried, cached carefully, and monitored like any other critical service.
A reliable SDS integration follows a consistent discovery workflow. While implementations vary, the underlying pattern remains stable across most NHS use cases.
The process begins with an organisational context, most commonly an ODS organisation code. This identifies the target organisation but does not, on its own, determine which system or endpoint should be used. The second essential input is the service intent, typically expressed as a service interaction identifier. This defines what you are trying to do, not just who you are trying to contact.
With these two inputs, the first API call is made to the /Device endpoint. This search returns one or more Device resources representing accredited systems that support the requested interaction at the specified organisation. Each Device provides identifiers that allow you to uniquely reference that system, most importantly the ASID and the Party Key.
The result of the /Device call is not yet a routable address. Instead, it provides the context required to perform the second lookup. Using the identifiers obtained from the Device resource, the integration then calls the /Endpoint endpoint to resolve the actual endpoint details. This second call returns Endpoint resources that include the address your application must use when making subsequent calls.
In practice, the most important outcome of this workflow is not the raw endpoint URL but the confidence that the endpoint is correct for the organisation, interaction, and system context. This confidence comes from consistently using the same service intent across both calls and ensuring that the identifiers extracted from the Device response are explicitly matched in the Endpoint search.
Once an endpoint has been resolved, many teams normalise the result into an internal routing model. This allows the rest of the application to remain unaware of FHIR-specific structures and reduces coupling between directory resolution logic and business workflows. The internal model typically includes the resolved endpoint address, the identifiers used to derive it, and metadata such as environment and lookup timestamp.
Although the SDS FHIR API follows FHIR conventions, it is used for directory resolution rather than clinical data exchange. This changes how responses should be interpreted and how defensive the parsing logic needs to be.
All successful searches return a FHIR Bundle, usually of type searchset. These Bundles may contain zero, one, or multiple entries, and integrations must handle all three scenarios gracefully. Assuming a single result is one of the most common causes of brittle implementations.
Query parameters for SDS searches use FHIR identifier syntax rather than simple key-value pairs. This means parameters typically include both an identifier system and a value. Constructing these identifiers consistently is essential, and many teams benefit from centralising this logic in a shared utility rather than duplicating string construction throughout the codebase.
When parsing Device responses, identifiers should never be accessed by array position. FHIR does not guarantee ordering, and SDS records may evolve over time. Instead, identifiers should be extracted by matching on their system values. The same principle applies to extensions, which may appear multiple times or not at all depending on the registration state.
Endpoint responses require similar care. It is entirely valid for a search to return multiple Endpoint resources. In these cases, the integration must apply deterministic selection logic based on the context of the lookup. Choosing the first entry without validation can result in requests being sent to the wrong service, which is particularly problematic in clinical environments.
Error handling should also be structured. Many SDS error responses use the FHIR OperationOutcome resource to convey diagnostic information. Parsing these responses and logging meaningful error details makes troubleshooting far more efficient than relying on HTTP status codes alone.
SDS FHIR API access spans multiple environments, typically including sandbox, integration, deployment, and production. Each environment has its own base URL and purpose, and a production-ready integration should support all of them through configuration rather than code changes.
Authentication is application-based and relies on API keys. While technically simple, API keys should be treated as sensitive credentials. They should be securely stored, rotated as required, and never exposed in logs or client-side code. In production systems, access to these keys should be tightly controlled.
Operational readiness extends beyond authentication. Endpoint discovery becomes a dependency for many user-facing workflows, so its availability and performance directly affect service quality. Teams should plan for scenarios where SDS is slow or temporarily unavailable, using conservative caching strategies and clear error propagation to prevent cascading failures.
Production access to SDS is typically granted as part of onboarding for a wider NHS programme rather than as a standalone activity. This means integration timelines are often influenced by assurance processes, conformance testing, and programme-specific requirements. Aligning technical design with these expectations early can prevent delays later in the delivery cycle.
Once deployed, endpoint discovery must operate reliably under load and change. Caching plays a central role, but it must be implemented carefully. Overly aggressive caching can hide legitimate directory updates, while insufficient caching can introduce unnecessary latency and load.
A common approach is to cache resolved endpoints using a composite key that includes the organisation, service intent, and any relevant system identifiers. This ensures that different services or interactions do not accidentally share routing information. Cache lifetimes should be conservative, reflecting the fact that directory data can change.
Observability is equally important. Directory resolution failures are often blamed for downstream issues, so logs and metrics should clearly show when and how endpoints were resolved. Correlation identifiers, structured logging, and clear error messages significantly reduce the time needed to diagnose problems.
Retry logic should be applied selectively. Transient failures such as timeouts may warrant retries with backoff, while client-side errors should fail fast. Uncontrolled retries can amplify outages rather than mitigate them.
Many SDS integration issues stem from assumptions rather than technical limitations. Assuming a single result, assuming identifier order, or assuming endpoints rarely change are all patterns that lead to fragile systems. Treating endpoint discovery as a first-class component, with tests, versioning, and ownership, helps avoid these pitfalls.
When implemented thoughtfully, the NHS Spine Directory Service FHIR API enables dynamic, reliable routing across complex NHS landscapes. By designing endpoint discovery as an explicit workflow rather than a simple lookup, teams can build integrations that remain robust even as organisations, systems, and services evolve.
The SDS FHIR API solves the problem of dynamic system discovery and routing within the NHS Spine ecosystem. Instead of hard-coding endpoint URLs for every organisation and service, integrations can use SDS to determine which accredited system supports a given interaction at a specific organisation and where requests should be sent. This is essential in an environment where organisations may change suppliers, endpoints may move, and multiple systems may coexist across NHS settings. SDS ensures that requests are routed correctly at runtime based on authoritative directory data.
The use of FHIR Device and Endpoint resources reflects a design decision to align with established FHIR R4 structures while representing non-clinical data. In SDS, a Device represents an accredited system deployment rather than physical hardware, while an Endpoint represents routable connectivity details. Using standard FHIR resource types allows the API to remain consistent with broader FHIR tooling and patterns, even though the semantics are focused on directory and infrastructure concerns rather than patient data.
No, the SDS FHIR API is not designed for general organisation or person lookup. Its scope is limited to accredited systems and their routing information. While organisation codes are used as search parameters, the API does not return Organisation or Practitioner resources. For broader directory needs involving organisations or individuals, other Spine services such as the SDS LDAP interface are used instead. Treating SDS FHIR as a system-level directory rather than a people or organisation registry helps avoid incorrect assumptions during integration.
Endpoint discovery should be treated as a runtime capability but not necessarily performed on every single transaction. Most production systems resolve endpoints on demand and cache the results for a limited period. The appropriate frequency depends on the service context and risk tolerance, but the key principle is to balance freshness with stability. Endpoints can and do change, so long-lived static configuration is risky, yet excessive lookups can introduce latency. Conservative caching with clear expiry and revalidation is typically the safest approach.
Most failures arise from incorrect assumptions rather than API instability. Common issues include malformed identifier parameters, inconsistent service identifiers between Device and Endpoint searches, assuming a single search result, or extracting identifiers by array position instead of matching on identifier systems. Operational issues such as missing API keys, incorrect environment URLs, or insufficient logging also contribute to integration problems. Addressing these risks early by designing defensive parsing, clear error handling, and strong observability significantly improves long-term reliability.
Is your team looking for help with NHS Spine Directory Service API integration? Click the button below.
Get in touch