--- title: "Convert advice and guidance request to referral (A027, FHIR STU3)" method: POST path: "/STU3/ReferralRequest/$ers.createFromCommunicationRequestActionLater" tags: ["Review advice and guidance requests"] --- # Convert advice and guidance request to referral (A027, FHIR STU3) `POST /STU3/ReferralRequest/$ers.createFromCommunicationRequestActionLater` ## Overview Use this endpoint, as a service provider, to: - convert the advice and guidance request you have received into a referral, AND - create a task for the service provider admin team to select/shortlist appropriate services for the patient, AND - provide final guidance response details back to the referrer Note: This endpoint is only allowed to be used if the referrer has authorised the provider to convert the advice and guidance request into a referral. Whilst a document can be uploaded via [[HYPERLINK_A020]] without a `NHSD-eRS-Referral-ID`, only documents that have a `NHSD-eRS-Referral-ID` can be associated using this end point. An attempt to associate a document without a `NHSD-eRS-Referral-ID` will return an error response of 422 - `INAPPROPRIATE_VALUE`. ## Supported security patterns - Healthcare worker, user-restricted access ## Pre-requisites In order to use this endpoint you must be an authenticated e-RS user and use one of the following e-RS roles: - `SERVICE_PROVIDER_CLINICIAN` - `SERVICE_PROVIDER_CLINICIAN_ADMIN` You need to use [[HYPERLINK_A024]] to retrieve the summary of an advice and guidance request. This will include whether or not the referrer has authorised the provider to be able to convert an advice and guidance request into a referral, and thus dictate whether this endpoint can be used. You need to use [[HYPERLINK_A025]] to retrieve the conversation within an advice and guidance request. If you want to include attachments with the admin task and/or the response to the referrer, you need to use [[HYPERLINK_A020]] so they are ready to be associated when this endpoint is called. ## Use case As an authenticated user I need to convert an inbound advice and guidance request into a referral and task my admin team to shortlist appropriate services for the patient So that I can progress the patient's care along the most appropriate referral pathway. ## Important notes When this endpoint is successfully used, an entry will be added to the service providers Appointments For Booking worklist for the admin team to action the task. The provider admin team will currently only be able to progress the referral via the e-RS Professional Application user interface (e.g. shortlisting appropriate services for the patient). In order to retrieve an attachment using the [[HYPERLINK_A042]] (or deprecated [[HYPERLINK_A006]]) endpoint, the attachment must be available for download. The availability status of attachments associated with a referral are returned via this endpoint as a eRS-AvailabilityStatus-1 code. Further details on attachment availability status and eRS-AvailabilityStatus-1 codes can be found in the [[HYPERLINK_A005]] and [[HYPERLINK_A042]] specifications. ## Related endpoints You can use [[HYPERLINK_A005]] to retrieve the details of the referral. You can use [[HYPERLINK_A024]] to retrieve the latest summary of the advice and guidance request. You can use [[HYPERLINK_A025]] to retrieve the latest conversation within the advice and guidance request. You can use [[HYPERLINK_A006]] to retrieve the clinical attachments for a referral/advice request. You can use [[HYPERLINK_A007]] to retrieve the clinical information summary PDF for a referral. ## Known Issues 1. The Participant.type attribute is being mapped as a single type for this endpoint. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be an array. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information. 2. The participant of an Appointment references a value set. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be a coding system. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information. ## Parameters - `#/paths/~1STU3~1Task/get/parameters/0` — unresolved $ref - `#/paths/~1STU3~1Task/get/parameters/1` — unresolved $ref - `#/paths/~1STU3~1Task/get/parameters/2` — unresolved $ref - `#/paths/~1STU3~1Task/get/parameters/3` — unresolved $ref - `#/paths/~1STU3~1Task/get/parameters/4` — unresolved $ref ## Response `201` A referral converted from A&G request. ## Other responses - `400` — unresolved $ref - `401` — unresolved $ref - `403` — unresolved $ref - `404` — unresolved $ref - `406` — unresolved $ref - `409` — unresolved $ref - `415` — 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. | | NO_RELATIONSHIP | The user does not have a legitimate relationship with the request. | | UNSUPPORTED_PRIORITY | The Priority submitted is not supported by the responsible Service. | | INAPPROPRIATE_VALUE | A value, which is acceptable under different conditions, is inappropriate in the context of the other information provided. | | INVALID_VALUE | The input provided does not conform to the expected data types and format. | | INVALID_REQUEST_STATE | The Request, while otherwise valid, is not in the correct state for the specific action being performed. | | INVALID_STATE | Indicates that the referenced item is not in the correct state for the request to be processed. | | MISSING_VALUE | A field defined as mandatory for an endpoint has not been provided. | | VALUE_IS_REQUIRED | A business rule defines a value as mandatory but it has not been provided. | | REFERENCE_NOT_FOUND | A supplied reference could not be resolved to valid resource (e.g. a patient, clinician or an organisation). | | DUPLICATE_FILENAME | A file being attached, matches another file being attached, or matches a file that is already linked. | | CONFLICTING_VALUES | Two or more supplied values are contradictory. | - `423` — 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)