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 for my patient with a shortlist of services
So that I can progress the care of my patient while leaving them the freedom to choose the service that best suits them.
Resource URL
| Method | URL | Authentication |
|---|---|---|
| POST | {Base URL}/STU3/v1/ReferralRequest/$ers.createReferral | 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-CreateReferral-Operation-1
Prerequisite Conditions
- The shortlisted service must be the result of a previously run patient service search using A010: Patient Service Search.
- The shortlist must not contain any Referral Assessment Services (RAS), referrals to these services should be created using endpoint A021: Create Referral And Send For Triage.
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) |
Request Operation: Parameters
| Parameter Name | Cardinality | Type | Notes |
|---|---|---|---|
| patient | 1..1 | Identifier | The master NHS Number for the patient |
| referringClinician | 0..1 | Identifier | |
| shortlist | 1..1 | Resource | The structure definition of this resource is: eRS-Shortlist-List-1. Please note that in turn this Resource needs to have a contained reference to an eRS-ServiceSearchCriteria-Parameters-1 |
| firstReminderLetterFollowUpDays | 1..1 | UnsignedInt | |
| intentionToAddReferralLetter | 1..1 | Coding | If shortlisting a service flagged as requiring a referral letter by the result of a Patient Service Search (and only in this case) then the value of this field must be NEED_TO_ADD_LATER |
Removed Parameters
| Removed Parameter Name | Notes |
|---|---|
| unaccreditedComment | This parameter was removed in e-RS Release 9.1 |
| contentSensitive | 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 contain environment specific URLs and test data, these should be replaced with appropriate values for your implementation.
Response
OUTPUT
Response: Success
If successful, the status code 201 (Created) is returned and the response body contains the just created eRS-ReferralRequest-1.
Example Response Header
"X_ERS_TRANSACTION_ID" : "d2945578-24c3-413a-9a91-b5002ec6938d-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 when one or more of the shortlisted services has the referral letter required set to true, or the proposed shortlist contains one or more services that do not support the ‘appointment request flow’ |
| 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 | The service selected for the shortlist submitted does not satisfy the search criteria provided |
| 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. |
