--- title: "Create referral (A011, FHIR STU3)" method: POST path: "/STU3/ReferralRequest/$ers.createReferral" tags: ["Refer patient"] --- # Create referral (A011, FHIR STU3) `POST /STU3/ReferralRequest/$ers.createReferral` ## Overview Use this endpoint to create a referral by choosing a shortlist of bookable services and/or triage services. ## Supported security patterns - Healthcare worker, user-restricted access ## Important notes when creating a referral The maximum amount of services allowed on a given shortlist is 20. The act of shortlisting alone will not result in a referral being sent/booked to any of the shortlisted services (even if only one service is shortlisted). A shortlist of a single triage service should be avoided as this relies on the patient to progress the referral, potentially leading to a delay to care. Especially if the referral priority is 2WW or Urgent. Use [[HYPERLINK_A016]] if there is a need to support the sending/booking of the referral into a shortlisted service. ## Important notes when sending an e-Referral Pathway Start Date The e-Referral Pathway Start Date is a derived value of when the Referral To Treatment (RTT) clock starts. Find out how e-RS derives the pathway start date [[HYPERLINK_PATHWAY_START]]. You can supply an optional, alternate pathway start date when creating a referral. This may be because steps, such as reviews, take place early in your business process. Which means the clock started earlier than when the e-RS referral is created. Providing an alternate pathway start date ensures the correct date is recorded and used in other systems. When provided, the pathway start date must be: - in the past - no longer than 365 days ago - calculated in line with [[HYPERLINK_RTT_RULES]] This also overrides any e-RS derived date. ## 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: - `REFERRING_CLINICIAN` - `REFERRING_CLINICIAN_ADMIN` You need to have identified a `patient`, for example via [[HYPERLINK_PDS]]. You need to have found services that meet the referral needs of a patient using [[HYPERLINK_A010]]. ## Use case As an authenticated user I need to create a shortlist of bookable services and/or triage services So I can initiate my patients referral pathway, allowing the patient to book into one of the shortlisted services. ## Related endpoints To allow the patient to progress their referral in their own time, you can generate a letter for the patient by using [[HYPERLINK_A019]]. The letter summarises the current state of the referral and any steps the patient may need to follow (e.g. appointment booking instructions). You can book an appointment for the patient into a shortlisted directly bookable service using [[HYPERLINK_A015]] and [[HYPERLINK_A016]]. You can send the referral into a shortlisted triage service using [[HYPERLINK_A016]]. For the referral to be processed by the service provider, you must ensure appropriate referral letter information has been added to the referral. You can add/manage referrer letter information by using [[HYPERLINK_A012]]. You can check to see what referral letter information has already been added to a referral by using [[HYPERLINK_A005]], [[HYPERLINK_A007]], and [[HYPERLINK_A006]] endpoints where necessary. You can generate a letter for the patient, which summarises the current state of their referral and any steps the patient may need to follow, by using [[HYPERLINK_A019]]. ## 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~1Slot/get/parameters/2` — unresolved $ref - `#/paths/~1STU3~1Task/get/parameters/4` — unresolved $ref ## Response `201` A referral created within e-RS. ## Other responses - `400` — unresolved $ref - `401` — unresolved $ref - `403` — unresolved $ref - `406` — 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 | | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | REFERENCE_NOT_FOUND | A supplied reference could not be resolved to valid resource (e.g. a patient, clinician or an organisation). | | INAPPROPRIATE_VALUE | A value, which is acceptable under different conditions, is inappropriate in the context of the other information provided. | | TOO_MANY_ITEMS | In a list where a maximum number of items is specified (e.g. a Shortlist), too many entries are supplied. | | 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. | | FIELD_NOT_PERMITTED | A business rule defines a field as not permitted but it has been provided. | | PATIENT_ERROR | An error occurred while retrieving the requested patient. Do not attempt again. | | INVALID_VALUE | The input provided does not conform to the expected data types and format. | | INVALID_CODE | The input provided for a field is not one of the defined legal values. | | UNEXPECTED_FIELD | A field is provided that is not expected as part of the request. E.g. a field is mis-spelt, was defined on a previous version of the endpoint but has subsequently been removed. | | INVALID_FHIR_STRUCTURE | The FHIR data structure in the message body does not match the expected structure (e.g. an array is present for a value when no array is expected). | | REFERENCED_USER_IS_NOT_SPC | The user provided does not have the Service Provider Clinician authorisation in the e-RS. | | ORGANISATION_IS_CLOSED | The organisation supplied corresponds to an organisation that is closed. | | ORGANISATION_NOT_APPROPRIATE | The organisation supplied corresponds to an organisation that is not valid for the given request. | | DUPLICATE_SERVICE | Unique service value expected. | | SHORTLISTED_SERVICE_NOT_IN_RESULTS | The service selected for the shortlist submitted does not satisfy the search criteria provided. | | REFERENCED_USER_IS_NOT_ACTIVE | The user identified is not active. | | REFERENCED_USER_NOT_IN_ORG | The referenced user does not belong to organisation specified. | | NO_REG_GP_PRACTICE | The patient provided was found not to have a registered GP practice in the e-RS. | | REFERENCED_USER_IS_NOT_RC | The user provided does not have the Referring Clinician authorisation in the e-RS. | | REFERENCED_USER_IS_NOT_RC_AT_ORG | The user provided does not have the Referring Clinician authorisation at the organisation specified. | | SNOMED_NOT_FOUND | A SNOMED code, while potentially valid in the latest version of the international dictionary, is not found in the e-RS dictionary. | - `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.dev/nhs/apis/e-referrals-service-api/revisions/916969ea472f?raw)