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

Prerequisites

Consumer

The consumer system:

API usage

Resolve (zero or more) Patient resources using a business identifier (that is, NHS number).

Request Operation

The [system] field SHALL be populated with a valid patient identifier system URL (that is, 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. This 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

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 structural validation checks (that is, 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 populate entry.fullUrl for each resource in the Bundle
  • SHALL only return Patient resources for active patients.

  • SHALL return Patient resources that conform to the CareConnect-GPC-Patient-1 profile.

  • SHALL populate the following Patient fields:
    • meta.profile with the profile URI
    • versionId with the current version of each Patient resource.
    • identifier with relevent business identifiers, including a minimum of the patient’s NHS number
    • name
      • The patient resource SHALL contain a single instance of the name element with the use of official and SHALL contain the name synchronised with PDS.
    • birthDate
    • gender
    • address where available
    • telecom where available
    • contact with the patient’s contacts - see Patient.contact population for further details
    • registrationDetails.preferredBranchSurgery with a reference to a Location resource representing the patient’s preferred branch surgery (see Branch surgeries for more details)
    • nhsCommunication with the patient’s language information, where available
    • managingOrganization Note: this is the current organisation, as addressed by ODS code in the base URL, and NOT the patient’s registered practice which may be different

  • SHALL meet General FHIR resource population requirements populating all fields where data is available, excluding those listed below

  • SHALL NOT populate the following fields:
    • ethnicCategory
    • religiousAffiliation
    • patient-cadavericDonor
    • residentialStatus
    • treatmentCategory
    • birthPlace
    • maritalStatus
    • multipleBirthBoolean
{
  "resourceType": "Bundle",
  "type": "searchset",
  "entry": [
    {
      "fullUrl": "http://gpconnect.aprovider.nhs.net/GP001/STU3/1/Patient/2",
      "resource": {
        "resourceType": "Patient",
        "id": "2",
        "meta": {
          "versionId": "1469448000000",
          "profile": [
            "https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-Patient-1"
          ]
        },
        "extension": [
          {
            "url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-CareConnect-GPC-RegistrationDetails-1",
            "extension": [
              {
                "url": "preferredBranchSurgery",
                "valueReference": {
                  "reference": "Location/785b4ff5-aced-4bdf-b7ed-34f92131ce97"
                }
              }
            ]
          },
          {
            "url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-CareConnect-GPC-NHSCommunication-1",
            "extension": [
              {
                "url": "language",
                "valueCodeableConcept": {
                  "coding": [
                    {
                      "system": "https://fhir.nhs.uk/STU3/CodeSystem/CareConnect-HumanLanguage-1",
                      "code": "bn",
                      "display": "Bengali"
                    }
                  ]
                }
              },
              {
                "url": "interpreterRequired",
                "valueBoolean": false
              }
            ]
          }
        ],
        "identifier": [
          {
            "extension": [
              {
                "url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-CareConnect-GPC-NHSNumberVerificationStatus-1",
                "valueCodeableConcept": {
                  "coding": [
                    {
                      "system": "https://fhir.nhs.uk/CareConnect-NHSNumberVerificationStatus-1",
                      "code": "01",
                      "display": "Number present and verified"
                    }
                  ]
                }
              }
            ],
            "system": "https://fhir.nhs.uk/Id/nhs-number",
            "value": "9476719931"
          }
        ],
        "active": true,
        "name": [
          {
            "use": "official",
            "text": "JACKSON Jane (Miss)",
            "family": "Jackson",
            "given": [
              "Jane"
            ],
            "prefix": [
              "Miss"
            ]
          }
        ],
        "telecom": [
          {
            "system": "phone",
            "value": "01454587554",
            "use": "home"
          }
        ],
        "gender": "female",
        "birthDate": "1952-05-31",
        "address": [
          {
            "use": "home",
            "type": "physical",
            "line": [
              "Trevelyan Square",
              "Boar Ln"
            ],
            "city": "Leeds",
            "district": "West Yorkshire",
            "postalCode": "LS1 6AE"
          }
        ],
        "managingOrganization": {
          "reference": "Organization/14"
        }
      }
    }
  ]
}

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

Java

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"))
.encodedXml()
.execute();

cURL

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