Find a patient by NHS number on the Access Document FHIR server

Use case

Find a patient using NHS number.

Security

  • GP Connect utilises TLS Mutual Authentication for system level authorization
  • GP Connect utilises JSON Web Tokens (JWT) to transmit clinical audit and provenance details

Prerequisites

Consumer

The consumer system:

API usage

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

Interaction diagram

Find patient interaction diagram

Request operation

The consumer system:

  • SHALL populate the [system] field with a valid patient identifier system URL (that is, https://fhir.nhs.uk/Id/nhs-number)

  • 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.

  • SHALL only use this Find a Patient interaction in conjunction with other Access Document interactions, and SHALL NOT use it with interactions in other capabilities.

FHIR relative request

GET /Patient?identifier=[system]|[value]

FHIR absolute request

GET https://[proxy_server]/https://[documents_provider_server]/[documents_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:documents:fhir:rest:search:patient-1

Payload request body

N/A

Error handling

The provider system MUST return a GPConnect-OperationOutcome-1 resource that provides additional detail when one or more data field is corrupt or a specific business rule/constraint is breached.

The table below shown common errors that may be encountered during this API call, and the returned Spine error code. Please see Error handling guidance for additional information needed to create the error response or to determine the response for errors encountered that are not shown below.

Errors returned due to query parameter failure MUST include diagnostic information detailing the invalid query parameter.

Error encountered Spine error code returned
The identifier parameter is not provided INVALID_PARAMETER
The identifier parameter contains a missing or unrecognised system INVALID_PARAMETER
The NHS number provided is invalid, for example it fails format or check digit tests INVALID_NHS_NUMBER
GP Connect is not enabled at the practice (see Enablement) ACCESS DENIED
The Access Document capability is not enabled at the practice (see Enablement) ACCESS DENIED
The patient is deceased and the request is received after the allowed access period PATIENT_NOT_FOUND

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 with a Regular/GMS registration type (i.e. where this is their registered GP practice), or
    • deceased patients if the patient was a main GMS registered patient prior to being de-registered due to death, and the request is within the allowed access period.

  • 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 relevant 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
    • deceasedDateTime where available
    • 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": [
    {
      "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"
        }
      }
    }
  ]
}