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 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 accept the referral into their service, i.e. it meets all the criteria for treatment at the service. Users will be able to carry out this action in their preferred system using this API.
Providers can also choose to reject the referral, using A014: Reject Referral, if they feel it’s inappropriate for their service or they require additional referral information to make a decision.
Resource URL
Method | URL | Authentication |
---|---|---|
POST | {Base URL}/STU3/v1/ReferralRequest/{ubrn}/$ers.acceptReferral | 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: Body
There is no request body required for this API.
Example URI
https://api.dev1.ers.ncrs.nhs.uk/ers-api/STU3/v1/ReferralRequest/000000098878/$ers.acceptReferral
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/\"10\"
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 “booked”) - UBRN version number
Example Response Header
X_ERS_TRANSACTION_ID:cd7c124c-59ee-4e95-a1be-06b13d7d2c72-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:
OperationOutcome | 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’ |