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 endpoint allows a Service Provider Clinician (SPC) or Service Provider Clinician Admin (SPCA) to send a response on an Advice and Guidance Request which is still “in progress”.

Request Operation: 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

eRS-SendCommunicationToRequester-Operation-1

Input

eRS-SendCommunicationToRequester-Request-Parameters-1

Output

eRS-SendCommunicationToRequester-Response-Parameters-1

Prerequisite Conditions

• The given UBRN relates to an Advice and Guidance Request that exists in e-RS and is currently “in progress”
• The user has reviewed the most recent version of the Advice and Guidance Request using A024: Get A&G Summary and A025: Get A&G Conversation
• It is expected that user will have made a clinical decision to review attachments and any Clinical Referral Information and Attachments associated with the Advice and Guidance Request

Compliance Requirements

MUST

• The guidance parameter is used to populate the Communcation.Note field. A Communcation Resource is part of what is returned on success.
• The “ Communication.Note “ field is a plain text field that additionally supports hyperlinks in the following format: <a href="[web_address]" target="_blank">link_text</a>
• It is the Suppliers responsibility to sanitize responses received from eRS. eRS allows for <a> tag HTML elements so that hyperlinks can be rendered. Suppliers MUST sanitize as they deem necessary, noting that eRS suggests all other HTML stored within eRS should be considered a text-only string
• Deceased Checks
• Viewing an Advice and Guidance is normally subject to a “deceased patient” check. It is expected that the whole Advice and Guidance Request is “viewed” before sending a response and therefore this compliance requirement is detailed here as well
• This check cannot be provided by API and instead the supplier should be expected to check for a Date of Death via PDS before making the call to the API

Example scenario

1) Supplier checks with PDS for the presence of a Date of Death. 2) If there is a DoD present, the Supplier should pass this information to the user so they can decide whether to proceed with retrieving the Advice and Guidance Request anyway, or not 3) If they choose to retrieve the A&G Request, the presence of a DoD will not prevent the xAPI returning the response.

COULD

Change in priority warning displayed during guidance response. The following notification could be displayed when changing the Priority as part of issuing a response, for example:
“You have selected the 2 Week Wait or Urgent priority for an Advice and Guidance request. This priority should only be selected for local pathways which deal with these critical requests. If not, patients could suffer harm due to delay to care. Have you selected the correct priority?”

Other useful information

• If RETURN_TO_REFERRER_WITH_ADVICE is provided as the value for the guidanceOutcome parameter, then a permissible value for the guidanceIntendedRecommentation parameter MUST be provided.
• If the guidanceOutcome parameter is not RETURN_TO_REFERRER_WITH_ADVICE, then no value for the guidanceIntendedRecommentation parameter should be provided.

INPUT

Request Operation: Header

Request Operation: Body

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"

(see http://hl7.org/fhir/STU3/http.html#concurrency for more information)

Example Request Body

• A026_Request.json

OUTPUT

Response: Success

• A Name string identify the Advice and Guidance Request information with the value ‘updatedCommuncationRequest’
• A Resource value containing the current CommuncationRequest Resource
  • The following fields on the CommuncationRequest Resource could have been updated as a result of this the Parameters input:
  • AdviceAndGuidanceStatus-1
  • eRS-ReferralPriority-1
• Name string identifying the Guidance Response information with the value ‘createdCommunication’
• A second Resource value containing the newly created Communcation Resource, which is represented as per A025: View Advice and Guidance Conversation
• The following fields con the Communication Resource will always return:
  • “Recipient” field representing the intended received of the message containing a “Recipient.Extension” to /HealthcareService-Reference-1 identifying the responding Service
  • “Category.CodeSystem” displaying a value (via CommunicationSentBy-1) representing the Direction Type of the communication. In this case, the value will be “Responder”

Example Response Header

HTTP 200

(No “e-tag” is returned)

Example Response Body

Note, only the created Communication is returned, not any existing Communications on the Advice and Guidance Request. To get the full set, you would need to use the fetch the “Advice and Guidance Request Conversation” which would include the newly created, and all previous/subsequent Communication Resources.

• A026_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:

Note: other “generic” errors concerning FHIR/JSON errors can also be returned. The above details for the most part, validation errors in the context of the Advice and Guidance Request.