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 (i.e. ODS organization code).
Request operation
The [system]
field SHALL be populated with a valid organization identifier system URL (i.e. https://fhir.nhs.uk/Id/ods-organization-code
).
The consumer system SHALL apply percent encoding when constructing the request URL as indicated in RFC 3986 Section 2.1. The will ensure that downstream servers correctly handle the pipe |
character which must be used in the identifier
parameter value below.
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 (i.e. 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 an 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 (i.e. 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 include the URI of the
CareConnect-GPC-Organization-1
profile StructureDefinition in theOrganization.meta.profile
element of the returnedOrganization
resources. - SHALL include the
versionId
andfullUrl
of the current version of eachOrganization
resource. - SHALL include all relevant business
identifier
details (i.e. ODS Code) for eachOrganization
resource.
{
"resourceType": "Bundle",
"type": "searchset",
"entry": [{
"fullUrl": "http://gpconnect.aprovider.nhs.net/GP001/STU3/1/Organization/23",
"resource": {
"resourceType": "Organization",
"id": "23",
"meta": {
"versionId": "636064088098730113",
"lastUpdated": "2016-08-10T13:52:54.516+01:00",
"profile": ["https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-Organization-1"]
},
"identifier": [{
"system": "https://fhir.nhs.uk/Id/ods-organization-code",
"value": "O001"
}],
"name": "Honley GP Practice"
}
}]
}
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();