Search loading...

API Hub

Explore and Make use of Nationally Defined Messaging APIs

 

A024: Retrieve Advice and Guidance Request Summary

Status: Live

Description

This endpoint allows an authenticated user to obtain summary information about a specific Advice and Guidance Request. This is referenced as a CommuncationRequest Resource in FHIR.

A further request must be sent to A025: Get Advice and Guidance Conversation to get details of the communication back and forth between the Referrer and the Provider for a given Advice and Guidance Request. This is referenced as a single or set of Communication Resources in FHIR where each Communication Resource is a single part of a conversation between a requester (the Referrer) or responder (the Service Provider).

Together, these two endpoints form a whole view of an Advice and Guidance Request.

These endpoints available for users with the role of Referring Clinician (RC), Referring Clinician Admin (RCA), Service Provider Clinician (SPC) or Service Provider Clinician Admin (SPCA).

Request Operation: URL

Method URL Authentication
GET {Base URL}/STU3/v1/CommunicationRequest/{ubrn}/_history/
OR
{Base URL}/STU3/v1/CommunicationRequest/{ubrn}
Session Token (Details)
  • 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”
  • is the version of the Advice and Guidance Request to be retrieved (only the most current version will be retrievable)
  • {Base URL} (Dev1) = https://api.dev1.ers.ncrs.nhs.uk/ers-api

Operation Definition

Prerequisite Conditions

  • The given UBRN must exist in eRS and be an Advice and Guidance Request
  • From a use case perspective, a call may have been made to fetch the “advice and guidance request worklist” to obtain a UBRN to reference when obtaining an Advice and Guidance Request.

Compliance Requirements

Deceased Checks

Viewing an Advice and Guidance is normally subject to a “deceased patient” check. This cannot be provided by xAPI and instead the supplier should be expected to check for a Date of Death via PDS before making the call to the xAPI

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

CommunicationRequest versions

To ensure the Supplier is always referencing the latest version of the CommunicationRequest and the most up to date Communication, the supplier must use the basedOn functionality otherwise a change in the CommunicationRequest could be missed, such as priority change, because they are referencing an out-of-date CommunicationRequest.

Advice and Guidance Summary

The “CommunicationRequest” resource described in here is only for the Advice and Guidance Request Summary, i.e. retrieving this will not return any of the ‘request’ or ‘response’ messages which must be retrieved using the “Communication” resource and requested from A025: Get Advice and Guidance Conversation.

Notes:

  • You can always “view” an Advice and Guidance Request without invoking a lock - even if it is “locked” by another user. As “viewing” via the API doesn’t “lock” the Advice and Guidance (but “updates” via the API or eRS might do), the information retrieved is only valid at the point that it is viewed
  • The “Sender” and “Request” details will always be the Referring Clinician’s details, as the Advice and Guidance Request is currently always created on their behalf
  • Note that the Service Specialty CAN change and the CommuncationRequest will return the CURRENT Service Specialty fetched at the time of the call

INPUT

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

Example Request Header

XAPI_ASID:999000000045
HTTP_X_SESSION_KEY:pro-api-session:e96357b1-298d-4159-ac58-a8953c3262c6

OUTPUT

Response: Success

The output includes

  • An ETag header with the current version number
  • 200 HTTP response
  • A CommuncationRequest Resource which can be understood as follows:
  • resourceType field representing the FHIR Resource (“CommunicationRequest”)
  • id field representing the Advice and Guidance Request’s UBRN
  • status” field. See “Table 1 State Mapping” below
  • Category.Coding (AdviceAndGuidanceStatus-1)” See “Table 1 State Mapping” below
  • Subject.Identifier field representing the Patient via their NHS number.
  • Extension (eRS-ReferralPriority-1) representing the A&G Request’s current Priority
  • Extension.list (eRS-Shortlist-List-1) representing the Shortlist that includes the receiving Service only. This extension also contains the current Service Search Criteria (via Extension-eRS-Shortlist-SearchCriteria-1) which may include:
    • “Priority” e.g. as “ROUTINE”
    • “Specialty” e.g. as “CARDIOLOGY”
    • “ClinicType” e.g. as “HEART_FAILURE”
    • “ClinicalTerm” i.e. eRS’s SNOMED Concept ID
    • “NamedClinician” e.g. “455201100234”
    • “Organisation” e.g. as “Leeds Healthcare Trust”
    • “Postcode” e.g. as “LS1 2TW”
    • “DistanceLimit” e.g. as “50”
    • “AgeAndGenderAppropriate” e.g. as “true”
    • “commissioningProvisioning” i.e. whether the current Service Search was Locally Commissionable Services only, Nationally Commissionable, “All available” (whereby no filtering is applied) or “All Available for booking”
    • N.B see eRS-ServiceSearchCriteria-Parameters-1 for cardinality
  • Extension.valueCoding (Extension-eRS-Specialty-1) that contains a coding system which represents the current Specialty’ as a ‘code’ and a human readable display value of the Service
  • Extension.Coding (eRS-ProviderConversionAuthorisation-1) - representing whether the Advice and Guidance request can currently be converted by a Service
  • Requester.Agent.Extension (PractitionerRole-Reference-1) that contains:
    • PractitionerRole.Practitioner representing the Referring Clinician at the time of creation, e.g. 111111111111
    • PractitionerRole.Organization representing the Referring Org. at the time of creation, e.g. RGD03
    • PractitionerRole.Coding representing the user’s authenticated role at the time of creation, e.g. REFERRING_CLINICAN
  • Sender.Extension (PractionerRole-Reference-1) that contains:
    • PractitionerRole.Practitioner representing the Referring Clinician at the time of creation, e.g. 111111111111
    • PractitionerRole.Organization representing the Referring Org. at the time of creation, e.g. RGD03
    • PractitionerRole.Coding representing the user’s authenticated role at the time of creation, e.g. REFERRING_CLINICAN
  • Recipient.Extension (HealthcareService-Reference-1) representing the Service ID of the Service responding.

State Mapping

Business Condition CommunicationRequest.Category CodeSystem( AdviceAndGuidanceStatus-1) value CommunicationRequest.Status value
The last person to send a Communication was a Referrer PROVIDER_RESPONSE_REQUIRED Active
The last person to send a Communication was the Service, who advised more information is required REFERRER_TO_SUBMIT_FURTHER_INFORMATION Active
The last person to send a Communication was the Service, who provided advice REFERRER_TO_REVIEW_RESPONSE Active
Advice and Guidance Request has been ‘Cancelled’ and there is no Referral associated with the UBRN CONVERSATION_ENDED_CANCELLED Cancelled
Advice and Guidance Request is ‘Closed’ and there is no Referral associated with the UBRN CONVERSATION_ENDED_CLOSED completed
Advice and Guidance Request has been progressed to a Referral (either via a Service or the Referrer) ADVICE_CONVERTED completed

Example Response Body

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_SUCH_REQUEST The UBRN provided in the URL doesn’t have a suitable match
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_TYPE The UBRN supplied does not correspond to an Advice and Guidance Request
HISTORY_NOT_SUPPORTED The version number supplied is not the latest version

Note: the errors in the table above only occur when the incoming message is correct but for business reasons a response cannot be returned.


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