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
This API gets the referral request identified by the given ID and returns referral information in the format of eRS-ReferralRequest-1.
Resource URL
| Method | URL | Authentication |
|---|---|---|
| GET | {Base URL}/STU3/v1/ReferralRequest/{ubrn} | 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”
FHIR Structure Definition
Prerequisite Conditions
- -
INPUT
Request Operation: Header
| Field Name | Description |
|---|---|
| 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 | Example: “application/fhir+json” |
Request Operation: Body
There is no body required for this request, the UBRN must be provided in the URL.
Example URI
https://api.dev1.ers.ncrs.nhs.uk/ers-api/STU3/v1/ReferralRequest/000000098888
Example Request Header
"XAPI_ASID" : "999000000045",
"HTTP_X_SESSION_KEY" : "pro-api-session:06bdd8aa-da2c-45dc-bc73-bee80b70fe2d",
"Accept" : "application/fhir+json"
Example Request Body
There is no body required for this request.
OUTPUT
Response: Success
If successful referral information is returned. The response code 200 (OK) is returned.
Example Response Header
"X_ERS_TRANSACTION_ID" : "7f68395f-41ce-4d45-bcc8-6564e2bc73a1-1",
"ETag" : "W/\"8\"",
"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 workgroup member for the current booked-to service at the logged-in organisation | No legitimate relationship exists with this referral, check workgroup permissions. |
| NO_SUCH_REQUEST | A referral with the specified UBRN does not exist. | The referral may have been archived or soft-deleted, check your records. |
| INVALID_REQUEST_TYPE | The UBRN is not associated with an appointment request. | The referral may be another type of request, e.g. advice and guidance or a draft request which cannot be retrieved. |
| INVALID_REQUEST_STATE | The referral request is not in the correct state. | The referral must have a booked appointment and referral clinical information attached. |
