Written by Technical Team | Last updated 06.02.2026 | 14 minute read
Integrating with NHS systems is rarely about a single endpoint or a single message type. It’s about reliably finding the right system, in the right organisation, for the right interaction, and doing so in a way that remains safe, auditable, and consistent across thousands of NHS and partner environments. That is where the NHS Spine Directory Service (SDS) comes in.
The SDS has long been part of the “plumbing” of national interoperability: it’s the directory that helps services discover accredited systems and routing details so that data can be exchanged correctly. The Spine Directory Service FHIR API exposes that directory information in a modern, standards-aligned way so that applications, integration engines, and national services can look up what they need at runtime rather than relying on brittle static configuration.
If you are building a product that talks to other NHS systems, there are many ways you can integrate. Some are direct, some are mediated through national platforms, and some are effectively “internal” within a trust or ICS boundary. Understanding when the SDS API is relevant, what problems it solves, and how to design around it can prevent months of rework and a lot of operational risk.
This article explains what the SDS API is, why it matters, and when you actually need it in a real integration programme. It also covers the most important concepts behind it, the practicalities of implementation, and the common mistakes that cause delays or outages.
The NHS Spine Directory Service is, at its heart, a directory of technical and accreditation-related information about systems connected to Spine-related services. When people talk about “SDS”, they often mean the capability to look up the details that let one system talk to another: identifiers, accredited system records, and endpoint routing information for specific interactions.
The Spine Directory Service FHIR API is a way of accessing that directory using a FHIR R4-style interface. Rather than inventing a bespoke directory schema, it expresses SDS records through familiar FHIR resource shapes such as Device and Endpoint. That doesn’t mean the SDS suddenly becomes a clinical record system; it means implementers get a predictable data model, predictable search behaviour, and JSON structures that integrate well with modern platforms.
In practical terms, you use the SDS API to answer questions like: “Given this organisation and this service interaction, which accredited system is authorised to respond?” and “Where should I send the message, and what reliability settings apply to that endpoint?” Those questions are easy to underestimate until you’ve tried to hard-code them. At national scale, they change too often and there are too many edge cases.
The SDS API is primarily about system-level discovery and routing, not about discovering organisations or people. It’s not an organisational directory in the sense of listing sites, wards, teams, or staff; and it’s not a demographic or patient identity service. It exists to make sure that when you need to connect to an NHS endpoint for a defined interaction, you can do it correctly and consistently.
A subtle but important point is that SDS is less about “finding a URL” and more about “finding the right accredited system and the correct way to use it”. The directory knowledge includes identifiers and configuration that underpin trust in the connection, the selection of the correct target, and the operational behaviour expected during message exchange.
In NHS integration, correctness is more than “the request reached a server”. Correctness includes reaching the correct organisation, reaching the correct system within that organisation, using the correct interaction, and adhering to the reliability expectations that prevent message loss or duplication. SDS matters because it centralises the source of truth for those routing decisions.
Without SDS, teams often start with spreadsheets or environment-specific configuration files that map “organisation X + service Y” to “endpoint URL Z”. That approach can work in a limited estate, but it does not scale across the NHS because endpoints change, organisational relationships shift, suppliers change hosting, and additional service interactions get commissioned. When configuration is spread across multiple products and environments, it becomes difficult to govern and impossible to keep fully aligned.
SDS also matters because it reinforces accreditation and contractual boundaries. NHS integrations frequently depend on the concept that a system is accredited for a particular interaction and is known by a recognised identifier. The directory is one of the mechanisms that keeps the ecosystem coherent: if your service is trying to reach an endpoint that is no longer valid, misconfigured, or not accredited for the interaction, directory-based checks help surface that early and reduce the risk of unsafe or non-compliant data exchange.
Operationally, SDS reduces the blast radius of change. If an organisation changes supplier, a supplier migrates endpoints, or a service is reconfigured, directory updates can be applied centrally, and clients that perform lookups dynamically can adapt without requiring a redeploy. That isn’t magic; you still need sensible caching, careful rollout, and monitoring. But it turns a “change every client” problem into a “change the directory and allow clients to refresh” problem, which is far more manageable.
Finally, SDS supports the realities of asynchronous messaging and reliability. Many NHS interactions are not simple request–response API calls. Some are message-based or mediated. Some require acknowledgements, retries, and duplicate elimination. The endpoint information in SDS is not just “send it here”; it often includes the operational characteristics that your integration needs to respect to behave properly within the network.
At first glance, the SDS API can look deceptively straightforward: call a FHIR endpoint, receive a Bundle, parse Device or Endpoint, and move on. The complexity sits in the meaning of the identifiers and how they combine to describe “who you are trying to reach” and “what you are trying to do”.
The most common starting point is the idea of a service interaction. In NHS messaging and integration, interactions are defined formally: they represent a specific type of transaction or message exchange. The directory lets you search for records that are associated with a given interaction, because an endpoint that supports one interaction may not support another, even within the same organisation. Thinking in terms of “interaction-specific routing” will save you from building oversimplified discovery logic.
Alongside the interaction, you typically consider the organisation context, usually represented by an ODS code. However, the organisation code alone is rarely enough. A single organisation can have multiple systems, multiple suppliers, and multiple endpoints, sometimes for similar functions. SDS helps you narrow to the right target by combining organisation context with interaction identifiers and system identifiers.
You will also encounter the concept of accredited system records and identifiers that distinguish systems within the Spine ecosystem. This is where Device resources become useful: they represent an accredited system entry and its identifiers. Endpoint resources then represent where and how to connect for a routing purpose. Together they provide a path from “I need to interact with organisation X for interaction Y” to “this is the system identifier and this is the endpoint with these reliability characteristics”.
Here are the SDS concepts that tend to matter most in real projects:
Once you recognise how these concepts combine, you can design discovery logic that is robust rather than “works in the sandbox only”. For example, you may need to query for endpoints using multiple identifiers, handle more than one match, and apply selection rules that reflect your product’s role in the exchange. Some services will require you to know your own system identifier as well as the target’s, especially if the broader workflow includes additional Spine services or message-handling components.
It’s also important to understand that the SDS API returns FHIR Bundles, not a single object. Even if you expect one answer, you must handle zero results, multiple results, and partial data. In practice, “multiple results” is not necessarily an error: it might represent multiple endpoints for different environments, multiple system instances, or multiple configurations. Your integration should treat discovery as a process with validation steps rather than a single lookup.
Finally, be careful with assumptions about how “live” the directory should be for your product. Some integrations will do lookups per transaction, some will cache for hours or days, and some will pre-load and refresh periodically. The right approach depends on your reliability requirements, expected call volumes, and how frequently the target directory data changes in your domain.
Not every NHS integration needs SDS, and adopting it without a clear reason can add complexity. The key is to understand whether your product needs dynamic discovery of accredited systems and endpoints, or whether your connectivity is fixed and governed in a different way.
You generally need the SDS API when you are building a service that must communicate with a range of NHS organisations or systems where endpoints and configurations vary, and where those details can change over time. This is common for national-scale suppliers, shared care record platforms, integration engines, messaging intermediaries, and services that must route to multiple provider systems based on organisational context.
You also tend to need SDS when the interaction you are implementing is defined in a way that expects directory lookups as part of the standard operating model. If your integration design includes steps like “discover the target endpoint for this interaction” or “determine the accredited system record associated with the target”, SDS stops being optional and becomes part of the integration contract.
There are also cases where you might not need SDS at all. If your product integrates only with a single upstream system within a controlled boundary, and the endpoint is stable, contractually fixed, and managed through a local interface specification, then SDS can be unnecessary overhead. The same applies when you are integrating purely through a platform that already handles routing on your behalf, meaning you never directly send to the downstream endpoints.
A practical way to decide is to look at the failure modes you can tolerate. If an endpoint changes and you do not use SDS, you will need an out-of-band update to your configuration. That may be acceptable in a small estate but risky in a large one. If you can’t tolerate stale routing information, or you need to support onboarding many new organisations without manual configuration, SDS becomes much more compelling.
The following situations are strong indicators that you should plan for SDS integration:
Conversely, you might reasonably avoid SDS if you have a single static integration with a known endpoint, or if an upstream platform or integration partner performs discovery and routing for you and provides a stable contract you can rely on. In those cases, it can still be useful to understand SDS conceptually, because it may influence how the upstream platform behaves, but your product may not need to call it directly.
A useful middle ground is to design your product so that it can use SDS when available but can also operate with configuration-based routing in constrained deployments. This can support phased rollouts, pilots, and local deployments where the directory is not the gating factor, while preserving a path to scale when the product expands.
A successful SDS API integration is not just about making a request and parsing JSON. It’s about designing a discovery component that is reliable, secure, observable, and aligned with the operational realities of NHS environments.
Most teams benefit from treating SDS lookups as a dedicated capability within the architecture, rather than scattering lookup logic throughout the codebase. Create a “directory client” module that knows how to query for Device and Endpoint resources, validate results, apply selection rules, and expose a simplified interface to the rest of your product. This keeps your business logic clean and makes future changes easier, especially when service interactions evolve or when you add new workflows.
Security and access management also deserve attention early. Even though the SDS API uses application-level authentication, you should approach it with the same discipline you would apply to any production NHS API. Protect API keys, rotate them appropriately, restrict their use to required environments, and ensure your deployment pipelines never expose secrets in logs. Your integration should also use correlation identifiers consistently so that you can trace requests across distributed systems during incident response.
From an implementation point of view, SDS lookups are searches that return Bundles. You should implement robust parsing and validation: confirm resource types, handle missing fields, and treat unexpected structures as recoverable errors rather than fatal exceptions. Because directory data drives routing, failures should degrade gracefully where possible, with clear error messages and alerts that allow you to resolve issues quickly.
Two patterns tend to work well for SDS in production. The first is per-transaction lookup with short-lived caching, used when routing changes are frequent or when strict correctness is required at the point of use. The second is scheduled refresh into a local cache or configuration store, used when you have high volume, you want to reduce dependency on a remote lookup service for every transaction, or you need deterministic behaviour during upstream disruptions. Both patterns can be valid; the wrong pattern is usually “no caching at all” in high volume systems, or “cache forever” in systems where routing can change.
When implementing caching, you must treat the directory as the source of truth but not as an always-perfect oracle. Build in rules for cache expiry, error handling, and fallback. For example, if a lookup fails temporarily, you may choose to use a recently cached endpoint for a limited window while alerting operators. That is a business decision tied to risk, and it should be made explicitly rather than implicitly through “whatever the cache library does”.
Here are practical implementation steps that teams commonly follow:
There are also some recurring pitfalls that can derail integration programmes. One is assuming that every lookup produces exactly one result. In reality, you may see multiple entries and you’ll need a deterministic way to pick the correct one. Another is ignoring reliability configuration and treating an endpoint as a simple URL, which can lead to duplicate messages, missed acknowledgements, or retry storms. A third is failing to separate “directory discovery” errors from “downstream endpoint” errors, which makes incident triage painful and increases mean time to recovery.
It’s also worth planning for change in the wider ecosystem. NHS digital infrastructure evolves, and directory or platform endpoints may be deprecated or moved as domains and services are consolidated. Even if your SDS integration is technically correct, you should design it so that base URLs and identifiers can be updated through configuration rather than code changes, and so that your operational team has clear runbooks for rotating keys and updating environment endpoints.
Finally, remember that the purpose of SDS integration is not to tick a box; it’s to reduce the long-term cost and risk of interoperability. The best implementations treat directory-driven routing as a first-class capability: tested with realistic scenarios, monitored continuously, and documented clearly enough that engineers can support it at 3am without guessing. If you invest in that foundation, your product will onboard organisations faster, survive change better, and deliver integrations that behave predictably across the NHS landscape.
Is your team looking for help with NHS Spine Directory Service API integration? Click the button below.
Get in touch