--- title: "Book or defer appointment (A016, FHIR STU3)" method: POST path: "/STU3/Appointment" tags: ["Arrange appointment", "Arrange triage"] --- # Book or defer appointment (A016, FHIR STU3) `POST /STU3/Appointment` ## Overview Use this endpoint to book an appointment to a directly bookable service if an appointment slot is available, defer the booking responsibility to a directly bookable service if no appointment slot is available, or refer a patient into a triage service. It is not possible to book into an indirectly bookable service using this endpoint. The patient will need to contact the service provider on the telephone number provided on [[HYPERLINK_A019]]. ## Supported security patterns - Healthcare worker, user-restricted access ## Pre-requisites In order to use this endpoint you must be an authenticated e-RS user and use one of the following e-RS roles: - `REFERRING_CLINICIAN` - `REFERRING_CLINICIAN_ADMIN` You need to check if the service is directly bookable, indirectly bookable, or triage by either using [[HYPERLINK_A033]] or [[HYPERLINK_A035]]. You can then offer appropriate actions to authenticated users, i.e. the ability to book an appointment into a directly bookable service if an appointment slot is available, defer the booking responsibility to a directly bookable service if no appointment slot is available, refer a patient into a triage service. If the service is directly bookable, you need to retrieve available appointment slots for the service using [[HYPERLINK_A015]]. You need to use the Unique Booking Reference Number (UBRN) of a referral request in order to use this endpoint. ## Important note when deferring to provider You should only defer booking to a directly bookable service in the following circumstances: - when the service has no available slots *or* - when trying to book an appointment into a service, the slot advertised is no longer available *or* - when trying to book an appointment into a service, no response is received within the message timeout period (currently 2 minutes) ## Important note when booking slots When appointment slots are booked using this endpoint, it may be necessary to provide the named clinician details. This is because slots can be setup with or without a named clinician. Your integrated application must support both scenarios. When booking a slot using [[HYPERLINK_A016]], the named clinician details must be added to the "Appointment.partcipant" list. As shown in the "Booking with named clinician" example. ## Use case As an authenticated user I need to be able to - Book an appointment into an available appointment slot for a directly bookable service *or* - Defer the booking responsibility to a directly bookable service if no appointment slot is available *or* - Refer the patient into a triage service So I can progress my patient's care at that service. ## Related endpoints You can generate a letter for the patient, summarising the current state of their referral and any steps the patient may need to follow using [[HYPERLINK_A019]]. Where deferring the booking responsibility to a directly bookable service, or referring the patient into a triage service, you can calculate the date when the patient can expect to be contacted (by the receiving service) using reference data from [[HYPERLINK_A004]]. ## Known Issues 1. The Participant.type attribute is being mapped as a single type for this endpoint. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be an array. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information. 2. The participant of an Appointment references a value set. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be a coding system. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information. ## Parameters - `#/paths/~1STU3~1Task/get/parameters/0` — unresolved $ref - `#/paths/~1STU3~1Task/get/parameters/1` — unresolved $ref - `#/paths/~1STU3~1Slot/get/parameters/2` — unresolved $ref - `#/paths/~1STU3~1Task/get/parameters/4` — unresolved $ref ## Response `201` An appointment within e-RS. ## Other responses - `401` — unresolved $ref - `403` — unresolved $ref - `406` — unresolved $ref - `409` — Conflict - Version supplied as part of the request does not match current version of the referral request - `415` — unresolved $ref - `422` — Where status code 422 (Unprocessable Entity) is returned then an eRS-OperationOutcome-1 will be included in the body, as detailed below. Check diagnostics property for specific information regarding the error. | Error code | Description | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | INVALID_VALUE | The input provided does not conform to the expected data types and format. | | INVALID_CODE | The input provided for a field is not one of the defined legal values. | | REFERENCE_NOT_FOUND | A supplied reference could not be resolved to valid resource (e.g. a patient, clinician or an organisation). | | NO_RELATIONSHIP | The user does not have a legitimate relationship with the request. | | INAPPROPRIATE_VALUE | A value, which is acceptable under different conditions, is inappropriate in the context of the other information provided. | | SERVICE_UNAVAILABLE | Indicates that a service is no longer available. | | INVALID_REQUEST_STATE | The Request, while otherwise valid, is not in the correct state for the specific action being performed. | | MISSING_VALUE | A field defined as mandatory for an endpoint has not been provided. | | PATIENT_ERROR | An error occurred while retrieving the requested patient. Do not attempt again. | | INVALID_STATE | Indicates that the referenced item is not in the correct state for the request to be processed. | | INAPPROPRIATE_SLOT | The slot provided is not suitable. | | SLOT_NOT_AVAILABLE | Slot is no longer available. | | UNABLE_TO_CONFIRM_APPOINTMENT | An unexpected error prevented eRS from successfully confirming the appointment. | | SLOTS_CURRENTLY_AVAILABLE | There are currently future slots available, so you cannot defer to this Service to book. | | THIS_SLOT_IS_AVAILABLE | Slot is currently available. | - `423` — The NHS e-Referral Service (e-RS) implements pessimistic locking functionality in order to prevent multiple users/systems attempting to update the same resource at the same time. The e-RS API automatically acquires the lock on the behalf of the caller, within the scope of the request. When an endpoint call is received to update a resource, that resource will be locked for the duration of the request. API callers should not attempt to make simultaneous requests to update the same resource. Any attempt to do so will result in a 423 (Locked) response. If a 423 response is received, then another system/user may be in the process of updating the resource. It will be necessary to fetch the resource again and re-try the request at a later time. - `429` — unresolved $ref - `500` — unresolved $ref - `502` — Where status code 502 (Bad Gateway) is returned then an eRS-OperationOutcome-1 will be included in the body. Check diagnostics property for specific information regarding the error. | Error code | Description | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | PAS_RESPONDED_WITH_ERROR | Error received from PAS. | - `503` — unresolved $ref - `504` — Where status code 504 (Gateway Timeout) is returned then an eRS-OperationOutcome-1 will be included in the body. Check diagnostics property for specific information regarding the error. In response to receiving this status code, it is recommended that clients retry at a later time. | Error code | Description | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | PAS_NOT_RESPONDING | No response from PAS. | --- [API](https://skmtc.dev/nhs/apis/e-referrals-service-api.md) · [All operations](https://skmtc.dev/nhs/apis/e-referrals-service-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nhs/e-referrals-service-api/revisions/916969ea472f/schema)