GP Connect - Access Document

This guidance is under active development by NHS Digital and content may be added or updated on a regular basis.

Find a patient

Use case

Find a patient using NHS number.

API specification

See GP Connect Access Document - FHIR API.

Interaction diagram

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

Important: GP Connect can only guarantee a successful response for searches using the identifier type https://fhir.nhs.uk/Id/nhs-number. Other identifier types may result in an error response if the provider does not recognise or support the identifier.

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)

    Note: Please note the restriction on returning patient records with a Regular/GMS registration type is a difference in behaviour between this Find a patient and Find a patient in the Foundations capability.

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

Examples

See Find a patient.

back to top