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

• 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”
• {version} is the version of the Advice and Guidance Request to be retrieved (only the most current version will be retrievable)
• {Base URL} is the URL for the test environment you are intending to use.

Operation Definition

• eRS-CommunicationRequest-1

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

Header

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

Example Response Body

• A024_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: the errors in the table above only occur when the incoming message is correct but for business reasons a response cannot be returned.