• API Hub
  • Search loading...

    API Hub

    Explore and Make use of Nationally Defined Messaging APIs


    Find a patient

    Use case for finding a patient resource by business identity.



    The Consumer system:

    API Usage

    Resolve (zero or more) Patient resources using a business identifier (i.e. NHS Number).

    Request Operation

    The [system] field SHALL be populated with a valid patient identifier system URL (i.e. https://fhir.nhs.uk/Id/nhs-number).

    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 /Patient?identifier=[system]|[value]

    FHIR Absolute Request

    GET https://[proxy_server]/https://[provider_server]/[fhir_base]/Patient?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:patient-1

    Payload Request Body


    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 structural validation checks (i.e. not enough digits to be a valid NHS Number).

    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 Patient resources in a Bundle of type searchset.
    • SHALL only return Patient resources for Active patients (Definition of a GP Connect Active Patient).
    • SHALL return Patient resources that conform to the CareConnect-GPC-Patient-1 profile.
    • SHALL include the URI of the CareConnect-GPC-Patient-1 profile StructureDefinition in the Patient.meta.profile element of the returned Patient resources.
    • SHALL include the versionId and fullUrl of the current version of each Patient resource.
    • SHALL include all relevant business identifier details (i.e. NHS Number) for each Patient resource.
    • SHALL supply gender, name, birth date or deceased date where these are available (as indicated by the Must-Support FHIR property)
    	"resourceType": "Bundle",
    	"type": "searchset",
    	"entry": [{
    		"fullUrl": "http://gpconnect.aprovider.nhs.net/GP001/STU3/1/Patient/2",
    		"resource": {
    			"resourceType": "Patient",
    			"id": "2",
    			"meta": {
    				"versionId": "636064088097580046",
    				"lastUpdated": "2016-08-10T16:52:39.716+01:00",
    				"profile": ["https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-Patient-1"]
    			"identifier": [{
    				"extension": [{
    					"url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-CareConnect-GPC-NHSNumberVerificationStatus-1",
    					"valueCodeableConcept": {
    						"coding": [{
    							"system": "https://fhir.nhs.uk/STU3/CodeSystem/CareConnect-NHSNumberVerificationStatus-1",
    							"code": "01"
    				"system": "https://fhir.nhs.uk/Id/nhs-number",
    				"value": "9476719931"
    			"name": [{
    				"use": "usual",
    				"family": ["Jackson"],
    				"given": ["Jane"],
    				"prefix": ["Miss"]
    			"gender": "female",
    			"birthDate": "22/02/1982"

    Example Code


    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/nhs-number|9476719931" };
    var bundle = client.Search("Patient", query);


    FhirContext ctx = new FhirContext();
    IGenericClient client = ctx.newRestfulGenericClient("http://gpconnect.aprovider.nhs.net/GP001/STU3/1/");
    Bundle bundle = client.search().forResource(Patient.class)
    .where(new TokenClientParam("identifier").exactly().systemAndCode("https://fhir.nhs.uk/Id/nhs-number", "9476719931"))


    curl -X GET -H 'Ssp-From: 0001' -H 'Ssp-To: 0002' -H 'Ssp-InteractionID: urn:nhs:names:services:gpconnect:fhir:rest:search:patient-1' -H 'Cache-Control: no-cache' -H 'Ssp-TraceID: e623b4de-f6bb-be0c-956d-c4ded0d58fc0' 'http://gpconnect.aprovider.nhs.net/GP001/STU3/1/Patient?identifier=https://fhir.nhs.uk/Id/nhs-number%7CP002'
    Tags: foundations

    All content is available under the Open Government Licence v3.0, except where otherwise stated