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, Referring Clinician Administrator, Service Provider Clinician or Service Provider Clinician Admin

I want to maintain and associate referral clinical information files (this endpoint could be used to delete files only)

So that I can create the referral letter

Resource URL

• {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

The Operation Definition for this endpoint is available on the FHIR server: eRS-MaintainReferralLetter-Operation-1

Prerequisite Operations

Each file to be attached to a referral needs to have been individually uploaded using A020: Upload file to document store. A020 will return the e-RS file location of each uploaded file; these are the URLs that need to be passed to the Maintain Referral Letter API so that they can be associated to the referral.

This linking action can be performed on newly created referrals that contain no existing attachments or an existing referral with associated attachments. Attachments can be subsequently added or deleted for existing referrals if at least one attachment remains associated with the referral after file maintenance. All new files to be associated with a referral should be uploaded first using A020: Upload file to document store and then linked to the referral using this endpoint.

Important Information:

The Maintain Referral Letter API can be used either to (1) associate attachments to a referral that has no existing referral letter attachments, OR (2) modify the set of referral letter attachments already associated with a referral.

For scenario 1 the conceptual process is very simple, i.e. upload attachment(s) via A020, and then associate these via A012.

For scenario 2, the API consumer is required to post all the referral letter attachments they wish to be associated to the referral, including any that were already associated.

a) Where a referral already has two referral letter attachments associated, and the API user wishes to add some more files: - the API consumer must upload the additional attachment(s) using A020, and then associate these AND the already associated referral letter attachments via A012 b) Where a referral already has three referral letter attachments associated, and the API user wishes to remove one of these, - the API consumer must re-associate, via A012, the two attachments that the user wishes to keep AND omit the file the user wishes to remove**. By omitting the file, e-RS will dis-associate the referral attachment. c) Where a referral already has four referral letter attachments associated, and the API user wishes to add some more files and remove some files, - the API consumer must upload the additional attachment(s) using A020, and then associate these AND only those referral letter attachments the user wishes to keep via A012.

In effect A012 completely replaces the set of referral letter attachments previously associated. As such, it is imperative that the new message must contains all the attachments the user wishes to keep associated.

• API consumer must ensure the user is fully aware when referral letter attachments are already associated with a referral and the implications of what will happen as a result of their action. E.g when a referring user wants to update a referral they should be presented with the attachments that are currently associated so they can add and/or remove attachments as required.

Note:

• It is possible to determine which files are already associated to a referral via A005: Retrieve Referral Request, and retrieve these clinical attachments via A006: Retrieve Attachment
• It is not permissible to remove all referral letter attachments leaving zero attachments associated. There must be at least one referral letter attachment associated.

INPUT

Request Operation: Header

Request Operation: Parameters

Example URI

/STU3/v1/ReferralRequest/000000097366/$ers.maintainReferralLetter

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/\"3\""

Example Request Body

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

• A012 Request.json

OUTPUT

Response: Success

If successful, the status code 200 (OK) is returned. The response body contains the just updated eRS-ReferralRequest-1

Example Response Header

"X_ERS_TRANSACTION_ID" : "237129a8-af7c-451b-982e-052bf06c223e-1",
"ETag" : "W/\"6\"",
"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.

• A012 Response.json

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.