Search loading...

API Hub

Explore and Make use of Nationally Defined Messaging APIs

 

A011: Create Referral

Status: Beta

API URL

Base URL (Dev3): https://api.dev3.ers.ncrs.nhs.uk/ers-api/

Method URL Authentication
POST STU3/v1/ReferralRequest/$ers.createReferral Session Token (Details)

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.

Prerequisite Operations

The shortlisted services must be the result of a previously run Patient Specific Service Search (A010) endpoint. Some of the parameters provided in input to the Create Referral endpoint are dependent on the services selected:

  • If any of the shortlisted services have the referral letter required flag set to true then, when calling the Create Referral endpoint, 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 Maintain Referral Letter (A012))
  • If any of the shortlisted services are marked as ‘unaccredited’ for the referrer (and only in this case) then, when calling the Create Referral endpoint, the referrer will need to provide a meaningful comment as to why they decided to override the accreditation
  • When selecting a service that supports the Triage Request flow (also known as a “RAS service”), this must be the only shortlisted service.

These two service attributes are available from the Patient Specific Service Search (A010) endpoint.

Request Operation

Request 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)
Accept */*, application/fhir+json

Request Body

The Operation Definition for this endpoint is available on the FHIR server: eRS-CreateReferral-Operation-1

Parameter Name Cardinality Type Notes
patient 1..1 Identifier The master NHS Number for the patient
referringClinician 0..1 Identifier  
contentSensitive 1..1 Boolean  
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
unaccreditedComment 0..1 String If shortlisting a service flagged as ‘unaccredited’ by the Patient Specific Service Search (A010) endpoint (and only in this case) then a comment must be provided
firstReminderLetterFollowUpDays 1..1 UnsignedInt  
intentionToAddReferralLetter 1..1 Coding If shortlisting a service flagged as requiring a referral letter by the Patient Specific Service Search (A010) endpoint (and only in this case) then the value of this field must be NEED_TO_ADD_LATER

Examples:

Request Header
    EXAMPLE COMING SOON
  
Request Body
    EXAMPLE COMING SOON
  


Response

Success

HTTP Status code 201 (Created) is returned. The response body contains the just created eRS-ReferralRequest-1, when the shortlist contains a service that supports the Triage Request flow (in which case it will be the only shortlisted service), the API will also create a triage request to that service.

Example:

Response Body
    EXAMPLE COMING SOON
  


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; or: a referrer right override comment is provided when none of the shortlisted services is marked as unaccredited
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
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 SDS. 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_IS_RESTRICTED A service in the shortlist submitted is marked as restricted. Although it may satisfy the search criteria provided, the user can’t refer into it directly but needs to first refer into one of its authorised pathway services. This also applies to pathway services
SHORTLISTED_SERVICE_NOT_AUTH_PATHWAY Service “A” is shortlisted as an authorised pathway for service “B”, but e-RS finds that actually “A” is not an authorised pathway for “B”
SHORTLISTED_SERVICE_NOT_IN_RESULTS A service in the shortlist submitted does not satisfy the search criteria provided. This also applies to the scenario of services shortlisted as authorised pathways of a restricted service, in the case where the restricted service specified in the pathway for field does not satisfy the search criteria
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; or: a referrer right override comment is not provided when one or more of the shortlisted services is marked as unaccredited

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