e-RS A008 request with (error) response

e-Referral Service (e-RS) e-Referral Service FHIR API
1

I tried to call INT eRS API but failed with below error, would you please advise what information I missed?

The A008 request and response for your reference:

POST https://int.api.service.nhs.uk/referrals/FHIR/STU3/ReferralRequest/$ers.fetchworklist

Accept: application/fhir+json

Content-Type: application/fhir+json

User-Agent: bruno-runtime/2.14.2

nhsd-end-user-organisation-ods: RYY

nhsd-ers-business-function: SERVICE_PROVIDER_CLINICIAN

Authorization: Bearer gs1VCi14fGcKOebHvZpMgAKwDA4B

{

  "resourceType": "Parameters",

  "meta": {

    "profile": [

      "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-FetchWorklist-Parameters-1"

    ]

  },

  "parameter": [

    {

      "name": "listType",

      "valueCodeableConcept": {

        "coding": [

          {

            "system": "https://fhir.nhs.uk/STU3/CodeSystem/eRS-ReferralListSelector-1",

            "code": "AWAITING_BOOKING"

          }

        ]

      }

    }

  ]

}

SSL validation: enabled

ALPN: offers h2, http/1.1

CA Certificates: 150 root, 111 system, 0 extra, 0 custom

Trying int.api.service.nhs.uk:443...

DNS lookup: int.api.service.nhs.uk -> 35.234.138.138

Connected to int.api.service.nhs.uk (35.234.138.138) port 443

SSL connection using TLSv1.2 / ECDHE-RSA-AES256-GCM-SHA384 (TLSv1/SSLv3)

ALPN: server accepted None

Server certificate:

 subject: C=GB, L=Leeds, O=NHS Digital, CN=int.api.service.nhs.uk

 start date: Aug 26 00:00:00 2025 GMT

 expire date: Apr 27 23:59:59 2026 GMT

 subjectAltName: DNS:int.api.service.nhs.uk

 issuer: C=US, O=DigiCert Inc, CN=DigiCert Global G2 TLS RSA SHA256 2020 CA1

SSL certificate verify ok.

there was an error executing the request!

HTTP/1.1 422 

date: Wed, 11 Feb 2026 13:45:31 GMT

content-type: application/fhir+json

transfer-encoding: chunked

connection: keep-alive

x-content-type-options: nosniff

x-xss-protection: 0

cache-control: no-cache, no-store, max-age=0, must-revalidate

pragma: no-cache

expires: 0

x-frame-options: DENY

strict-transport-security: max-age=31536000; includeSubDomains

x-request-id: 5e49cd13-b1a5-4b46-99f6-2b58021dd886-1

request-duration: 222

"{\"meta\":{\"profile\":[\"https://fhir.nhs.uk/STU3/StructureDefinition/eRS-OperationOutcome-1\"]},\"resourceType\":\"OperationOutcome\",\"issue\":[{\"severity\":\"error\",\"code\":\"business-rule\",\"details\":{\"coding\":[{\"code\":\"INAPPROPRIATE_VALUE\",\"system\":\"https://fhir.nhs.uk/STU3/CodeSystem/eRS-APIErrorCode-1\",\"display\":\"Inappropriate value\"}]},\"diagnostics\":\"Business Function (SERVICE_PROVIDER_CLINICIAN) is not valid for AWAITING_BOOKING worklist\"}]}"
2

Hi @Jerry_Ng ,

The Service Provider Clinician role is not authorised to use this endpoint, as it is only available from the following roles:

  • REFERRING_CLINICIAN

  • REFERRING_CLINICIAN_ADMIN

  • REFERRING_ADMIN

Find more info on A008 here: e-Referral Service - FHIR API - NHS England Digital

As a Service Provider Clinician, you can access A023 to access advice and guidance request worklists. Find more info on A023 here: e-Referral Service - FHIR API - NHS England Digital

Thanks,

Ed

3

We are trying to retrieve the “appointment for Booking” worklist from eRS via API.

Tried to do so through A023, but no triaged record can be retrieved.
Just want to clarify with API should be used to retrieve the “appointment for Booking” with The Service Provider Clinician role?

image (27)
image (27)1939×905 65.5 KB

4

Hi,

Any update on my follow query?

5

Hi @Jerry_Ng Please see the OAS spec for details on the A008 worklist API, by your description you’re acting in a provider role.

https://digital.nhs.uk/developer/api-catalogue/e-referral-service-fhir#post-/STU3/ReferralRequest/$ers.fetchworklist

Other than the A&G worklist (A023), the only retrievable worklists are (via A008):

  • The ‘Referrals for Review’ worklist contains booked and RAS (triage) referrals that require review by the service provider organisation. The version of each referral in the worklist will also be returned. Note that the version can change due to admin/clinical changes as well as internal e-RS processes.

  • The ‘Appointment Slot Issues’ worklist contains referrals which have been ‘deferred to provider’ because of a lack of appointment availability (e.g. no appointment slots). The referrals need to be reviewed and if appropriate booked into a service at the service provider organisation.

6

Thanks for your reply, i tried the referral for review worklist via A008, it is not working. As I need to retrieve the worklist I uploaded in my previous reply, which is “appointment for booking” worklist displayed in frontend.
I believe it should be included in “AWAITING_BOOKING” worklist but i can’t get any record return.
Would you please advise how to to get the “appointment for booking” worklist from eRS API?

7

Hello, please pay special attention to the roles and permissions for each request detailed in the OAS Spec. You’ve detailed the Awaiting Booking worklist but this is only available via a referrer role NOT a provider role, and you previously mentioned you were using a service provider role in an attempt to access it. This worklist is not available for providers via the API.