Search loading...

API Hub

Explore and Make use of Nationally Defined Messaging APIs

 

A021: Create Referral And Send For Triage

Status: Live

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

All content is available under the Open Government Licence v3.0, except where otherwise stated