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
As a Referring Clinician (/Administrator)
I want to create a Referral in e-RS to a RAS Service and initiate the Triage process
So that I can progress my patients’ care without logging into multiple applications
Resource URL
| Method | URL | Authentication |
|---|---|---|
| POST | {Base URL}/STU3/v1/ReferralRequest/$ers.createReferralAndSendForTriage | Session Token (Details) |
- {Base URL} (Dev1) = https://api.dev1.ers.ncrs.nhs.uk/ers-api
Operation Definition
The Operation Definition for this endpoint is available on the FHIR server: eRS-CreateReferralAndSendForTriage-Operation-1
Prerequisite Operations
- The shortlisted service must be the result of a previously run patient service search using A010: Patient Service Search.
- Only one service may be shortlisted, and this must support the ‘Triage Request Flow’.
- Services that support the ‘Appointment Request Flow’ may be used with the A011: Create Referral endpoint instead.
- The shortlisted service will necessarily require a referral letter, therefore the intention to add a referral letter must be set to NEED_TO_ADD_LATER and the referrer will later need to attach some files with a separate call to the endpoint A012: Maintain Referral Letter.
- Requests sent for Triage are not eligible for appointment booking reminder letters, and therefore the first reminder follow up days must be set to 0.
- The service attributes are available from the Patient Specific Service Search (A010) endpoint.
INPUT
Request Operation: Header
| Field Name | Value |
|---|---|
| XAPI_ASID | The “Accredited System ID” issued to the third party |
| HTTP_X_SESSION_KEY | The session key generated by the Create Session endpoint (A001) |
| If-Match | W/"[Referral Request Version Number]" |
Request Operation: Parameters
| Parameter Name | Cardinality | Type | Notes |
|---|---|---|---|
| patient | 1..1 | Identifier | The NHS Number of the patient who the referral being created is for. Format: ^[0-9]{10}$ |
| referringClinician | 0..1 | Identifier | Required if and only if the logged in user has a role of Referring Clinician Admin. Format: ^[0-9]{12}$ |
| shortlist | 1..1 | Resource | When sending for triage, the shortlist must contain exactly one service, and this must support the ‘triage request flow’. Profile: https://fhir.nhs.uk/STU3/StructureDefinition/eRS-Shortlist-List-1 |
| firstReminderLetterFollowUpDays | 1..1 | UnsignedInt | This parameter triggers a reminder letter to the patient to prompt them to book an appointment if they haven’t done so after x days. When sending for triage, the only acceptable value is 0, which means no follow up letter will be sent, as the patient does not need to book an appointment. |
| intentionToAddReferralLetter | 1..1 | Coding | When sending for triage, a referral letter is always required; therefore the only acceptable value is NEED_TO_ADD_LATER. Binding: https://fhir.nhs.uk/STU3/ValueSet/eRS-ReferralLetterIntention-1 |
Removed Parameters
| Removed Parameter Name | Notes |
|---|---|
| contentSensitive | This parameter was removed in e-RS Release 9.1 |
| unaccreditedComment | This parameter was removed in e-RS Release 9.1 |
Example Request Header
"XAPI_ASID" : "999000000045",
"HTTP_X_SESSION_KEY" : "pro-api-session:55807c65-d0ca-4a0b-9d97-25b1b8009742"
Example Request Body
Note: These examples may contain environment specific URLs and test data, these should be replaced with appropriate values for your implementation.
OUTPUT
Response: Success
If successful, the status code 201 (Created) is returned and the response body contains the just created eRS-ReferralRequest-1, the API will also create a triage request to that service.
| Parameter Name | Cardinality | Type | Notes |
|---|---|---|---|
| referral | 1..1 | ReferralRequest | The referral request that will be created. Profile: https://fhir.nhs.uk/STU3/StructureDefinition/eRS-ReferralRequest-1 |
Example Response Header
"X_ERS_TRANSACTION_ID" : "505d58b8-137c-4738-ba84-f27bed651b26-1",
"ETag" : "W/\"3\"",
"Content-Disposition" : "inline;filename=f.txt",
"Content-Type" : "application/fhir+json"
Example Response Body
Note: These examples may contain environment specific URLs and test data, these should be replaced with appropriate values for your implementation.
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.
| issue.details.code | Description |
|---|---|
| FIELD_NOT_PERMITTED | A referring clinician is provided when the logged in user is not an RCA; or: one of the following occurs: the distance limit is specified when the postcode is not provided, the IWT limit is specified when the priority is TWO_WEEK_WAIT or the clinic type is specified when the specialty is not provided |
| INAPPROPRIATE_VALUE | The value of commissioning provisioning is ALL_SERVICES (this value is not supported), or: the intention to add a referral letter is set to NOT_INTENDING_TO_ADD, or: the proposed shortlist contains one or more services that do not support the ‘triage request flow’, or the first reminder letter follow up days is other than 0. |
| INVALID VALUE | The input provided does not conform with the expected data types and format specifically documented on the FHIR OperationDefinition or on the related FHIR profiles |
| MISSING_VALUE | One of the parameters described as mandatory on the FHIR OperationDefinition or on the related FHIR profiles has not been supplied |
| NO_REG_GP_PRACTICE | The patient provided was found not to have a registered GP practice. The patient is not eligible to be referred via e-RS while this problem persists |
| ORGANISATION_IS_CLOSED | The organisation identifier supplied corresponds to an organisation that is closed |
| ORGANISATION_NOT_APPROPRIATE | The organisation identifier supplied corresponds to an organisation of a type other than ‘Service location’ and ‘Service providing organisation’ |
| PATIENT_ERROR | There was a problem with the patient’s record in PDS. The patient is not eligible to be referred via e-RS while this problem persists |
| REFERENCE_NOT_FOUND | An entity referenced (e.g. the patient, the postcode, the organisation or a clinician) is not found |
| REFERENCED_USER_IS_NOT_ACTIVE | The SDS user provided as the referring clinician or the named clinician is found to be not active in SDS |
| REFERENCED_USER_IS_NOT_RC | The SDS user provided as the referring clinician does not actually have the Referring Clinician business function in e-RS |
| REFERENCED_USER_IS_NOT_SPC | The SDS user provided as the named clinician does not actually have the Service Provider Clinician business function in e-RS |
| REFERENCED_USER_NOT_IN_ORG | The referring clinician provided does not belong to the same organisation as the logged in user |
| SHORTLISTED_SERVICE_NOT_IN_RESULTS | A service in the shortlist submitted does not satisfy the search criteria provided |
| TOO_MANY_ITEMS | The proposed shortlist contains more than one service |
| VALUE_IS_REQUIRED | A referring clinician is not provided when the logged in user is an RCA; or: one of the following three is not provided: the pair specialty + clinic type, the clinical term¬ or the named clinician |
