--- title: "Retrieve advice and guidance request summary (A024, FHIR STU3)" method: GET path: "/STU3/CommunicationRequest/{ubrn}" tags: ["Retrieve clinical information"] --- # Retrieve advice and guidance request summary (A024, FHIR STU3) `GET /STU3/CommunicationRequest/{ubrn}` ## Overview Use this endpoint to retrieve the summary of an advice and guidance request. This endpoint provides important contextual information about the advice and guidance request (e.g. the service/specialty to which advice has been requested, etc). This does not include the advice and guidance conversation between the referrer and the service provider. The conversation must be retrieved via [[HYPERLINK_A025]]. An advice request can include file attachments and structured clinical data added via an integrated primary care system. These must be retrieved via [[HYPERLINK_A042]] and [[HYPERLINK_A043]], respectively. [Read](https://digital.nhs.uk/developer/guides-and-documentation/building-healthcare-software/referrals-and-bookings/e-referral-service/retrieve-clinical-referral-information-as-a-service-provider) our building healthcare software guide for detailed information. ## Supported security patterns - Application-restricted access, unattended access - Healthcare worker, user-restricted access ## Pre-requisites You need to use the `Unique Booking Reference Number` (UBRN) of the advice and guidance request. For service provider users, you may have identified the UBRN via [[HYPERLINK_A023]]. ## Application-restricted access In order to use this endpoint you must be an authenticated e-RS calling application, working in the context of a Service Provider Organisation. ## Healthcare worker, user-restricted access In order to use this endpoint you must be an authenticated e-RS user and use one of the following e-RS roles: - `REFERRING_CLINICIAN` - `REFERRING_CLINICIAN_ADMIN` - `SERVICE_PROVIDER_CLINICIAN` - `SERVICE_PROVIDER_CLINICIAN_ADMIN` ## Use case As an authenticated user or application I need to retrieve the summary of an advice and guidance request So I can understand all of the relevant context for the request. ## Important notes The summary includes an indicator of whether the referrer has authorised the providing organisation to convert the advice and guidance request into an appointment request. If authorised, [[HYPERLINK_A027]] can be used to convert the advice and guidance request into an appointment request. An advice and guidance request may have been converted to a referral (with the same UBRN), and in addition a referral pathway in e-RS can be made up of more than one UBRN. As such, it is important that all clinical information is obtained across all the related UBRNs in the pathway. These may be identified using [[HYPERLINK_A005]] and will be returned if the user is authorised to view this. If the converted advice and guidance request is referred to a service outside of your organisation, the subsequent referral information may not be accessible due to existing data-access rules. However, the advice and guidance summary ([[HYPERLINK_A024]]), attachments ([[HYPERLINK_A006]]), advice and guidance conversation ([[HYPERLINK_A025]]) and clinical information ([[HYPERLINK_A043]]) which took place before such a conversion still forms part of the clinical information and can still be retrieved. In order to retrieve an attachment using the [[HYPERLINK_A042]] (or [[HYPERLINK_A006]] endpoint, the attachment must be available for download. Attachments are only made available once an uploaded file has been validated and successfully malware scanned. A request to retrieve an attachment that is not available for download will result in an error being returned. See [[HYPERLINK_A042]] for more information. The availability status of an attachment can be retrieved via any endpoint that returns an eRS-AvailabilityStatus-1 code in the success response, including [[HYPERLINK_A024]]. The eRS-AvailabilityStatus-1 code can return one of four possible values, as detailed below. | eRS-AvailabilityStatus-1 code | Description / Guidance | |-------------------------------|--------------------------------------------------------------------------------------------------------------------| | AVAILABLE | The file is available for download. | | PENDING | The file is being scanned and cannot be retrieved. Wait at least 5 minutes before checking its availability again. | | THREATS_FOUND | The file has been quarantined after detecting a threat and cannot be retrieved.
Contact the organisation that uploaded the file to resolve the issue and get the information you need. Use the extensions returned via this endpoint: Extension-eRS-AttachedBy-1 and Extension-eRS-AttachedByOrganisation-1. | | VALIDATION_FAILED | The file has failed validation and cannot be retrieved.
Contact the organisation that uploaded the file to resolve the issue and get the information you need. Use the extensions returned via this endpoint: Extension-eRS-AttachedBy-1 and Extension-eRS-AttachedByOrganisation-1. Validation can fail because the: | ## Related endpoints After using this endpoint, use [[HYPERLINK_A025]] to retrieve the Advice and Guidance conversation itself. ## Sandbox test scenarios You can test the following scenarios in our sandbox environment | Scenario | Request | | ------------------------------------------------------------------------ | ----------------------- | | Simple summary `CommunicationRequest` | `ubrn`=`000000070000` | | Attachment file reference present | `ubrn`=`000000070001` | | Attachment files unavailable for download | `ubrn`=`000000070002` | ## Parameters - `#/paths/~1STU3~1ReferralRequest~1%7Bubrn%7D/get/parameters/0` — unresolved $ref - `#/paths/~1STU3~1Task/get/parameters/0` — unresolved $ref - `#/paths/~1STU3~1Communication/get/parameters/3` — unresolved $ref - `#/paths/~1STU3~1Communication/get/parameters/4` — unresolved $ref - `#/paths/~1STU3~1Communication/get/parameters/5` — unresolved $ref - `#/paths/~1STU3~1Task/get/parameters/4` — unresolved $ref ## Response `200` e-RS Communication Request (advice and guidance summary) ## Other responses - `400` — unresolved $ref - `401` — unresolved $ref - `403` — unresolved $ref - `404` — unresolved $ref - `406` — unresolved $ref - `422` — Where status code 422 (Unprocessable Entity) is returned then an eRS-OperationOutcome-1 will be included in the body, as detailed below. Check diagnostics property for specific information regarding the error. | Error code | Description | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | PATIENT_ERROR | An error occurred while retrieving the requested patient. Do not attempt again. | | INVALID_REQUEST_TYPE | The `UBRN` provided exists in e-RS but does not correspond to an Advice and Guidance request. | | NO_RELATIONSHIP | The user does not have a legitimate relationship with the request. | - `429` — unresolved $ref - `500` — unresolved $ref - `503` — unresolved $ref --- [API](https://skmtc.dev/nhs/apis/e-referrals-service-api.md) · [All operations](https://skmtc.dev/nhs/apis/e-referrals-service-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nhs/e-referrals-service-api/revisions/916969ea472f/schema)