Search loading...

API Hub

Explore and Make use of Nationally Defined Messaging APIs

 

A008: Retrieve Worklist

If you are using the deprecated FHIR v2 endpoint, please click here.

Status: Live

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

eRS-FetchWorklist-Operation-1

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 Reference to an e-RS Service by Service Id.
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.


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