Patients/Demographics Use Cases

Retrieve a Patient by Resource Id

Each Patient resource has a unique logical identifier (id) assigned by the CDR. If the resource id is known, the Patient can be retrieved directly using a FHIR read interaction.

API Request Format

API Request Example

Notes

This retrieves a single Patient resource with the specified resource id.

• The resource id is the logical FHIR identifier (Patient.id) assigned by the CDR and is distinct from business identifiers such as an NHS number or local PAS/CRN identifier.
• If the specified resource does not exist, the server returns an HTTP 404 Not Found response.

If you do not know the resource id, use a FHIR search (for example by identifier, name, or other supported search parameters) to locate the Patient resource first, as shown in the sections below.

Supported Search Parameters

The CDR supports the standard search parameters defined in the FHIR R4 specification for the Patient resource.

This includes commonly used parameters such as:

• identifier
• name
• given
• family
• birthdate
• gender
• address

Please see the refer to the FHIR specification for further details on searching for resources.

The following sections provide examples of common Patient searches and demonstrate how search criteria can be combined to refine the results.

Search for Patient by Identifier (NHS Number and Local PAS/CRN)

To search for a Patient by NHS number, use the standard FHIR identifier search parameter against Patient.identifier. The identifier parameter is a token search, so the recommended pattern is to search using both the identifier system and the identifier value.

API Request Format

Example API Requests

Search by NHS Number

Search by Local PAS/CRN

As well as NHS number, you can also search using local PAS/CRN identifiers.

The following identifier systems are supported:

• https://fhir.abuhb.nhs.wales/Id/pas-identifier
• https://fhir.bcuhb.nhs.wales/Id/pas-identifier
• https://fhir.cavuhb.nhs.wales/Id/pas-identifier
• https://fhir.ctmuhb.nhs.wales/Id/pas-identifier
• https://fhir.hduhb.nhs.wales/Id/pas-identifier
• https://fhir.pthb.nhs.wales/Id/pas-identifier
• https://fhir.sbuhb.nhs.wales/Id/pas-identifier
• https://fhir.vunhst.nhs.wales/Id/pas-identifier

Notes

• Search using Patient.identifier, not Patient.id. Including both the system and the value helps make sure you get the right match.

Search for Patient by Name, Address, Date of Birth and Gender

You can combine multiple search parameters to narrow down results when searching for a Patient. Adding more parameters will generally reduce the number of matches returned.

API Request Examples

Search by Name

You can start with a simple name search:

You can make this more specific by splitting given and family name:

Search By Name, Address, Date of Birth and Gender

Additional parameters can then be added to refine the search further:

You can also search using more specific address details, such as address line and postcode:

Notes

• Name searches are not exact and may return multiple matches.
• Results may include similar or partial matches (e.g. “Jon” may match “Jones”).
• Each additional parameter acts as an “AND”, helping to narrow the results.
• birthdate should be in YYYY-MM-DD format.
• gender uses standard FHIR values (e.g. male, female, other, unknown).
• The address parameter searches across address fields (e.g. city, line, postcode).
• Even with multiple parameters, more than one match may still be returned.

Submit a Patient Record to the CDR

A Patient record can be submitted to the CDR by sending a FHIR message Bundle to the $process-message endpoint.

The CDR-PatientSubmit MessageDefinition defines the message used to create or update an application-managed Patient record where the patient is not already represented by an appropriate existing CDR Patient record. This enables submitting systems to establish a local CDR Patient record before submitting associated patient record items.

Gold Patient records are created and maintained from the Welsh Demographic Service, while Silver Patient records are created and maintained by Health Board PAS systems. Gold and Silver Patient records are not supported by this message.

The message supports upsert behaviour. If a Patient record already exists in the CDR with the same business identifier in Patient.identifier, the existing record is updated rather than a duplicate Patient record being created.

Message Model

The message Bundle must contain:

• a MessageHeader resource identifying the patient-submit event and referencing the Patient as its focus; and
• exactly one Patient resource conforming to the CDR-Patient-Bronze profile.

The Patient resource is mandatory and must occur exactly once in the message.

Message Definition

Message Processing Rules

The message supports upsert processing, meaning that the CDR will either create a new Patient record or update an existing one.

The CDR uses the business identifier provided in Patient.identifier to determine whether the Patient already exists:

• If no matching Patient record exists, a new Patient record is created.
• If a Patient record already exists with the same business identifier, the existing record is updated rather than a duplicate record being created.
• The message processor will populate Patient.meta.source with the Application Instance Identifier OID of the submitting source system, as identified from the message bundle's MessageHeader.source.endpoint context.
• The message processor adds a Patient.meta.tag using the CDR patient record type code system, with the code bronze and display Application-managed patient, to classify the record as an application-managed Patient within the CDR.

The Patient.meta.source and Patient.meta.tag are used to identify and classify application-managed Patient records within the CDR. Patient.meta.source identifies the application responsible for creating and maintaining the record and supports searches using the standard FHIR _source search parameter, while Patient.meta.tag classifies the record as a Bronze, or application-managed, Patient and can be searched using the standard FHIR _tag search parameter. An example patient record is provided below.

Example FHIR Resources

• Example Bundle – Patient Submit (Nia Roberts)
• Example Patient (Nia Roberts)

Example API Request

The following example shows the HTTP POST request used to submit an Application Managed Patient record to the CDR.