---
title: "Cancel referral (A036, FHIR STU3)"
method: POST
path: "/STU3/ReferralRequest/{ubrn}/$ers.cancelReferral"
tags: ["Manage referral"]
---

# Cancel referral (A036, FHIR STU3)

`POST /STU3/ReferralRequest/{ubrn}/$ers.cancelReferral`

## Request

- Base URL: `https://sandbox.api.service.nhs.uk/referrals/FHIR`
- URL: `https://sandbox.api.service.nhs.uk/referrals/FHIR/STU3/ReferralRequest/{ubrn}/$ers.cancelReferral`
- Auth: HTTP bearer

## Overview
Use this endpoint to cancel a referral and the current appointment, if there is one. Cancelling a referral is a one-way process and results in an end-state. No further progression of care can occur once this action has been performed.

A reason for cancelling an appointment must be provided. A comment on the cancellation is conditionally mandatory depending on the reason selected. See pre-requisites and related referrals for more information.

You can check if you can cancel a referral by calling [[HYPERLINK_A029]].

e-RS does not allow a referral to be cancelled, without also cancelling the current appointment. Therefore, if there is a current appointment associated with the referral, this *must* be cancelled in advance, or at the same time.

In order to cancel (only) an appointment you must use [[HYPERLINK_A034]].

## Supported security patterns
- Healthcare worker, user-restricted access
- Application-restricted, unattended access

## Pre-requisites
### Application-restricted, unattended access
In order to use this endpoint you must be an authenticated e-RS calling application, working in the context of a Service Provider Organisation.

To access this endpoint in application-restricted, unattended mode, you will be required to submit your use case for review. The only use case currently permitted is for non-clinical provider actions.

### Healthcare worker, user-restricted access
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`
- `SERVICE_PROVIDER_CLINICIAN`
- `SERVICE_PROVIDER_CLINICIAN_ADMIN`

You must use [[HYPERLINK_A004]] to retrieve a list of reference data, which detail the reason the cancellation is being performed. You can only use reference data from the set `REFERRAL-CANCELLATION-REASON`.


To find out which reference data from this set can be used, the following filters can be used depending on the cancellation scenario:

***1. I want to cancel the referral and the current appointment as a Referrer***

* Obtain reference data from `REFERRAL-CANCELLATION-REASON` and filter:

  * `referrerUsage` must be `CANCEL_REFERRAL`, and

  * `businessFunction` must be `REFERRING_CLINICIAN` or `REFERRING_CLINICIAN_ADMIN` (depending which authenticated user will be performing the action), and

  * `canCancelAppointment` must be true, and

  * `effectiveFrom` must be in the past, and 

  * if provided, `effectiveTo` must **not** be in the past


***2. I want to cancel a referral, for which there is no current appointment as a Referrer***

* Obtain reference data from `REFERRAL-CANCELLATION-REASON` and filter:

  * `referrerUsage` must be `CANCEL_REFERRAL`, and

  * `businessFunction` must be `REFERRING_CLINICIAN` or `REFERRING_CLINICIAN_ADMIN` (depending which authenticated user will be performing the action), and

  * `canCancelAppointment` could be true or false, and

  * `effectiveFrom` must be in the past, and

  * if provided, `effectiveTo` must **not** be in the past

***3. I want to cancel the referral and the current appointment as a Service Provider***

* Obtain reference data from `REFERRAL-CANCELLATION-REASON` and filter:

  * `referrerUsage` must be `CANCEL_REFERRAL`, and

  * `businessFunction` must be `SERVICE_PROVIDER_CLINICIAN` or `SERVICE_PROVIDER_CLINICIAN_ADMIN` (depending which authenticated user will be performing the action), and

  * `appointmentRequestCancellationReasonType` must be `PROVIDER` and `PATIENT`, and

  * `canCancelAppointment` must be true, and

  * `effectiveFrom` must be in the past, and 

  * `effectiveTo` must **not** be in the past

***4. I want to cancel a referral, for which there is no current appointment as a Service Provider***

* Obtain reference data from `REFERRAL-CANCELLATION-REASON` and filter:

  * `referrerUsage` must be `CANCEL_REFERRAL`, and

  * `businessFunction` must be `SERVICE_PROVIDER_CLINICIAN` or `SERVICE_PROVIDER_CLINICIAN_ADMIN` (depending which authenticated user will be performing the action), and

  * `appointmentRequestCancellationReasonType` must be `PROVIDER` and `PATIENT`, and

  * `canCancelAppointment` could be true or false, and

  * `effectiveFrom` must be in the past, and 

  * `effectiveTo` must **not** be in the past

***5. I want to cancel the triage referral as a Service Provider***

* Obtain reference data from `REFERRAL-CANCELLATION-REASON` and filter:

  * `referrerUsage` must be `CANCEL_REFERRAL`, and

  * `businessFunction` must be `SERVICE_PROVIDER_CLINICIAN` or `SERVICE_PROVIDER_CLINICIAN_ADMIN` (depending which authenticated user will be performing the action), and

  * `appointmentRequestCancellationReasonType` must be `PROVIDER_TRIAGE`, and

  * `effectiveFrom` must be in the past, and 

  * `effectiveTo` must **not** be in the past

You need to use [[HYPERLINK_A005]] to retrieve details of the referral in order to make this clinical decision.

## Important note when retrieving attachments

In order to retrieve an attachment using the [[HYPERLINK_A042]] (or deprecated [[HYPERLINK_A006]]) endpoint, the attachment must be available for download. 
The availability status of attachments associated with a referral are returned via this endpoint as a eRS-AvailabilityStatus-1 code.

Further details on attachment availability status and eRS-AvailabilityStatus-1 codes can be found in the [[HYPERLINK_A005]] and [[HYPERLINK_A042]] specifications. 

## Important notes when providing an appointment request cancellation reason

When cancelling a referral as a Service Provider Clinician:

  * If the referral is in the **"Triaged - Provider to action"** state, the cancellation reason must be an **Appointment Request End Triage Reason** type.

  * If the referral is **not** in that state, the cancellation reason must be a **Provider Appointment Request Cancellation Reason** or **Patient Appointment Request Cancellation Reason** type.

## Use case
As an authenticated user

I need to cancel a referral, and any active appointments

So that the referral is no longer processed

## Related endpoints
You can retrieve the reference data needed to cancel a referral by using [[HYPERLINK_A004]]. This contains "reasons" for cancellation.

You can check if you can cancel the referral by checking [[HYPERLINK_A029]].

You can use [[HYPERLINK_A005]] to obtain a current appointment reference, if there is one. This endpoint will also provide you with the current UBRN version.

You can use [[HYPERLINK_A038]] to view the current appointment (where applicable).

## 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.

## Sandbox test scenarios

You can test the following scenarios in our sandbox environment:

| Scenario                                                                 | Request details                       |
| ------------------------------------------------------------------------ | ------------------------------------- |
| Reason for Cancellation without Comment (Comment Not Mandatory)          | Intend Private With No Comment        |
| Reason for Cancellation with Comment (Comment Mandatory)                 | Patient Cancellation With Comment     |
| Cancelled Referral                                                       | Raised in Error                       |
| Cancelled Appointment and Referral                                       | Referrer Cancellation                 |
| Cancelled Referral After Prior Appointment Cancellation                  | Treatment No Longer Required          |
| Cancelled Referral with Existing Review Outcome                          | Intend Private With Comment           |
| Cancelled Referral (Provider) without Comment (Comment Not Mandatory)    | Provider Cancellation With No Comment |
| Cancelled Referral with Triage Response                                  | Provider Cancellation via End Triage  |

## 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)
- `#/paths/~1STU3~1ReferralRequest~1%7Bubrn%7D/get/parameters/0` (unresolved $ref)
- `#/paths/~1STU3~1Appointment~1%7Bid%7D/put/parameters/5` (unresolved $ref)

## Request body

- object: Parameters containing the cancellation reason and comment for referral cancellation request.
  - `resourceType` 'Parameters', required
  - `meta` object, required
    - `profile` string[], required
  - `parameter` union[], required: | Field | Cardinality | Notes | | --------------------------------- | ----------- | ------------------------------------------ | | `cancellationReason` | `1..1` | The reason why the referral is being cancelled | | `cancellationComments` | `0..1` | This may be mandatory if mandatory comment indicator is set to 'Yes' for the Cancellation Reason Type selected. Maximum 2000 characters. |
    - union
      - object: Parameter to supply a cancellationReason
        - `name` 'cancellationReason', required
        - `valueCoding` object, required
          - `system` string, required
          - `code` string, required
      - object: Parameter to supply the cancellationComments
        - `name` 'cancellationComments', required
        - `valueString` string, required

## Response `200`

e-RS Referral Request

- object: Parameters containing for the cancelled referral with/without cancelled appointment.
  - `resourceType` 'Parameters', required
  - `meta` object, required
    - `profile` string[], required
  - `parameter` union[], required: | Field | Cardinality | Notes | | --------------------------------- | ----------- | ---------------------------------------------------------------------------------------- | | `updatedReferralRequest` | `1..1` | Cancelled Referral Request . | | `updatedAppointment` | `0..1` | The cancelled appointment resource is only returned if appointment was cancelled part of this cancel referral operation.|
    - union
      - object: Parameter containing the cancelled referral request
        - `name` 'updatedReferralRequest', required
        - `resource` Schema, required (unresolved $ref)
      - object: Parameter containing the cancelled appointment
        - `name` 'updatedAppointment', required
        - `resource` Schema, required (unresolved $ref)

## Other responses

- `400` (unresolved $ref)
- `401` (unresolved $ref)
- `403` (unresolved $ref)
- `404` (unresolved $ref)
- `406` (unresolved $ref)
- `409` (unresolved $ref)
- `412` (unresolved $ref)
- `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 | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | MISSING_VALUE | A field defined as mandatory for an endpoint has not been provided. | | INVALID_REQUEST_STATE | The Request, while otherwise valid, is not in the correct state for the specific action being performed. | | PATIENT_ERROR | An error occurred while retrieving the requested patient. Do not attempt again. | | NO_RELATIONSHIP | The user does not have a legitimate relationship with the request. | | UNABLE_TO_CANCEL_APPOINTMENT | System is unable to cancel the appointment. | | INAPPROPRIATE_VALUE | A value, which is acceptable under different conditions, is inappropriate in the context of the other information provided. |
- `423` (unresolved $ref)
- `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.dev/nhs/apis/e-referrals-service-api/revisions/916969ea472f?raw)
