We have detected that you are using Internet Explorer to visit this website. Internet Explorer is now being phased out by Microsoft. As a result, NHS Digital no longer supports any version of Internet Explorer for our web-based products, as it involves considerable extra effort and expense, which cannot be justified from public funds. Some features on this site will not work. You should use a modern browser such as Edge, Chrome, Firefox, or Safari. If you have difficulty installing or accessing a different browser, contact your IT support team.
Overview
Use this API to access details of systems registered in the Spine Directory Service (SDS).
You can:
- get accredited system details
You cannot currently use this API to:
- search for organisations
- search for people
Accredited system records
Every system that connects to the Spine has one or more “Accredited System” (AS) records in SDS, identified by an Accredited System Identifier (ASID). This ASID is unique to a system deployed in a specific organisation, so the same application deployed into three NHS organisations would typically be represented as three unique ASIDs.
MHS records and endpoints
Every GP Connect system also has one or more “MHS” records (or message handling server record), identified by Party Key and Interaction ID. MHS records of GP Connect provider systems contain the endpoint of the target practice, as defined by the FHIR service root URL. Please see System topologies for more details on the allocation of ASIDs and Party Keys.
API status
This API is in beta, meaning:
- the API is available in our sandbox and integration test environments
- the API is not yet available for production use
- we might make breaking changes, but only if we cannot avoid it, and we'll give advance notice
To see our roadmap, or to suggest, comment or vote on features for this API, see our interactive product backlog.
If you have any other queries, please contact us.
Technology
This API is RESTful.
It also conforms to the FHIR global standard for health care data exchange.Specifically, it is aligned with FHIR UK Core, which is built on FHIR Release 4. You don’t need to know much about FHIR to use this API - FHIR APIs are just RESTful APIs that follow specific rules. In particular:
- resource names are capitalised and singular, for example
/Endpoint
not/endpoints
Errors handling in this API follows NHS guidelines and produces an OperationOutcome FHIR resource response with appropriate HTTP code
Network access
This API is available on the internet and, indirectly, on the Health and Social Care Network (HSCN).
For more details see Network access for APIs.
Security and Authorisation
This API uses the Application-restricted pattern.
In this pattern, you authenticate your application by including an API key with each API request. The API key is unique to your application.
For more details, including detailed technical integration instructions, see Security and Authorisation - Application-restricted RESTful APIs - API key authentication page within the NHS Digital Portal.
Environments and testing
Environment | Base URL |
---|---|
Sandbox | https://sandbox.api.service.nhs.uk/spine-directory/ |
Integration test | https://int.api.service.nhs.uk/spine-directory/ |
Sandbox testing
Our sandbox environment:
- is for early developer testing
- only covers a limited set of scenarios
- is open-access, so does not allow you to test authorisation
For more details on sandbox testing, or to try out the sandbox using our "Try this API" feature, see the documentation for each endpoint.
Integration testing
Our integration test environment:
- is for formal integration testing.
- includes application authentication
Data
The data used will be dependant on the service you are trying to access. See Spine Services and Interaction IDs
For more details see integration testing with our RESTful APIs.
Related APIs
The following APIs are related to this one:
- Spine Directory Service - LDAP API - Access details of organisations, people and systems registered in the Spine Directory Service (SDS) using our LDAP API.
Legal Use
This API can only be used where there is a legal basis to do so. Make sure you have a valid use case before you go too far with your development.
You must do this before you can go live (see ‘Onboarding’ below).
Onboarding
You need to get your software approved by us before it can go live with this API. We call this onboarding. The onboarding process can sometimes be quite long, so it’s worth planning well ahead. This API is not yet available for onboarding.
Endpoints
Get accredited system details
Overview
Use this endpoint to get accredited systems information in SDS.
This endpoint should return all matching accredited system objects which provides the following information:
- Accredited System Identifier
- Managing Organisation Code
- Client Code
- Party Key
- Service-Interactions
To get the information, you must supply:
- organisation code
- service identifier
and may supply:
- managing organization identifier
- party key
Request
Query parameters
Name | Description |
---|---|
organization |
String
The organisation code for the NHS Spine instance that your Message Handling System is communicating with. Must be preceded with FHIR identifier (eg."organization=https://fhir.nhs.uk/Id/ods-organization-code|YES-0000806")
Required
|
identifier |
array[String]
The service that is being contacted and the action that is required. Additionally optional MHS party key as a second occurance of this parameter. Both must be preceded with FHIR identifier (eg. service id: 'identifier=https://fhir.nhs.uk/Id/nhsServiceInteractionId|urn:nhs:names:services:gpconnect:fhir:rest:search:patient' ; party key: 'identifier=https://fhir.nhs.uk/Id/nhsMhsPartyKey|YES-0000806'). See the Data section in this API Specification document for more information.
Required
|
managing-organization |
String
Manufacturer's organisation code - ODS code of the manufacturer's organisation (i.e. GP System supplier)
|
Headers
Name | Description |
---|---|
X-Correlation-Id |
UUID
(uuid)
UUID for request tracking
|
Response
HTTP status: 200
Body
{
"resourceType" : "Bundle",
"id" : "9A05D8C6-587D-4CD7-B360-C5560961C01F",
"type" : "searchset",
"total" : 1,
"link" : [ {
"relation" : "self",
"url" : "http://internal-dev.apis.ptl.api.platform.nhs.uk/Device?organization=https://fhir.nhs.uk/Id/ods-organization-code|A20047&identifier=https://fhir.nhs.uk/Id/nhsServiceInteractionId|urn:nhs:names:services:gpconnect:fhir:rest:search:patient&identifier=https://fhir.nhs.uk/Id/nhsMhsPartyKey|A20047-821870&managing-organization=https://fhir.nhs.uk/Id/ods-organization-code|X26"
} ],
"entry" : [ {
"fullUrl" : "http://internal-dev.apis.ptl.api.platform.nhs.uk/Device/0E512499-E65C-4AE9-BEEC-224917FCDE94",
"resource" : {
"resourceType" : "Device",
"id" : "0E512499-E65C-4AE9-BEEC-224917FCDE94",
"identifier" : [ {
"system" : "https://fhir.nhs.uk/Id/nhsSpineASID",
"value" : "200000000985"
}, {
"system" : "https://fhir.nhs.uk/Id/nhsMhsPartyKey",
"value" : "A20047-821870"
} ],
"extension" : [ {
"url" : "https://fhir.nhs.uk/StructureDefinition/Extension-SDS-ManufacturingOrganisation",
"valueReference" : {
"identifier" : {
"system" : "https://fhir.nhs.uk/Id/ods-organization-code",
"value" : "A20047"
}
}
}, {
"url" : "https://fhir.nhs.uk/StructureDefinition/Extension-SDS-NhsServiceInteractionId",
"valueReference" : {
"identifier" : {
"system" : "https://fhir.nhs.uk/Id/nhsServiceInteractionId",
"value" : "urn:nhs:names:services:gpconnect:fhir:operation:gpc.getcarerecord"
}
}
}, {
"url" : "https://fhir.nhs.uk/StructureDefinition/Extension-SDS-NhsServiceInteractionId",
"valueReference" : {
"identifier" : {
"system" : "https://fhir.nhs.uk/Id/nhsServiceInteractionId",
"value" : "urn:nhs:names:services:gpconnect:fhir:rest:read:location"
}
}
} ],
"owner" : {
"identifier" : {
"system" : "https://fhir.nhs.uk/Id/ods-organization-code",
"value" : "A20047"
}
}
},
"search" : {
"mode" : "match"
}
} ]
}
Name | Description |
---|---|
object
|
|
resourceType string
|
Default:
Bundle |
id string
uuid
|
Unique identifier for this search request.
|
type string
|
Default:
searchset |
total integer
|
|
link array
|
|
object
|
|
relation string
|
Default:
self |
url string
|
The full url that produced the data
|
entry array
|
|
object
|
|
fullUrl string
|
Full url of the resource
|
resource object
|
A FHIR Device resource information for the accredited system
|
resourceType string
|
Default:
Device |
id string
uuid
|
SDS’s unique identifier for this accredited system record.
Example:
f0f0e921-92ca-4a88-a550-2dbb36f703af |
identifier array
|
Identifies this device across multiple systems
|
object
|
|
system string
|
|
value string
|
|
extension array
|
Additional content defined by implementations
|
object
|
|
url string
|
|
valueReference object
|
|
identifier object
|
|
system string
|
|
value string
|
|
owner object
|
Manufacturer's organisation details
|
identifier object
|
|
system string
|
|
value string
|
|
display string
|
|
search object
|
Search operation description
|
mode string
|
Default:
match |
HTTP status: 400
HTTP status: 404
HTTP status: 405
HTTP status: 406
HTTP status: 500
HTTP status: 502
HTTP status: 504
Get routing and reliability details
Overview
Use this endpoint to get accredited systems routing and reliability information in SDS.
This endpoint should return all matching routing and reliability objects which provides the following information:
- Endpoint Service ID
- Message Handling System Party Key
- Accredited System ID
- Endpoint URL
- Fully Qualified Domain Name of the Message Handling System
To get the information, you must supply:
- organisation code
And at least one of the following:
- service identifier
- party key
Request
Query parameters
Name | Description |
---|---|
organization |
String
The organisation code for the NHS Spine instance that your Message Handling System is communicating with. Must be preceded with FHIR identifier (eg."organization=https://fhir.nhs.uk/Id/ods-organization-code|YES-0000806")
Required
|
identifier |
String
The service that is being contacted and the action that is required, or the MHS Party Key (or both, as separate occurences of this parameter). Must be preceded with FHIR identifier (eg. service id 'identifier=https://fhir.nhs.uk/Id/nhsEndpointServiceId|urn:nhs:names:services:psis:REPC_IN150016UK05' ; party key: 'https://fhir.nhs.uk/Id/nhsMhsPartyKey|A20047-821870'). See the Data section in this API Specification document for more information.
Required
|
Headers
Name | Description |
---|---|
X-Correlation-Id |
UUID
(uuid)
UUID for request tracking
|
Response
HTTP status: 200
Body
{
"resourceType" : "Bundle",
"id" : "BAD2C148-6353-40A6-A215-33222EED2E11",
"type" : "searchset",
"total" : 1,
"link" : [ {
"relation" : "self",
"url" : "http://internal-dev.apis.ptl.api.platform.nhs.uk/Endpoint?organization=https://fhir.nhs.uk/Id/ods-organization-code|YES&identifier=https://fhir.nhs.uk/Id/nhsServiceInteractionId|urn:nhs:names:services:psis:REPC_IN150016UK05&identifier=https://fhir.nhs.uk/Id/nhsMhsPartyKeey|A20047-821870"
} ],
"entry" : [ {
"fullUrl" : "http://internal-dev.apis.ptl.api.platform.nhs.uk/Endpoint/08CE3BFB-5055-422B-9AE5-80DF6F4E1C61",
"resource" : {
"resourceType" : "Endpoint",
"id" : "08CE3BFB-5055-422B-9AE5-80DF6F4E1C61",
"status" : "active",
"connectionType" : {
"system" : "http://terminology.hl7.org/CodeSystem/endpoint-connection-type",
"code" : "hl7-fhir-msg",
"display" : "HL7 FHIR Messaging"
},
"payloadType" : [ {
"coding" : [ {
"system" : "http://terminology.hl7.org/CodeSystem/endpoint-payload-type",
"code" : "any",
"display" : "Any"
} ]
} ],
"address" : "https://msg.int.spine2.ncrs.nhs.uk/reliablemessaging/reliablerequest",
"managingOrganization" : {
"identifier" : {
"system" : "https://fhir.nhs.uk/Id/ods-organization-code",
"value" : true
}
},
"identifier" : [ {
"system" : "https://fhir.nhs.uk/Id/nhsMhsFQDN",
"value" : "msg.int.spine2.ncrs.nhs.uk"
}, {
"system" : "https://fhir.nhs.uk/Id/nhsMhsPartyKey",
"value" : "YES-0000806"
}, {
"system" : "https://fhir.nhs.uk/Id/nhsMhsCPAId",
"value" : "S20001A000182"
}, {
"system" : "https://fhir.nhs.uk/Id/nhsMHSId",
"value" : "S20001A000182"
} ],
"extension" : [ {
"url" : "https://fhir.nhs.uk/StructureDefinition/Extension-SDS-ReliabilityConfiguration",
"extension" : [ {
"url" : "nhsMHSSyncReplyMode",
"valueString" : "MSHSignalsOnly"
}, {
"url" : "nhsMHSRetryInterval",
"valueString" : "PT1M"
}, {
"url" : "nhsMHSRetries",
"valueInteger" : 2
}, {
"url" : "nhsMHSPersistDuration",
"valueString" : "PT5M"
}, {
"url" : "nhsMHSDuplicateElimination",
"valueString" : "always"
}, {
"url" : "nhsMHSAckRequested",
"valueString" : "always"
} ]
}, {
"url" : "https://fhir.nhs.uk/StructureDefinition/Extension-SDS-NhsServiceInteractionId",
"valueReference" : {
"identifier" : {
"system" : "https://fhir.nhs.uk/Id/nhsServiceInteractionId",
"value" : "urn:nhs:names:services:psis:REPC_IN150016UK05"
}
}
} ]
},
"search" : {
"mode" : "match"
}
} ]
}
Name | Description |
---|---|
object
|
A FHIR Bundle with Endpoint resources
|
resourceType string
|
Default:
Bundle |
id string
uuid
|
Unique identifier for this search request.
|
type string
|
Default:
searchset |
total integer
|
|
link array
|
|
object
|
|
relation string
|
Default:
self |
url string
|
The full url that produced the data
|
entry array
|
|
object
|
|
fullUrl string
|
Full url of the resource
|
resource object
|
A FHIR Enpoint resource that include routing and reliability information for the accredited system
|
resourceType string
|
Default:
Endpoint |
id string
uuid
|
SDS’s unique identifier for this accredited system record.
|
status string
|
Allowed values:
active Default:
active |
connectionType object
|
Protocol/Profile/Standard to be used with this endpoint connection
|
system string
|
|
code string
|
|
display string
|
|
payloadType array
|
The type of content that may be used at this endpoint (e.g. XDS Discharge summaries)
|
object
|
|
coding array
|
|
object
|
|
system string
|
|
code string
|
|
display string
|
|
address string
|
The base URL for connecting to this endpoint
|
managingOrganization object
|
Organization that manages this endpoint (might not be the organization that exposes the endpoint)
|
identifier object
|
|
system string
|
|
value string
|
|
identifier array
|
Identifies this endpoint across multiple systems
|
object
|
|
system string
|
|
value string
|
|
extension array
|
Additional content defined by implementations
|
object
|
|
url string
|
|
extension array
|
|
object
|
|
url string
|
|
valueString string
|
|
search object
|
Search operation description
|
mode string
|
Default:
match |