Standard Pattern - DocumentReference

Important: Release information

This section of the Implementation Guide is currently a preview, in an Alpha state and subject to change. There is currently only support for Appointment (booking) pointers.

Introduction

There is functionality in BaRS to accommodate the use of pointers (DocumentReference resources), to locate existing bookings and referrals from a central Registry.

This section will walk you through the process of using FHIR DocumentReferences, from the central Registry, to find and retrieve bookings and referrals held at Receiver services.

The BaRS API acts as a gateway to the National Record Locator (NRL) FHIR API, for BaRS enabled Services. In the image below the BaRS API is called by Consumers and Producers.

Consumer - Queries the API for existing DocumentReferences for use in finding existing Bookings and Referrals. Usually a BaRS Sender.
Producer - Posts and maintains DocumentReferences for Bookings and Referrals that they have received. Usually a BaRS Receiver.

DocumentReferences for Senders

Step 1: Understand the Document Reference Resource

The FHIR DocumentReference resource represents a reference to a clinical document or resource, in the case of BaRS a pointer to an active booking or referral. It contains metadata about the booking or referral, such as its type (booking or referral), author, and subject (the patient's NHS number), as well as a reference to the actual document's .id and where it resides (the service who owns it); the two key data points needed to retrieve it.

Step 2: Search for the booking or referral pointer (DocumentReference)

FHIR DocumentReference resources holding pointers for BaRS bookings and referrals are stored in a central Registry, within NRL (National Record Locator), as decribed above, and interrogated through the BaRS API DocumentReference.

To find a booking or referral location, you need to search for the appropriate DocumentReference resource from the Registry, using search parameters. It is mandatory to include the subject:identifier (the patient's NHS number). Other parameters can be used to filter the response further e.g type of document (booking and referral).

Step 3: Inspect the booking or referral pointer (DocumentReference)

Once you retrieve the Document Reference(s) (pointers) from the search, inspect the returned resources to identify the one you need. Look for relevant metadata, as described below, to confirm the correct resource.

identifier: The DocumentReference will have several identifiers which are required to locate the booking or referral at a Receiver service.

The .id of the booking or referral is indicated by the system '*https://fhir.nhs.uk/Id/BaRS-Identifier*'. The value can be used to directly request the booking or referral by .id, once you know Receiver service holding it (see next identifier).

"identifier": [
	{
		"system": "https://fhir.nhs.uk/Id/BaRS-Identifier",
		"value": "8c63d621-4d86-4f57-8699-e8e22d49935d"
	}

The second identifier, required to make the subsequent request for the booking or referral in question, has a system of '*https://fhir.nhs.uk/Id/dos-service-id*' and enables the Sender to direct their request to the Receiver service which owns it. The Sender will use the system and value here to build the base64 encoded HTTP Header NHSD-Target-Identifier, as defined for the booking or referral.

"identifier": [
	{
		"system": "https://fhir.nhs.uk/Id/dos-service-id",
		"value": "2000072491"
	}

The third identifier (currently optional) relates to the product-id, system '*https://fhir.nhs.uk/id/product-id*'. This is forthcoming functionality and further detail on its utility will follow but [working documentation] (https://github.com/NHSDigital/nhse-epr-integration/blob/main/pages/appendix1.md) is being actively updated.

"identifier": [
	{
		"system": "https://fhir.nhs.uk/Id/product-id",
		"value": "P.GH7-4TY"
	}

type: within the DocumentReference Resource, indicates whether the pointer is for a booking or referral. BaRS currently only supports bookings (749001000000101) and referrals (736253002), described using SNOMED codes. This information is required to direct the subsequent request to the correct endpoint for the booking or referral

"type": {
	"coding": [
		{
			"system": "https://snomed.info/ict",
			"code": "749001000000101",
			"display": "Appointment (record artifact)"
		}
	]
}

subject: The subject will describe the patient, by means of an NHS number. This element is not explicitly required to request the specific resource dictated by the pointer but could be used to search a service more widely for related bookings and referrals, using the search by patient endpoints.

"subject": {
	"identifier": {
		"system": "https://fhir.nhs.uk/Id/nhs-number",
		"value": "9556274839"
	}

custodian: The custodian element will describe the organisation that owns the resource data. This will be a concatenation of ODS codes.

	"custodian": {
		"identifier": {
			"system": "https://fhir.nhs.uk/Id/ods-organization-code",
			"value": "A1001"
		}
	}

context: includes a period set to the Appointment start and end times.

"context": {
  "period": {
    "start": "2025-02-12T12:30:30+00:00",
    "end": "2025-02-12T12:40:30+00:00"
  }
}

Step 4: Retrieve the booking or referral

The booking or referral resource can be retrieved by making a GET request for the booking or referral.

The two key values required to make the request are the first two identifiers in the DocumentReference; the resource .id ('*https://fhir.nhs.uk/Id/BaRS-Identifier*') and service id ('*https://fhir.nhs.uk/Id/dos-service-id*'). Use the resource .id populate the location of the request and service id to populate the NHSD-Target-Identifier HTTP Header, as described in the worked example below.

For BaRS, a GET of the relevant resource using the Target Identifiers. In this simplified example, the identifier containing the service id is used in the NHSD-Target-Identifier header, instructing the BaRS proxy to route to the request to that target note: The header is not base64Encoded in this example:

cURL --location 'https://int.api.service.nhs.uk/booking-and-referral/FHIR/R4/Appointment/8c63d621-4d86-4f57-8699-e8e22d49935d' \
--header 'X-Request-ID: Command 'X-Request-ID' could not render: There is no placeholder called 'X-Request-ID'' \
--header 'X-Correlation-ID: Command 'X-Correlation-ID' could not render: There is no placeholder called 'X-Correlation-ID'' \
--header 'NHSD-Target-Identifier: {system:"http://fhir.nhs.uk/Id/dos-service-id", value:"111111111"}' \
--header 'Accept: application/fhir+json' \

Step 5: Handle the Retrieved booking or referral

Once you have retrieved the booking or referral resource, it can be used in subsequent workflows. Refer to the FHIR documentation or resource-specific or application-specific guides for further information on handling the retrieved resource.

Note: It's important to consider the security and privacy aspects when working with clinical documents and resources. Ensure that you adhere to applicable regulations and best practices to protect patient data.

DocumentReferences for Receivers

Creating a DocumentReference.

The FHIR DocumentReference resource allows you to create a reference to a clinical document or resource. This section describes the process of creating a FHIR DocumentReference (pointer) for a booking or referral resource on the central Registry. A DocumentReference will be created when a Receiver accepts a booking or referral. Each booking or referral request processed requires a distinct DocumentReference on the Registry.

Step 1: Identify the booking or referral to create a pointer for

When a Receiver processes a request for a booking (Appointment) or referral (ServiceRequest), the next step in the workflow is to create a pointer for the newly created resource (Appointment or ServiceRequest) on the central Registry. This will be undertaken via a POST DocumentReference request to the BaRS Proxy.

Step 2: Set content of the DocumentReference (pointer)

Create a new instance of the DocumentReference resource and populate the relevant fields. Key fields to include are as follows:

identifier: The DocumentReference needs several identifiers which allow the booking or referral to be located at a Receiver service.

The resource .id of the booking (Appointment) or referral (ServiceRequest) (created by the Receiver when processing the request) must be set in the 'value' element of an Identifier, clarified by the system '*https://fhir.nhs.uk/Id/BaRS-Identifier*'.

"identifier": [
	{
		"system": "https://fhir.nhs.uk/Id/BaRS-Identifier",
		"value": "8c63d621-4d86-4f57-8699-e8e22d49935d"
	}

The second identifier of note is the Receiving service who own the resource. The 'system' indicates the Service Discovery tool and the 'value', the identifier. In the code snippet below, the system '*https://fhir.nhs.uk/Id/dos-service-id*' indicates the Receiver service is on the Urgent and Emergency Care Directory of Services (UEC DoS) as service 2000072491. The Sender of any request will use the 'system' and 'value' here to build the base64 encoded HTTP Header NHSD-Target-Identifier, as defined for the booking or referral.

"identifier": [
	{
		"system": "https://fhir.nhs.uk/Id/dos-service-id",
		"value": "2000072491"
	}

"identifier": [
	{
		"system": "https://fhir.nhs.uk/Id/product-id",
		"value": "P.GH7-4TY"
	}

type:, within the DocumentReference resource, indicates whether the pointer is for a booking or referral. BaRS currently only supports bookings (749001000000101) and referrals (736253002), described using SNOMED codes.

"type": {
	"coding": [
		{
			"system": "https://snomed.info/ict",
			"code": "749001000000101"
		}
	]
}

subject: specifies the subject of the DocumentReference, which will be the patient associated with the Resource. The patient's NHS number must be used to identify them, as outlined below.

"subject": {
	"identifier": {
		"system": "https://fhir.nhs.uk/Id/nhs-number",
		"value": "9556274839"
	}
},

custodian: Set the author of the DocumentReference, which will be the ODS code for the organisation writing the DocumentReference resource entry.

	"custodian": {
		"identifier": {
			"system": "https://fhir.nhs.uk/Id/ods-organization-code",
			"value": "A1001"
		}
	}

context: MUST include a period set to the Appointment start and end times.

"context": {
  "period": {
    "start": "2025-02-12T12:30:30+00:00",
    "end": "2025-02-12T12:40:30+00:00"
  }
}

Step 3: Save and Transmit the DocumentReference (pointer)

Once all the necessary fields are populated, perform a POST of the DocumentReference to the /DocumentReference endpoint on the BaRS proxy. This will create a DocumentReference in the NRL.

After saving, the DocumentReference will be assigned a unique id (e.g., DocumentReference/12345). This can be used to reference or retrieve the DocumentReference in the future.

Step 4: Verify the DocumentReference

To ensure that the DocumentReference was created successfully, retrieve it using its id or search for it using relevant parameters. Make sure to validate the returned DocumentReference to confirm that all the contents are accurate.

Updating a DocumentReference

A DocumentReference can be updated by performing a PUT request with the updated resource to the /DocumentReference endpoint on the BaRS proxy with the appropriate DocumentReference.id. A read operation must be performed prior to this to ensure that the new DocumentReference is the most up to date.

Note: A Receiver can only update DocumentReference resources that they created and own.

Delete a DocumentReference

A DocumentReference can be removed by performing a DELETE request to the /DocumentReference endpoint on the BaRS proxy with the appropriate DocumentReference.id. A read operation must be performed prior to this to ensure that the action is appropriate.

Note: A Receiver can only delete DocumentReference resources they created and own.

NHS Booking and Referral Standard