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
As a Referring Clinician (/Administrator) having created a referral
I want to retrieve the patient’s letter
So that the patient has all the necessary details to choose the clinic they want to attend and book an appointment
Resource URL
| Method | URL | Authentication |
|---|---|---|
| POST | {Base URL}/STU3/v1/ReferralRequest/{ubrn}/$ers.generatePatientLetter | 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”
This endpoint is to be used as part of the Create Referral workflow.
Operation Definition
The operation definition for this endpoint is available on the FHIR server: eRS-GeneratePatientLetter-Operation-1
Prerequisite Conditions
- A referral must exist and the user must legitimately have access to it.
(A letter can be fetched multiple times, but the current API only supports the scenario of referrals that don’t have an appointment booked.)
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) |
| Accept | application/pdf |
Request Operation: Parameters
This operation does not require a body.
Example URI
/STU3/v1/ReferralRequest/000000097366/$ers.generatePatientLetter
Example Request Header
XAPI_ASID" : "999000000045",
"HTTP_X_SESSION_KEY" : "pro-api-session:06bdd8aa-da2c-45dc-bc73-bee80b70fe2d"
OUTPUT
Response: Success
If successful, the Status code 200 (OK) is returned and the response body contains the binary stream of the generated patient letter.
Example Response Header
"X_ERS_TRANSACTION_ID" : "505bc389-d95b-4e37-b957-6476e82fd9de-1",
"Content-Disposition" : "attachment; filename=\"97366_Triage_Summary_20200518160340.pdf\"",
"Content-Type" : "application/pdf"
Response: Failure
If an error occurs, the relating HTTP status code will be returned. Where status code 422 (Unprocessable Entity) is returned then an eRS-OperationOutcome-1 will be included in the body, as detailed below.
| issue.details.code | Description |
|---|---|
| INVALID_REQUEST_TYPE | The UBRN provided exists in e-RS but does not correspond to a referral |
| INVALID_REQUEST_STATE | The referral is in a state that is not suitable to print the appointment request summary or the triage summary letters, for example it is either incomplete or cancelled; or the referral has a booked appointment; or the referral has been superseded by an onward referral; or: the referral has a booking deferral |
| NO_ACCESS_CODE | The patient doesn’t have an access code/password to log onto the patient portal |
| NO_RELATIONSHIP | The user does not have a suitable legitimate relationship with the referral |
