Written by Technical Team | Last updated 05.09.2025 | 9 minute read
The NHS Spine is the digital backbone of national health infrastructure, hosting essential services such as the Summary Care Record, the Electronic Prescription Service, and patient demographics. Within this landscape, the Spine Directory Service (SDS) functions as a master directory: it tells systems where to send requests, how to authenticate, and which organisations own or operate services. Traditionally, this information was retrieved using LDAP queries. Today, a modern interface is available: the Spine Directory Service FHIR API.
The SDS FHIR API exposes directory information using HL7® FHIR® resource models. This means routing information, organisation details, and technical endpoints are expressed through standardised resources like Organization, Endpoint, and HealthcareService. These resources are linked together in a way that allows applications to traverse from an NHS organisation to the service it provides, and ultimately to the endpoint they must call.
This shift to FHIR is significant. Developers can use modern tooling, libraries, and patterns already familiar from clinical FHIR APIs. Instead of parsing arcane directory schemas, applications can make intuitive RESTful queries, cache results safely, and validate them with standard FHIR search parameters. For example, a system can query: “Give me the active endpoint for interaction X, provided by the organisation with ODS code Y.” That request is clear, testable, and future-proof.
The importance of SDS lies not in clinical content but in infrastructure. Without it, applications cannot reliably discover endpoints for critical workflows such as e-prescribing, referrals, or discharge summaries. By centralising routing logic in the directory, NHS Digital ensures consistency across suppliers, supports supplier migrations, and allows national services to evolve without breaking existing integrations. For developers and organisations, getting SDS integration right is the difference between brittle routing and resilient, scalable architecture.
Security underpins every NHS Spine interaction, and SDS is no exception. The directory may not contain patient-level clinical data, but the endpoints it reveals are gateways to sensitive services. Ensuring only authorised systems can discover and connect to them is crucial.
Connectivity begins with the network layer. Most production consumers access SDS over the Health and Social Care Network (HSCN), which provides a private and managed backbone across the NHS. Where internet access is permitted, strict safeguards are in place. Firewalls and egress controls should only allow outbound traffic to the specific hostnames and ports required for SDS, reducing the risk of accidental data exposure. DNS monitoring is also vital; incorrect resolution is a common cause of avoidable outages.
Above the transport, authentication relies on strong client identity. In most cases this is achieved through mutual TLS (mTLS), where both client and server present certificates to prove their identity. The client certificate binds the calling system to its organisation, ensuring every query can be traced. Certificates are issued under a strict governance model and must be rotated before expiry. Treat these credentials as critical assets: store them in secure keystores, automate renewal, and audit access.
Authorisation is expressed both through directory metadata and through interaction identifiers. Each endpoint is tied to a specific interaction contract. When you call SDS, you retrieve not just a URL but also a marker of what that endpoint expects—such as a unique identifier for a prescription submission interaction. Your downstream system must then present this identifier when connecting, ensuring that requests are routed correctly and governed appropriately. Some services may also require signed tokens, typically JWTs, that further describe the calling application, environment, or purpose.
Auditing and observability close the loop. Every SDS query should be logged with context: which system made the call, what resource type was queried, what identifiers were used, and what result was returned. This allows teams to trace routing decisions, investigate incidents, and prove compliance. Crucially, no patient data should ever be logged at this layer.
To support consistent practice, many organisations adopt a pre-deployment security checklist. This typically includes:
By embedding these checks early, teams avoid late-stage surprises and promote uniform security across services.
The SDS FHIR API organises its data into resources that are familiar to anyone working with FHIR. Understanding how they fit together is the foundation of effective integration.
The Endpoint resource is the most directly useful. It describes where and how to connect to a service: the URL, the connectionType (such as RESTful API or messaging endpoint), and the interaction identifiers it supports. Each Endpoint also carries metadata such as whether it is active, which organisation owns it, and when it was last updated. In practice, your application will query for endpoints filtered by interaction identifiers and, in some cases, by organisation. This ensures you retrieve the precise technical details needed.
The Organization resource captures the owner of a service. Organisations are identified by their ODS codes, which are widely used across NHS systems. An Organization may represent a GP practice, an NHS trust, or another healthcare entity. Linking Organization to Endpoint allows you to ask: “What is the endpoint for this service at this specific organisation?” For auditing, the organisation’s type, name, and identifiers are also valuable.
The HealthcareService resource links organisations to the services they provide. For example, a trust may expose a healthcare service for electronic prescribing. That service, in turn, links to one or more endpoints where requests should be sent. This separation—organisation, service, endpoint—reflects real-world complexity. A single organisation can provide many services, and a service may be hosted across multiple technical endpoints.
From an implementation perspective, query strategies should be deterministic and repeatable. A common pattern is:
Alternatively, for national services with a single target, you can query Endpoint directly using only the interaction identifier. In both approaches, FHIR search parameters make queries precise and auditable.
Handling results correctly is just as important as forming the query. A 200 response with an empty bundle is not an error: it means no match exists. By contrast, a 404 on a direct read indicates the specific resource ID does not exist. These outcomes should be logged distinctly and fed into operator playbooks. Deterministic tie-breakers should also be defined for cases where multiple endpoints are returned—for example, preferring the most recent lastUpdated value.
By mastering these resource models and patterns, developers can avoid brittle configuration and instead build routing that adapts gracefully as services evolve.
Successful integration with SDS requires a structured approach, moving through non-production environments into live deployment. Rushing the process risks outages, mis-routing, or security failures.
The first milestone is basic connectivity. In a sandbox or integration environment, developers use test ODS codes, certificates, and seeded directory data. A simple authenticated query—such as retrieving an Organization by ODS code—proves that network paths, DNS, TLS, and credentials are configured correctly. Only once this is stable should teams build more complex queries for Endpoint and HealthcareService.
Caching is a central design decision. Directory data changes infrequently, but it can and does change, particularly during supplier transitions. A balanced approach is to cache results for a defined time-to-live (TTL) and refresh them proactively. For critical services, a “first call validation” approach can be used: the first live transaction after deployment re-queries SDS to confirm the cached endpoint is still valid. Cached entries should store provenance data such as resource IDs and lastUpdated values, so routing decisions can always be explained.
Testing should go beyond the happy path. What happens if a query returns multiple endpoints? What if the target endpoint becomes inactive between lookup and invocation? What if an expected organisation does not appear in SDS? Each of these scenarios should be handled gracefully, with clear error messages and safe defaults. Synthetic monitoring—queries that replicate your production lookups on a schedule—can alert teams when directory entries change unexpectedly.
Governance is another non-negotiable element. For clinical systems, compliance with NHS safety standards such as DCB0129 and DCB0160 is mandatory. Even for administrative systems, evidence from the Data Security and Protection Toolkit (DSPT) may be required. Documentation should cover directory queries, caching behaviour, error handling, and audit logging. This ensures regulators and clinical safety officers can understand and approve the design.
To keep implementation consistent across teams, many organisations maintain a blueprint or run-book. This typically covers:
By following such a blueprint, teams can move from sandbox to go-live without surprises, reducing risk and ensuring smooth adoption.
Integration does not end at go-live. To maintain safe and reliable services, operational excellence is essential. The SDS FHIR API may not carry patient data directly, but its reliability underpins services that clinicians and patients depend on every day.
Monitoring should treat SDS queries as first-class citizens. Log the resource types, search parameters, result counts, and selected endpoints for each query. Instrument latency and error rates separately for SDS and downstream APIs; this allows teams to distinguish directory issues from endpoint-specific failures. Dashboards and alerts should highlight unusual result changes—such as a sudden increase in empty bundles for a key interaction.
Resilience depends on graceful error handling. A transient directory failure should not flood SDS with retries. Implement exponential back-off with jitter and use cached entries where safe. When cache entries expire, prefer a fail-closed approach for sensitive interactions—rejecting requests rather than risking mis-routing. Where caches are refreshed, log the old and new endpoint values to support incident investigation.
Proactive testing builds confidence. Regularly simulate certificate expiry, DNS failure, or missing endpoints in a non-production environment. These “chaos” exercises reveal weaknesses in error handling and operator run-books before they cause real incidents. Similarly, synthetic probes should continuously validate that the queries your applications rely on are returning expected results. If an endpoint or interaction is withdrawn, you should know before users are affected.
Change is inevitable. New services are added, interactions are deprecated, and suppliers migrate. Isolating your SDS integration code behind a small, testable interface makes adaptation easier. Feature flags for routing behaviour allow operators to switch quickly if directory data changes unexpectedly. Migration playbooks should describe how caches will be refreshed, how new endpoints will be validated, and how traffic will be switched safely.
By treating SDS integration as a product in its own right—with dedicated monitoring, governance, and continuous improvement—you create a stable foundation for the clinical and administrative services that depend on it. The result is fewer outages, faster supplier transitions, and a smoother experience for the healthcare professionals and patients who rely on connected systems.
Is your team looking for help with NHS Spine Directory Service API integration? Click the button below.
Get in touch