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 aims to make available e-RS functionality which will allow the retrieval of the “Advice and Guidance Requests” worklist by a Service Provider. The behaviour for this retrieval is very similar to retrieval of worklists for Appointment Requests (e.g. the “Referrals for Review” worklist) but references FHIR ‘CommunicationRequest’ resources which are used to model e-RS Advice and Guidance Requests.
Request Operation: URL
| Method | URL | Authentication |
|---|---|---|
| POST | {Base URL}/STU3/v1/CommunicationRequest/$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”
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 Authentication and Authorisation APIs |
| Content-Type |
*/*, application/fhir+json
|
Request Operation: Body
| Name | Cardinality | Type | Description |
|---|---|---|---|
| listType | 1..1 | CodeableConcept | Indicates the type of list requested, this is currently fixed to ‘ADVICE_AND_GUIDANCE_REQUESTS |
| 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/CommunicationRequest/$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 entries from the ‘Advice and Guidance Requests’ worklist matching the input criteria are returned and the response code 200 (OK) is returned.
The Response Body is in the structure of a eRS-FetchWorklist-List-1 and each entry within the List includes Extension-eRS-AdviceAndGuidanceRequests-WorkListItem-1.
The fields within this extension are specific to the Advice and Guidance Requests worklist as follows:
| Field | Description |
|---|---|
| priority | Priority of the Advice and Guidance Request from the CodeableConcept eRS-Priority-1 |
| category | The status of the Advice and Guidance Request. A Codeable Concept from eRS-AdviceAndGuidanceStatus-1 |
| adviceLastUpdated | DateTime when the Advice and Guidance Request was last updated |
| adviceFirstRequested | DateTime when the Advice and Guidance Request was first requested |
| referrer | The Referrer of the Advice and Guidance Request. Reference to a Practitioner by UID in SDS |
| service | Reference to an e-RS Service by Service Id |
| specialty | Specialty of the Service from CodeableConcept SPECIALTY |
| clinicType | Specialty of the Service from CodeableConcept CLINIC-TYPE |
| namedClinician | Reference to a Practitioner used within the Service Search by UID in SDS. Only present if service search included ‘Named Clinician’. |
| patient | Reference to the Patient associated with the Advice and Guidance Request by NHS Number. |
The ‘item.reference’ field within each entry in the FHIR List returned is a reference to a FHIR ‘CommunicationRequest’ resource. This reference can be used to retrieve the full Advice and Guidance Request as a FHIR ‘CommunicationRequest’ resource.
CodeableConcept https://baseURL/STU3/CodeSystem/eRS-CommunicationListSelector-1 is new for this worklist. It has, for now, only a single value as follows:
| Value | Meaning |
|---|---|
| ADVICE_AND_GUIDANCE_REQUESTS | Select the ‘Advice and Guidance Requests’ worklist |
Example Response Header
"X_ERS_TRANSACTION_ID" : "bfa90094-981a-4d2a-ad56-a17429865241-1",
"Content-Type" : "application/fhir+json"
Example Response Body
The following example contains a single entry on the worklist:
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. |
