Search loading...

API Hub

Explore and Make use of Nationally Defined Messaging APIs

 

A014: Reject Referral

Status: Live

Description

Once a referring organisation has booked an appointment and appropriate referral information has been added, the referral is available for the service provider to review (via the Referrals for Review worklist). As part of this review process, a provider can choose to reject the referral if they feel it’s inappropriate for their service or they require additional referral information to make a decision. Users will be able to carry out this action in their preferred system using this API.

Providers can also choose to accept the referral into their service, i.e. it meets all the criteria for treatment at the service, using A013: Accept Referral.

Resource URL

Method URL Authentication
POST {Base URL}/STU3/v1/ReferralRequest/{ubrn}/$ers.rejectReferral 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

Prerequisite Conditions

  • The user is a workgroup member (or in the case of an SPCA, is logged in on behalf of a workgroup member) for the service associated to the current appointment booking;

  • 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 by using A008: Retrieve Worklist

  • Detailed referral information, including clinical referral information and attachments can be obtained via A005: Retrieve Referral Request

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
rejectionReason 1..1 Coding The reason why the referral is being rejected (required): eRS-RejectionReason-1
rejectionComments 0..1 String This may be mandatory if mandatory comment indicator is set to ‘Yes’ for the Rejection Reason Type selected. Maximum 2000 characters
appointmentCancelledInPAS 0..1 Boolean Whether the appointment has been cancelled in the PAS system

Example URI

https://api.dev1.ers.ncrs.nhs.uk/ers-api/STU3/v1/ReferralRequest/000000098880/$ers.rejectReferral

Example Request Header

XAPI_ASID:999000000045
HTTP_X_SESSION_KEY:pro-api-session:e96357b1-298d-4159-ac58-a8953c3262c6
Content-Type:application/fhir+json
If-Match:W/\"9\"

Example Request Body

Note: These examples may contain environment specific URLs and test data, these should be replaced with appropriate values for your implementation.

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”)

Example Response Header

X_ERS_TRANSACTION_ID:82f14a9b-7ed1-4917-afca-f849d2e0eb55-1
ETag:W/\"11\"
Content-Disposition:inline;filename=f.txt
Content-Type:application/fhir+json

Example Response Body

Note: These examples may contain environment specific URLs and test data, these should be replaced with appropriate values for your implementation.

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
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’
VALUE_IS_REQUIRED Comment missing when deemed mandatory for the selected Rejection Reason Comments are mandatory for this rejection reason
INAPPROPRIATE_VALUE Appointment Cancellation Reason is either outside its effective date range or is not of type Reject Request Appointment Booking Cancellation Reason Type Reason is not an effective booking cancellation reason for a provider reject
VALUE_IS_REQUIRED Appt. Cancelled in PAS Indicator missing for IBS appointment Appointment Cancelled in PAS Indicator is required for indirectly bookable appointments
FIELD_NOT_PERMITTED Appt. Cancelled in PAS Indicator supplied for DBS appointment Appointment Cancelled in PAS Indicator is not relevant for directly bookable appointments

In case of errors related to PAS interaction, the following codes could be returned:

HTTP Status Code OutcomeKey Suggested Diagnostic
504 PAS_NOT_RESPONDING The request to cancel the appointment on the provider clinical system has timed out.
422 UNABLE_TO_CANCEL_APPOINTMENT The appointment could not be cancelled because it was rejected by the clinical provider system. This is most likely due to the appointment being amended outside of eRS.
502 PAS_RESPONDED_WITH_ERROR There was an error in communication with the provider clinical system.

All content is available under the Open Government Licence v3.0, except where otherwise stated