--- title: "Retrieve advice and guidance conversation (A025, FHIR STU3)" method: GET path: "/STU3/Communication" tags: ["Retrieve clinical information"] --- # Retrieve advice and guidance conversation (A025, FHIR STU3) `GET /STU3/Communication` ## Overview Use this endpoint to retrieve the advice and guidance conversation between the referring organisation and service providing organisation. A conversation takes the form of messages between a referrer (seeking advice) and a provider or specialist. Messages can include file attachments. These must be retrieved via [[HYPERLINK_A042]] [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]]. You need to use [[HYPERLINK_A024]] to retrieve the summary of an advice and guidance request. This will importantly include the latest version of the request which must be used. ## 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 conversation that is present on an advice and guidance request So that I can review the conversation and potentially contribute further to it. ## Important notes The conversation returned includes links to any attachments associated with the conversation. This can be done via endpoint [[HYPERLINK_A006]]. Note, dependent on how attachments were added they may be linked to the Advice and Guidance summary instead of the conversation. These may be retrieved from [[HYPERLINK_A024]]. 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. The conversation also gets included in the form of a PDF file returned by [[HYPERLINK_A007]]. In order to retrieve an attachment using the [[HYPERLINK_A042]] (or deprecated [[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_A025]]. 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_A006]] to retrieve any attachments associated with the advice and guidance request. - (For service provider users) Use [[HYPERLINK_A026]] to respond to the referrer supplying advice or requesting further information. - (For service provider users) Use [[HYPERLINK_A027]] to convert the advice and guidance request into a referral. This is only possible if the referrer has authorised the provider to do so. Use [[HYPERLINK_A043]] to generate a PDF file overview relating to an advice and guidance request. ## Sandbox test scenarios You can test the following scenarios in our sandbox environment | Scenario | Request | | -------------------------------------------------------------- | --------------------------------------------------------- | | Single message from referrer | `based-on`=`CommunicationRequest/000000070000/_history/1` | | One message each way | `based-on`=`CommunicationRequest/000000070000/_history/2` | | Attachment present in each direction | `based-on`=`CommunicationRequest/000000070001/_history/6` | | Multi-way conversation | `based-on`=`CommunicationRequest/000000070002/_history/1` | | Attachment uploaded from RCS before A&G creation | `based-on`=`CommunicationRequest/000000070003/_history/7` | | Attachment files unavailable for download | `based-on`=`CommunicationRequest/000000070004/_history/3` | ## Query parameters - `based-on` string, required - `_include` 'Communication:requester-practitionerrole:PractitionerRole' | 'Communication:sender-practitionerrole:PractionerRole' | 'Communication:content-reference:DocumentReference' ## Headers - `NHSD-End-User-Organisation-ODS` string - `NHSD-eRS-Business-Function` 'REFERRING_CLINICIAN' | 'REFERRING_CLINICIAN_ADMIN' | 'REFERRING_ADMIN' | 'COMMISSIONER' | 'SERVICE_PROVIDER_CLINICIAN_ADMIN' | 'SERVICE_PROVIDER_CLINICIAN' | 'SERVICE_PROVIDER_ADMIN' | 'INFORMATION_ANALYST' | 'BOOKING_MANAGER' | 'ADDITIONAL_REQUIREMENTS_MANAGER' - `NHSD-eRS-On-Behalf-Of-User-ID` string ## Parameters - `#/paths/~1STU3~1Task/get/parameters/0` — unresolved $ref - `#/paths/~1STU3~1Task/get/parameters/4` — unresolved $ref ## Response `200` e-RS Communication Request (advice and guidance summary) ## Other responses - `400` — Where status code 400 (Bad Request) 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 active request. | | NO_RELATIONSHIP | The user does not have a legitimate relationship with the request. | - `401` — unresolved $ref - `403` — unresolved $ref - `404` — Not Found - Resource not found for ID provided or Resource version does not match version requested. - `406` — unresolved $ref - `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)