NHS Booking and Referral Standard

Guide v1.10.0 | Core v1.3.1 | Package v1.37.0
  1. Home
  2. Core
  3. 1.3.1

Standard Pattern - Appointments

Introduction

The BaRS API suite can be used where there is no specific use-case supported by the Applications to fulfil generic Appointment workflows, referred to as Appointment Management Foundation. This section outlines the functionality supported, workflows involved and how these correspond with the API Specification.

This includes using Standard Pattern DocumentReference to write pointers for bookings to a central respository, commonly referred to as the Registry.

The Appointment Management Foundation is based on BaRS Core and an understanding of the central tenets is essential before beginning. This includes: -

The key functions surrounding appointment bookings are listed below. This section will provide information on how to meet them using the Appointment Resource.

The ability to -

  • view
  • book
  • update
  • cancel
  • reschedule
  • rebook

Interface

The following table describes how the BaRS API accomodates these four capabilities using the /Appointment endpoint and the /Appointment/{id} endpoint

Capability Endpoint VERB Description
List /DocumentReference GET Using the DocumentReference pattern, a list of existing appointments for a patient can be viewed with the central Registry.
View /Appointment/{id} GET This action, using the id from the List capability, will allow that specific Appointment Resource to be retrieved from the healthcare service who owns it.
View (Search) /Appointment GET If the Appointment.id is not known, the Sender can perform a look up based the patient national identifier (NHS No.) or demographics (Name (as defined by FHIR), Date of Birth, Home Address Postcode). This returns a (FHIR) bundle of resources for the specific Appointment Resource to be retrieved from the healthcare service who owns it. See Cancellation for further detail.
Get Slots /Slots GET Obtain a list of available booking slots from a specified receiving system using the GET /Slots endpoint
Book /Appointment or /$process-message POST This will be a POST operation, with a BaRS Application /$process-message is typically used, outside of supported use cases /Appointment is adopted.
Cancel /Appointment/{id} PUT The cancel of a booking will be setting the status of the appointment to "cancelled". Cancel is also possible using /$process-message
Update /Appointment/{id} PUT An update to an appointment will be a direct update to the existing resource
Reschedule /Appointment/{id} PATCH An update the slot against an appointment, altering to the existing resource
Rebook Composite of Cancel and then Book Composite Requesting a new booking and then cancelling the existing one will constitute a rebook

In line with the BaRS standard all operations used to modify a resource must be preceded by a read of the resource by means of a GET operation.

Appointment Resource

Below are examples of each of the described interactions. The appointment resource adheres to the UKCore-Appointment definition.

Any operations that modify an existing resource must perform a read before a write, as outlined below.

Book

Making an initial booking through Appointment Management Foundation, outside of the prescribed BaRS Applications, must follow the workflow outlined using the discete booking endpoints.

If undertaking a booking within the context of an Application, the guidance stated there takes precedence over this documentation. NB: BaRS Applications are likely to utilise the $process-message endpoint (contact BaRS Team for guidance on use outside of the published Applications - bookingandreferralstandard@nhs.net), rather than independent resources. Steps to perform an initial booking:

Request Body

{
	"resourceType": "Appointment",
    "id":"aca94bdb-2e38-4399-9ece-2ba083ce65b5",
	"meta": {
		"lastUpdated": "2024-01-11T15:01:30.8185338+00:00",
		"profile": [
			"https://fhir.hl7.org.uk/StructureDefinition/UKCore-Appointment"
		]
	},
	"status": "booked",
    "slot": [
        {
            "reference": "Slot/deb4c4b3-870b-4599-84df-5e54cef7afda"
        }
    ],
	"description": "Reason for calling",
	"start": "2024-02-12T12:30:30+00:00",
	"end": "2024-02-12T12:40:30+00:00",
	"created": "2024-10-08T15:01:30+00:00",
	"participant": [
		{
			"actor": {
				"reference": "Patient/788660eb-d2c9-4773-abd4-318484673fb2"
			},
			"status": "accepted"
		}
	]
}

Update

Steps to update:

  • Perform a GET operation using the .id of the appointment to /Appointment/{id}. Alternatively, if the .id is not known, a search of the Registry can be undertaken following the Document Reference Standard Pattern - Sender. NB: If a match cannot be obtained using this method the process of updating must be performed manually
  • Update the Appointment resource as required. There is only currently support to alter .status and .reasonCode. NB: The .slot element of the resource must not be updated, if an alternative slot is required either the Reschedule or Rebook processes must be followed
  • Perform a PUT operation using the id of the appointment to /Appointment/{id}

resource returned:

{
	"resourceType": "Appointment",
    "id":"aca94bdb-2e38-4399-9ece-2ba083ce65b5",
	"meta": {
		"lastUpdated": "2024-01-11T15:01:30.8185338+00:00",
		"profile": [
			"https://fhir.hl7.org.uk/StructureDefinition/UKCore-Appointment"
		]
	},
	"status": "booked",
	"reasonCode": [
		{
			"coding": [
				{
					"system": "http://snomed.info/sct",
					"code": "165342003",
					"display": "Patient declined laboratory test (situation)"
				}
			]
		}
	],
	"description": "Reason for calling",
	"created": "2024-10-08T15:01:30+00:00",
	"participant": [
		{
			"actor": {
				"reference": "Patient/788660eb-d2c9-4773-abd4-318484673fb2"
			},
			"status": "accepted"
		}
	]
}

Request Body

{
	"resourceType": "Appointment",
	"id": "aca94bdb-2e38-4399-9ece-2ba083ce65b5",
	"meta": {
		"lastUpdated": "2024-01-11T15:01:30.8185338+00:00",
		"profile": [
			"https://fhir.hl7.org.uk/StructureDefinition/UKCore-Appointment"
		]
	},
	"status": "booked",
	"reasonCode": [
		{
			"coding": [
				{
					"system": "http://snomed.info/sct",
					"code": "165332000",
					"display": "Laboratory test requested (situation)"
				}
			]
		}
	],
	"slot": [
		{
			"reference": "Slot/deb4c4b3-870b-4599-84df-5e54cef7afda"
		}
	],
	"description": "Reason for calling",
	"start": "2024-02-12T12:30:30+00:00",
	"end": "2024-02-12T12:40:30+00:00",
	"created": "2024-10-08T15:01:30+00:00",
	"participant": [
		{
			"actor": {
				"reference": "Patient/788660eb-d2c9-4773-abd4-318484673fb2"
			},
			"status": "accepted"
		}
	]
}

Cancel

Cancellation is documented for completeness. The technical functionality for cancellation mirrors that of Update booking.

Steps to cancel:

  • Perform a GET operation using the .id of the appointment to /Appointment/{id}. Alternatively, if the .id is not known, a search of the Registry can be undertaken following the Document Reference Standard Pattern - Sender. NB: If a match cannot be obtained using this method the process of updating must be performed manually
  • Set the Appointment.status value to "cancelled". NB - It is also permissible to update .reasonCode in the request but no other element
  • Perform a PUT operation using the id of the appointment to /Appointment/{id}
  • Once processed, the Receiver of the booking must DELETE the pointer in the central Registry, as described in Document Reference Standard Pattern - Receiver

resource returned:

{
	"resourceType": "Appointment",
    "id":"aca94bdb-2e38-4399-9ece-2ba083ce65b5",
	"meta": {
		"lastUpdated": "2024-01-11T15:01:30.8185338+00:00",
		"profile": [
			"https://fhir.hl7.org.uk/StructureDefinition/UKCore-Appointment"
		]
	},
	"status": "booked",
    "slot": [
        {
            "reference": "Slot/deb4c4b3-870b-4599-84df-5e54cef7afda"
        }
    ],
	"description": "Reason for calling",
	"start": "2024-02-12T12:30:30+00:00",
	"end": "2024-02-12T12:40:30+00:00",
	"created": "2024-10-08T15:01:30+00:00",
	"participant": [
		{
			"actor": {
				"reference": "Patient/788660eb-d2c9-4773-abd4-318484673fb2"
			},
			"status": "accepted"
		}
	]
}

Request body:

{
	"resourceType": "Appointment",
    "id":"aca94bdb-2e38-4399-9ece-2ba083ce65b5",
	"meta": {
		"lastUpdated": "2024-01-11T16:01:30.8185338+00:00",
		"profile": [
			"https://fhir.hl7.org.uk/StructureDefinition/UKCore-Appointment"
		]
	},
	"status": "cancelled",
    "slot": [
        {
            "reference": "Slot/deb4c4b3-870b-4599-84df-5e54cef7afda"
        }
    ],
	"description": "Reason for calling",
	"start": "2024-02-12T12:30:30+00:00",
	"end": "2024-02-12T12:40:30+00:00",
	"created": "2024-10-08T15:01:30+00:00",
	"participant": [
		{
			"actor": {
				"reference": "Patient/788660eb-d2c9-4773-abd4-318484673fb2"
			},
			"status": "accepted"
		}
	]
}

OR if the appointment was entered in error

Request body:

{
	"resourceType": "Appointment",
    "id":"aca94bdb-2e38-4399-9ece-2ba083ce65b5",
	"meta": {
		"lastUpdated": "2024-01-11T16:01:30.8185338+00:00",
		"profile": [
			"https://fhir.hl7.org.uk/StructureDefinition/UKCore-Appointment"
		]
	},
	"status": "entered-in-error",
    "slot": [
        {
            "reference": "Slot/deb4c4b3-870b-4599-84df-5e54cef7afda"
        }
    ],
	"description": "Reason for calling",
	"start": "2024-02-12T12:30:30+00:00",
	"end": "2024-02-12T12:40:30+00:00",
	"created": "2024-10-08T15:01:30+00:00",
	"participant": [
		{
			"actor": {
				"reference": "Patient/788660eb-d2c9-4773-abd4-318484673fb2"
			},
			"status": "accepted"
		}
	]
}

Reschedule

The Reschedule operation supports amending the slot a booking is made against. The slot is the only element capable of being changed as part of the reschedule operation, if either the .status or .reasonCode require amendment, the Update operation can be followed, otherwise, the Rebook operation.

Steps to Reschedule:

  • Perform a GET operation using the .id of the appointment to /Appointment/{id}. Alternatively, if the .id is not known, a search of the Registry can be undertaken following the Document Reference Standard Pattern - Sender. NB: If a match cannot be obtained using this method the process of updating must be performed manually
  • Request Available slots from the service
  • Select a new slot
  • Update the resource with the new slot. NB: Only the .slot element of the resource must be updated
  • Perform a PATCH operation using the id of the appointment to /Appointment/{id}
  • Once processed, the Receiver of the booking must update (PUT) the pointer in the central Registry, as described in Document Reference Standard Pattern - Receiver. The principal update to the pointer is to change the .context element to alter the slot time -
"context": {
  "period": {
    "start": "2025-02-12T12:30:30+00:00",
    "end": "2025-02-12T12:40:30+00:00"
  }
}

In this example the Appointment resource is with the existing slot, and updated with the newly selected slot.

resource returned:

{
	"resourceType": "Appointment",
    "id":"aca94bdb-2e38-4399-9ece-2ba083ce65b5",
	"meta": {
		"lastUpdated": "2024-01-11T15:01:30.8185338+00:00",
		"profile": [
			"https://fhir.hl7.org.uk/StructureDefinition/UKCore-Appointment"
		]
	},
	"status": "booked",
    "slot": [
        {
            "reference": "Slot/265a53d7-1d21-4fc6-a5b7-761f650e75eb"
        }
    ],
	"description": "Reason for calling",
	"start": "2025-02-12T10:00:30+00:00",
	"end": "2025-02-12T10:10:30+00:00",
	"created": "2024-10-08T15:01:30+00:00",
	"participant": [
		{
			"actor": {
				"reference": "Patient/788660eb-d2c9-4773-abd4-318484673fb2"
			},
			"status": "accepted"
		}
	]
}

Request Body

{
	"resourceType": "Appointment",
    "id":"aca94bdb-2e38-4399-9ece-2ba083ce65b5",
	"meta": {
		"lastUpdated": "2024-01-11T15:01:30.8185338+00:00",
		"profile": [
			"https://fhir.hl7.org.uk/StructureDefinition/UKCore-Appointment"
		]
	},
	"status": "booked",
    "slot": [
        {
            "reference": "Slot/deb4c4b3-870b-4599-84df-5e54cef7afda"
        }
    ],
	"description": "Reason for calling",
	"start": "2025-02-12T12:30:30+00:00",
	"end": "2025-02-12T12:40:30+00:00",
	"created": "2024-10-08T15:01:30+00:00",
	"participant": [
		{
			"actor": {
				"reference": "Patient/788660eb-d2c9-4773-abd4-318484673fb2"
			},
			"status": "accepted"
		}
	]
}

Rebook

FHIR Guidance for Rebook

Process for rebook

Rebooking through Appointment Management Foundation, outside of a prescribed BaRS Applications, must follow the workflow outlined. If undertaking a rebook within the context of an Application, the guidance stated there takes precedence over this documentation. NB: BaRS Applications are likely to utilise the $process-message endpoint (contact BaRS Team bookingandreferralstandard@nhs.net for guidance on use of $process-message, outside of the published Applications), rather than independent resources.

Steps to perform a rebook:

back to top