Status:

This endpoint has been deprecated, meaning you should not use it for new integrations.

Instead, please use our newer e-RS FHIR API solution which is documented here: https://digital.nhs.uk/developer/api-catalogue/e-referral-service-fhir

Description

Once a referring organisation has booked an appointment and appropriate clinical referral information attached, the referral is available for the service provider to review via the Referrals for Review worklist (A008: Retrieve Worklist).

As part of this review process, a provider can either accept (A013: Accept Referral) or reject (A014: Reject Referral) a referral. Another scenario commonly encountered is being able to rebook the appointment or redirect the referral to another, perhaps more appropriate, service. These actions can be achieved via the ‘Cancel Appointment, Action Later’ API.

The API allows clinical users to take responsibility for the referral while informing administrators of the changes required. Users can amend the priority of the booking, as well as adding review comments and clinical attachments, if required. The booked appointment will be cancelled because of this action. Referrals actioned in this manner can then be progressed within the e-RS professional application via the Appointments for Booking worklist.

Resource URL

Method	URL	Authentication
POST	{Base URL}/STU3/v1/ReferralRequest/{ubrn}/$ers.CancelAppointmentActionLater	Session Token (Details)

• {Base URL} (Dev1) = https://api.dev1.ers.ncrs.nhs.uk/ers-api
• The {ubrn} represents the unique booking reference number of the Advice and Guidance Request for which the caller is obtaining the “Advice and Guidance summary”

Operation Definition

• eRS-cancelAppointmentActionLater-Operation-1

Prerequisite Conditions

• The user is a workgroup member (or in the case of a Service Provider Clinician Admin, is logged in on behalf of a workgroup member) for the service associated to the current appointment booking. This API is restricted to Service Provider Clinician and Service Provider Clinician Admin roles;

• There is a currently booked appointment (future dated) and there is referrer clinical information associated with the referral;

• The referral exists on the Referrals for Review worklist and can be determined using A008: Retrieve Worklist;

• Detailed referral information, including clinical referral information and attachments can be obtained via A005: Retrieve Referral Request, A006: Retrieve Attachment & A007: Retrieve Clinical Information;

• Calls to A020: Upload file to the e-RS document store must be made before this end point if attachments are to be included as part of the ‘Cancel Appointment, Action Later’ API.

INPUT

Request Operation: Header

Field Name	Value
XAPI_ASID	The “Accredited System ID” issued to the third party
HTTP_X_SESSION_KEY	The session key generated by the Create Session endpoint (A001)
Content-Type	*/*, application/fhir+json
If-Match	W/”n”

Note: n is the VersionId of the Referral and this can be retrieved by fetching the Referral details.
It must be the ID of the latest version of the referral in e-RS.

Request Operation: Parameters

Name	Cardinality	Type	Description
comments	1..1	valueString	Mandatory comments which provide the administrative user with notes on what action to take. Max. 2000 characters
providerAttachmentFile	0..*	Resource	Optional attachment(s) of type ‘Provider’ (eRS-DocumentReference-1)
priority	0..1	Code	Optional priority change (eRS-Priority-1)
appointmentCancelledinPAS	0..1	Boolean	Flag whether the appointment has been cancelled in the Patient Administrative System (PAS). Mandatory only if the appointment was to an Indirectly Bookable Service (IBS). If the appointment remains booked on PAS, then an entry will appear on the ‘Indirectly Booked Appointments to Cancel in PAS’ worklist on e-RS for administrative users to resolve later.

Example Request Body

Example Request

OUTPUT

Response: Success

If successful, the referral is accepted, and an indication of success returned with:

• A HTTP status code 200 (OK)
• Referral request (https://fhir.nhs.uk/STU3/StructureDefinition/eRS-ReferralRequest-1)
• With an eRSAppointment (appointment.status) code and display of “cancelled”
• UBRN version number

Response: Failure

If an error occurs, the relating HTTP status code will be returned in the header. Where status code 422 (Unprocessable Entity) is returned then an eRS-OperationOutcome-1 will be included in the body, as detailed below:

OutcomeKey	Description	Suggested Diagnostic
NO_RELATIONSHIP	The SPC user (or if SPCA, SPC user they are “on behalf of”) is not a service provider workgroup member for the current booked-to service at the logged-in organisation	No legitimate relationship exists with this referral, check workgroup permissions
PATIENT_ERROR	The patient associated with the request is marked as ‘sensitive’	The user does not have the necessary clinical credentials to view this patient
INVALID_REQUEST_STATE	The appointment request has a status other than ‘Booked’ or ‘Requires Rebook’	The referral must be ‘Booked’ or ‘Requires Rebook’
INVALID_REQUEST_STATE	The appointment request has an appointment booking with a state other than ‘Booked’	The referral must have a booked appointment
INVALID_REQUEST_STATE	The appointment request has an appointment booking with a date in the past	The appointment must be on or after today
INVALID_REQUEST_STATE	The shortlisted service status of the service associated with the appointment booking is not ‘Pending Review’	The referral request must not be marked for review, i.e. sent to a Referral Assessment Service (RAS)
INVALID_REQUEST_STATE	The clinical information intent indicator is not ‘Not Intending to Add’	The intention to add the referral letter must be ‘Not Intending to Add’
TECHNICAL_ERROR	Booking deferral was not able to be created	Request to rebook could not be fulfilled. Appointment remains booked