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 endpoint allows an authenticated Service Provider or Service Provider Clinician to check what type of action they can perform on a Referral.
Currently, the only supported response is the ability to “Record Review Outcome” (which can be actioned via A028: Record Review Outcome). Additional ‘available actions for users’ will be added in the future.
Request Operation: URL
Method | URL | Authentication |
---|---|---|
GET | {Base URL}/STU3/v1/Task?focus=ReferralRequest/{ubrn}/_history/{version}&intent=proposal&status=ready | Session Token (Details) |
- {Base URL} (e.g. for Dev1) = https://api.dev1.ers.ncrs.nhs.uk/ers-api
- The {ubrn} represents the unique booking reference number of the Referral request
Operation Definition
- There is no “input” definition as this is a RestFUL “search”.
- There is no “output” definition because we return http://hl7.org/fhir/STU3/StructureDefinition/Bundle (which in turn references https://fhir.hl7.org.uk/STU3/StructureDefinition/CareConnect-Task-1).
Prerequisite Conditions
- You must (currently) be authenticated as a Service Provider Clinician or a Service Provider Clinician Admin.
- You should obtain the UBRN before using this endpoint, as the current UBRN version is required.
Compliance Requirements
SHOULD NOT
- You SHOULD NOT cache the list of available user actions. This is because the endpoint gives the actions available to the user at the time of calling the endpoint. If you call the endpoint even 1 second later, the user might have access to different actions, leading to potential failure flows.
INPUT
Example Request Header
XAPI_ASID:999000000043 (The “Accredited System ID” issued to the third party)
HTTP_X_SESSION_KEY:pro-api-session:e96357b1-298d-4159-ac58-a8953c3262c6" (The session key generated by A001 - Create Session endpoint)
Content-Type: "application/fhir+json"
Request Operation: Parameters
- None. The URL itself contains all that is required.
OUTPUT
Example Response Body
Response: Failure
Outcome | Note |
---|---|
REFERENCE_NOT_FOUND | The Referral does not exist |
HISTORY_NOT_SUPPORTED | Only the current version of the UBRN is permissible |
MISSING_PARAMETER | “intent” and/or “status” parameters are not included |
INVALID_VALUE | “intent” and/or “status” parameters are not “proposal” and/or “ready” respectively |
Note: other “generic” errors concerning FHIR/JSON errors can also be returned.