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 populate
entry.fullUrl
for each resource in theBundle
- SHALL populate
-
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 relevent business identifiers (i.e. 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": [
{
"fullUrl": "http://gpconnect.aprovider.nhs.net/GP001/STU3/1/Organization/23",
"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();