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
This API lets authorised users retrieve the ‘Referrals for Review’ and/or ‘Appointment Slot Issues’ work lists. ‘Referrals for Review’ and ‘Appointment Slot Issues’ are ListTypes as detailed below.
Resource URL
Method | URL | Authentication |
---|---|---|
POST | {Base URL}/STU3/v1/ReferralRequest/$ers.fetchworklist | Session Token (Details) |
- {Base URL} (Dev1) = https://api.dev1.ers.ncrs.nhs.uk/ers-api
Operation Definition
Prerequisite Conditions
The user is authenticated with an effective business function of Service Provider Clinician or Service Provider Admin. For a login business function of Service Provider Clinician Admin, the effective business function is Service Provider Clinician since the login is “on behalf of”.
ListType: Referrals for Review
INPUT
Request Operation: Header
Field Name | Description |
---|---|
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) |
Content-Type | Example: “*/*, application/fhir+json” |
Request Operation: Parameters
Name | Cardinality | Type | Description |
---|---|---|---|
listType | 1..1 | CodeableConcept | Indicates the type of list requested, in this case ‘REFERRALS_FOR_REVIEW’. |
service | 0..1 | Identifier | The service identifier |
specialtyAssignedIndicator | 0..1 | CodeableConcept | Indicates whether a Specialty is assigned to the Referral Request. If ‘Assigned’ the ‘Specialty’ parameter must be present. If ‘Not Assigned’ the ‘specialtyAssignedIndicator’ and ‘Specialty’ parameter must be absent. |
specialty | 0..1 | CodeableConcept | The Specialty for the service. If present, the ‘specialtyAssignedIndicator’ parameter must be set to ‘Assigned’. The specialty list must be retrieved dynamically from the e-RS valueset. |
location | 0..1 | Identifier | The service location identifier. |
clinicianAssignedIndicator | 0..1 | CodeableConcept | Indicates whether a clinician is assigned to the Referral Request. If ‘Assigned’ the ‘Clinician’ parameter must be present. If ‘Not Assigned’ the ‘Clinician’ parameter must be absent. |
clinician | 0..1 | Identifier | The clinician assigned to the Referral Request. If present, the ‘ClinicianAssignedIndicator’ parameter must be set to ‘Assigned’ |
Example URI
https://api.dev1.ers.ncrs.nhs.uk/ers-api/STU3/v1/ReferralRequest/$ers.fetchworklist
Example Request Header
"XAPI_ASID" : "999000000045",
"HTTP_X_SESSION_KEY" : "pro-api-session:06bdd8aa-da2c-45dc-bc73-bee80b70fe2d",
"Content-Type" : "application/fhir+json"
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, all referrals from the ‘Referrals for Review’ worklist matching the input criteria are returned. The response code 200 (OK)
is returned.
The Response Body is a eRS-FetchWorklist-List-1
Example Response Header
"X_ERS_TRANSACTION_ID" : "bfa90094-981a-4d2a-ad56-a17429865241-1",
"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:
OutcomeKey | Description | Suggested Diagnostic | |
---|---|---|---|
NO_RELATIONSHIP | The SPC user (or if SPCA, SPC user they are “on behalf of”) is not a workgroup member for the worklist. | The professional user must be associated to the following by current workgroup membership at the same e-RS organisation that the ““owner”” professional user is logged-in under: Service Location (if provided) Specialty (if provided) |
|
MISSING_VALUE | Either one or both of the following fields have not been provided: Specialty Clinician The field is reported as the location of the error. |
When attempting to filter the worklist by specialty and/or clinician, the value for specialty assigned or clinician assigned is ‘assigned’. A specialty or clinician must be provided in this scenario. | ” |
UNEXPECTED_FIELD | A value for specialty and/or clinician has been provided when not required. The field is reported as the location of the error. | When attempting to filter the worklist by specialty and/or clinician, the value for specialty assigned or clinician assigned is not ‘assigned’, a specialty or clinician is not required. | |
NO_SUCH_SERVICE | The service provided does not exist in e-RS. | When attempting to filter the worklist by service, the service ID must match an existing service in the eRS application. Check the service is still active and published in the DOS (directory of services). | |
NO_SUCH_LOCATION | The location does not match a service location in e-RS. | When attempting to filter the worklist by location, the location ID must match an existing location in the eRS application. Check the organisation is still active and not closed. | |
NO_SUCH_SPECIALTY | The specialty provided is not part of e-RS reference data. | When attempting to filter the worklist by specialty, the provided specialty is not recognised. Check against existing reference data. | |
NO_SUCH_CLINICIAN | The clinician provided is not a recognised professional user in e-RS. | When attempting to filter the worklist by clinician, the provided clinician is not recognised. Check against existing reference data. | |
INVALID_VALUE | The specialty assigned value is ‘Not Assigned’. | This value may be allowed in future worklists. |
ListType: Appointment Slot Issues
INPUT
Request Operation: Header
Field Name | Description |
---|---|
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) |
Content-Type | Example: “*/*, application/fhir+json” |
Request Operation: Parameters
The body of the Request is the same as for retrieving a ‘Referrals for Review’ worklist except that the value of the ‘listType’ parameter is ‘APPOINTMENT_SLOT_ISSUES’.
The same filtering parameters that can be used with ‘Referrals for Review’ can be included if required and function the same way as for the ‘Referrals for Review’ worklist, as follows:
Name | Cardinality | Type | Description |
---|---|---|---|
listType | 1..1 | CodeableConcept | Indicates the type of list requested, in this case ‘APPOINTMENT_SLOT_ISSUES’. |
service | 0..1 | Identifier | The service identifier |
specialtyAssignedIndicator | 0..1 | CodeableConcept | Indicates whether a Specialty is assigned to the Referral Request. If ‘Assigned’ the ‘Specialty’ parameter must be present. If ‘Not Assigned’ the ‘specialtyAssignedIndicator’ and ‘Specialty’ parameter must be absent. |
specialty | 0..1 | CodeableConcept | The Specialty for the service. If present, the ‘specialtyAssignedIndicator’ parameter must be set to ‘Assigned’. The specialty list must be retrieved dynamically from the e-RS valueset. |
location | 0..1 | Identifier | The service location identifier. |
clinicianAssignedIndicator | 0..1 | CodeableConcept | Indicates whether a clinician is assigned to the Referral Request. If ‘Assigned’ the ‘Clinician’ parameter must be present. If ‘Not Assigned’ the ‘Clinician’ parameter must be absent. |
clinician | 0..1 | Identifier | The clinician assigned to the Referral Request. If present, the ‘ClinicianAssignedIndicator’ parameter must be set to ‘Assigned’ |
Example URI
https://api.dev1.ers.ncrs.nhs.uk/ers-api/STU3/v1/ReferralRequest/$ers.fetchworklist
Example Request Header
"XAPI_ASID" : "999000000045",
"HTTP_X_SESSION_KEY" : "pro-api-session:06bdd8aa-da2c-45dc-bc73-bee80b70fe2d",
"Content-Type" : "application/fhir+json"
OUTPUT
Response: Success
If successful, all referrals from the ‘Referrals for Review’ worklist matching the input criteria are returned. The response code 200 (OK)
is returned.
The Response Body is, as for the ‘Referrals for Review’ worklist, a “eRS-FetchWorklist-List-1” but each entry within the List includes an extension of https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-AppointmentSlotIssues-WorkListItem-1.
The fields within this extension are specific to the Appointment Slot Issues worklist as follows:
Field | Description |
---|---|
priority | Priority of the Appointment Request from the CodeableConcept https://fhir.nhs.uk/STU3/CodeSystem/eRS-Priority-1 |
eReferralPathwayStart | DateTime when the Pathway associated with the Appointment Request started. |
ubrnReceived | DateTime when the Appointment Request was deferred to the Service. |
patientContactExpected | Date by when the Patient has been told to expect to be contacted. |
clinicalInformationStatus | A Codeable Concept from https://fhir.nhs.uk/STU3/CodeSystem/eRS-ClinicalInformationStatus-1. |
clinicalInfoPrinted | Boolean indicating if the latest Clinical Information has been marked as printed. |
service | Information regarding e-RS Service including Service Id and name. |
specialty | Specialty of the Service from CodeableConcept https://fhir.nhs.uk/STU3/CodeSystem/eRS-Specialty-1. |
namedClinician | Reference to a Practitioner used within the Service Search by UID in SDS. Only present if service search included ‘Named Clinician’. |
reason | Reason for Slot Issue from CodeableConcept https://fhir.nhs.uk/STU3/CodeSystem/eRS-ReviewReason-1 |
patient | Reference to the Patient associated with the Appointment Request by NHS Number. |
lastContact | DateTime when the last contact with the Patient was attempted. Only present if there has been such an attempt. |
CodeableConcept https://fhir.nhs.uk/STU3/CodeSystem/eRS-ClinicalInformationStatus-1 is new for this worklist. Its values and their meanings are as follows:
Value | Meaning |
---|---|
PRESENT | There is Referrer Clinical Information associated with the Appointment Request’s Pathway. |
NOT_APPLICABLE | There is no indicated intention to add Clinical Information AND the ‘deferred-to’ Service does NOT require a Referral Letter AND there is no Referrer Clinical Information in the Pathway. |
NOT_DUE | There is an indicated intention to add Clinical Information BUT the Letter Due Date for the Appointment Request is in the future. |
OVERDUE | There is an indicated intention to add Clinical Information AND the Letter Due Date for the Appointment Request is the current date or in the past. |
Example Response Header
"X_ERS_TRANSACTION_ID" : "bfa90094-981a-4d2a-ad56-a17429865241-1",
"Content-Type" : "application/fhir+json"
Response Example (JSON) The following example contains a single entry on the worklist.
Response: Failure
Failure conditions are the same as for retrieving the ‘Referrals for Review’ worklist.