How to use FHIR Patient resources to perform Patient Searches

0. References

1. Overview

Most NHS trusts will typically have one central system called the Patient Administration System (PAS) thats holds a master Patient registry of all patients who have had care with the trust. In order to reduce patient administration and improve data quality, all other MIS within the trusts will be kept in sync with the central registry (PAS) via HL7v2 messaging. Alongside these messages will be patient encounter messages as shown in the diagram below:

Patient Identity Feeds
Patient Identity Feeds

HL7v2 is a mature and widely used standard but it is not suitable for querying patient demographic details (see HL7v2 Patient Demographics Query below). Mostly because it is a messaging standard and not an API. Care Connect API gives an API using RESTful interface following a resource API pattern to provide access to the central Patient repository. This is particularly suited to:

  • A health portal securely exposing demographics data to browser based plugins
  • Medical devices which need to access patient demographic information
  • Mobile devices used by physicians (example bedside eCharts) which need to establish patient context by scanning a bracelet
  • Web based EPR/EHR applications which wish to provide dynamic updates of patient demographic information such as a non-postback search, additional demographic detail, etc.
  • Any low resource application which exposes patient demographic search functionality
  • A facade providing a simple API to a complex interface

2.1 Foundation

Patient Search FHIR Actor Diagram
Patient Search FHIR Actor Diagram

The patient search can use any of the search parameters defined in the Patient API. For example if the patient informs the nurse of their date of birth, first name (19th Mar 1998 Bernie Kanfeld) and surname the query would be.

GET [baseUrl]/Patient?birthdate=1998-03-19&name=bernie%20kanfeld

[baseUrl] needs to be replaced with an actual url, in the example below this is The url would work within a web browser but a better tool to work with RESTful is Postman

A sample response is shown below

XML Example 1 - Bundle Patient

What we have just described is shown in the diagram below. When entered the url we did a Patient Search FHIR Query and the response is called Patient Search FHIR Query Response.

Basic Process Flow Patient Search FHIR
Basic Process Flow

ManagagingOrganisation, the patients GP Practice is given as a reference (Organization/24965)

    <reference value="Organization/24965"/>
    <display value="Moir Medical Centre"/>

If you wish to know more details about this organisation, you will need to follow the reference. The Reference used in the the example is relative, they can also point to external servers, e.g.:

    <reference value=""/>
    <display value="Moir Medical Centre"/>

We retrieve the Organization resource in the similar manner to searching for the Patient but as we know the Id of the resource we can access it directly.

GET [baseUrl]/Organization/24965

The response from this request is shown below, it is not returned in a FHIR Bundle as we haven’t performed a search and requested the resource by it’s Id. The SDS/ODS code can be found in the identifier section.

XML Example 2 - Organization

The method for returning Practitioner is the similar and an example is shown below in section 2.2

2.1 identifier

To find a patient by NHS number, Hospital number, etc we use the identifier. The earlier example contained an NHS number, the number 9876543210 belongs to the system, which is identifier for the NHS Number in England and Wales.

    <extension url="">
        ... snip ...
    <system value=""/>
    <value value="9876543210"/>

To search for Patients by NHS number, use the following query:

GET [baseUrl]/Patient?identifier=[system]|[code]

The system is and the code is 9876543210, e.g.

GET [baseUrl]/Patient?identifier=|9876543210

This will return all Patient resources with a NHS number of 9876543210 (this may be more than one). NHS Number may not be the main patient identifier within a NHS Organisation or Health Enterprise, this is for a number of reasons:

  • Patient doesn’t currently have a NHS Number (foreign visitor or from another home nation in the UK)
  • Patient’s NHS number hasn’t been validated (and so can not be used for interoperability/communication)
  • Patient has not been identified accurately.

For these reasons the trust/health organisation will use it’s own primary identifier, often referred to as Hospital or District number. Organisation’s will need to create their own system for the identifier, in the example Example NHS Trust have used ‘’ to indicate PAS Hospital Number. They use this with the API as shown below:

GET [baseUrl]/Patient?identifier=|123345

2.2. Java Example

The examples are built using HAPI FHIR which is an open source implementation of the HL7 FHIR specification by the University Health Network, Canada. Source code can be found on NHSConnect GitHub

The first example uses the same search parameters we used earlier, we are searching for patients with a surname of Kanfeld, forename of Bernie and date of birth 19/Mar/1998. The first couple of lines setup a Dstu2 FHIR context and set the baseUrl to be The output from running this code is shown earlier in this guide.

The second example would return the same FHIR response but this time the search is using the patients NHS Number.

Java Example 2 - Patient Search NHS Number

As previously mentioned these queries have not returned details on the patient GP or Surgery but have provided references to them which allows us to retrieve them.

GET [baseUrl]/Organization/24965
GET [baseUrl]/Practitoner/24967

The example belows shows how this could be done using java.

In practice many FHIR Servers will be facades or gateways. Facades will provide a standardised CareConnect interface to the underlying a SQL database or provide a CareConnectAPI gateway to other patient search systems such NHS Spine Mini Services Provider (SMSP) or HL7v2 Patient queries. In both cases the CareConnect client is insulated away from the interfacing technology or technology stack.

National NHS Patient Search Actor Diagram
Implementing Patient Search FHIR as a gateway

The Service Connector(/Gateway) Pattern can insulate client applications from complex processing which is especially useful for web applications. This would typically be done in a Trust Integration Engine or other middleware products such as Apache Camel. Advantages include:

  • Insulates clients from the complexities of interoperability.
  • Transforms external calls into internal formats (e.g. HL7v2 / HL7v3 XML to FHIR JSON/XML)
  • Allows the different security models to work with each other (e.g. OAuth2 based environment working with FHIR API using certificate based authentication)
  • Simplifies client access. API Gateway can retrieve demographics from multiple sources with a single query.

Consider the HL7v2 Example below:

HL7 version 2 Example 1 - Patient Demographics Query

QPD|Q22^Find Candidates^HL7|Q1520|@PID.8^F~@PID.5.1^JONES

This is searching for female patients with a surname of Jones. It is not clear from the message this is a search query and also the parameters @PID.8^F~@PID.5.1^JONES means a female called Jones. Also it’s difficult to call from a web browser based application. Using a FHIR API Gateway hides this complexity from the client web developer allowing them to use the $http service as shown in the example below:

Gateway Process Flow Patient Search FHIR
Sample Patient Search FHIR gateway process flow

Java Example 4 - Patient Resource from CSV line

Example code for building a FHIR Patient resource from a CSV file can be found on GitHub.