Prerequisites
Consumer
The consumer system:
- SHALL have previously resolved the organisation’s FHIR endpoint Base URL through the Spine Directory Service
API usage
Resolve (zero or more) Organization
resources using a business identifier (for example, ODS organization code).
Request operation
The consumer system:
-
SHALL populate the
[system]
field with a valid organization identifier system URL (for example,https://fhir.nhs.uk/Id/ods-organization-code
). -
apply percent encoding when constructing the request URL as indicated in RFC 3986 Section 2.1. This will ensure that downstream servers correctly handle the pipe
|
character which must be used in theidentifier
parameter value below.
https://fhir.nhs.uk/Id/ods-organization-code
. Other identifier types may result in an error response if the provider does not recognise or support the identifier.FHIR relative request
GET /Organization?identifier=[system]|[value]
FHIR absolute request
GET https://[proxy_server]/https://[provider_server]/[fhir_base]/Organization?identifier=[system]|[value]
Request headers
Consumers SHALL include the following additional HTTP request headers:
Header | Value |
---|---|
Ssp-TraceID |
Consumer’s TraceID (for example, GUID/UUID) |
Ssp-From |
Consumer’s ASID |
Ssp-To |
Provider’s ASID |
Ssp-InteractionID |
urn:nhs:names:services:gpconnect:fhir:rest:search:organization-1 |
Payload request body
N/A
Error handling
Provider systems:
- SHALL return a GPConnect-OperationOutcome-1 resource that provides additional detail when one or more request fields are corrupt or a specific business rule/constraint is breached
For example, the:
- Business identifier
[system]
is not recognised/supported by the provider system - Business identifier fails any structural validation checks (for example, length and check digits)
Request response
Response headers
Provider systems are not expected to add any specific headers beyond that described in the HTTP and FHIR® standards.
Payload response body
Provider systems:
- SHALL return a
200
OK HTTP status code on successful execution of the operation - SHALL return zero or more matching
Organization
resources in aBundle
oftype
searchset -
SHALL return
Organization
resources that conform to the CareConnect-GPC-Organization-1 profile - SHALL populate the following
Organization
fields:meta.profile
with the profile URIversionId
with the current version of eachOrganization
resource.identifier
with relevant business identifiers (for example, ODS code) for eachOrganization
resource.name
address
where availabletelecom
where available
-
SHALL meet General FHIR resource population requirements populating all fields where data is available, excluding those listed below
- SHALL NOT populate the following fields:
contact
endpoint
{
"resourceType": "Bundle",
"type": "searchset",
"entry": [
{
"resource": {
"resourceType": "Organization",
"id": "23",
"meta": {
"versionId": "636064088098730113",
"profile": [
"https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-Organization-1"
]
},
"identifier": [
{
"system": "https://fhir.nhs.uk/Id/ods-organization-code",
"value": "O001"
}
],
"name": "The Trevelyan Practice",
"address": [
{
"line": [
"Trevelyan Square",
"Boar Ln"
],
"city": "Leeds",
"district": "West Yorkshire",
"postalCode": "LS1 6AE"
}
],
"telecom": [
{
"system": "phone",
"value": "03003035678",
"use": "work"
}
]
}
}
]
}
Example code
C#
var client = new FhirClient("http://gpconnect.aprovider.nhs.net/GP001/STU3/1/");
client.PreferredFormat = ResourceFormat.Json;
var query = new string[] { "identifier=https://fhir.nhs.uk/Id/ods-organization-code|O001" };
var bundle = client.Search("Organization", query);
FhirSerializer.SerializeResourceToJson(bundle).Dump();
Java
FhirContext ctx = new FhirContext();
IGenericClient client = ctx.newRestfulGenericClient("http://gpconnect.aprovider.nhs.net/GP001/STU3/1/");
Bundle bundle = client.search().forResource(Organization.class)
.where(new TokenClientParam("identifier").exactly().systemAndCode("https://fhir.nhs.uk/Id/ods-organization-code", "O001"))
.encodedJson()
.execute();