Search loading...


Explore and Make use of Nationally Defined Messaging APIs


A005: Retrieve Referral Request

If you are using the deprecated FHIR v2 endpoint, please click here.

Status: Live


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) =
  • 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

- -


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

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.


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.

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