Search loading...

API Hub

Explore and Make use of Nationally Defined Messaging APIs

 

A026: Send Advice and Guidance Response

Status: Live

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

Method URL Authentication
POST {Base URL}/STU3/v1/CommunicationRequest/{ubrn}/$ers.sendCommunicationToRequester 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”

Operation Definition

eRS-sendCommuncationToRequest-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

Field Name Value
XAPI_ASID The “Accredited System ID” issued to the third party
HTTP_X_SESSION_KEY The session key generated by the Authentication and Authorisation APIs
Content-Type application/fhir+json
If-Match Used to identify the UBRN version of the Supplier versus what is stored within e-RS

Request Operation: Body

Name Cardinality Type Description
guidance 1..1 string This is the guidance offered to the Referrer from the Provider
- max 2000 characters
- Any links must be in a valid format <a href="Link Target" target="_blank">Link Text</a>

More than one HTML element could be included providing each meet validation
priority 1..1 Coding This should be set to what the Provider believes the Priority of the Request should be. It is mandatory but does not have to be changed from the current Priority.

Binding: eRS-Priority-1
guidanceOutcome 1..1 Coding A summary of the guidance offered

Binding: eRS-GuidanceResponseOutcome-1
guidanceIntendedRecommentation 0..1 (conditionally mandatory) Coding What the provider expects to happen next. Conditionally Mandatory if guidanceOutcome value is “RETURN_TO_REFERRER_WITH_ADVICE”

Binding: eRS-GuidanceIntendedRecommendation-1
guidanceAttachmentFile 0..* Resource This parameter is the field used to attach files that have previously been uploaded using A020 to the response the Service wishes to send.

Should be represented as eRS-DocumentReference-1

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

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.

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 Suggested Diagnostic
NO_RELATIONSHIP User associated with the API session does not have a Legitimate Relationship with the Advice and Guidance Request
PATIENT_ERROR The Patient cannot be viewed via e-Referrals
INVALID_REQUEST_STATE An Advice and Guidance Request must be in progress for a Service to send a response or the UBRN provided is not for an Advice and Guidance Request
INAPPROPRIATE_VALUE guidanceIntendedRecommentation value is only required if guidanceOutcome value is “RETURN_TO_REFERRER_WITH_ADVICE”
VALUE_IS_REQUIRED guidanceIntendedRecommentation value is required if guidanceOutcome value is “RETURN_TO_REFERRER_WITH_ADVICE
INAPPROPRIATE_VALUE Attachment/document type must be ‘GUIDANCE_RESPONSE’
INAPPROPRIATE_VALUE Attachment/document status must be ‘current’
DUPLICATE_FILENAME File names, including extensions, must be unique – there is already a file with the same File name and extension on the Advice and Guidance Request

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.


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