# This is an OpenAPI Specification (https://swagger.io/specification/) # for the e-Referral Service API # owned by NHS Digital (https://digital.nhs.uk/) openapi: 3.0.0 x-nhsd-api-platform: meta: service_name: e-referrals-service-api short_service_name: ers service_base_path: referrals product_display_name: e-Referrals-Service product_description: 'The NHS e-RS vision is to enable local innovation and adoption of paperless referrals. To support this vision NHS Digital have created a set of APIs which provide a well-defined, simple to use data interface to the NHS e-Referral Service (e-RS). See https://developer.nhs.uk/apis/e-Referrals/index.html' pipeline_name_prefix: E-Referrals-Service info: version: 0.0.1 title: e-Referrals Service description: | ## Overview Use this API to create paperless referrals from primary to secondary care with the [e-Referral Service (e-RS)](https://digital.nhs.uk/services/e-referral-service). **As a primary care referrer, you can:** - create a new e-referral - search for relevant patient services to create a shortlist - access existing e-referrals - create a triage request for the Referral Assessment Service (RAS) - upload and manage a patient letter or attachments, linking them to a referral - retrieve appointment slots and book appointments - defer a booking to a provider if an appointment slot is unavailable **As a secondary care provider, you can:** - access referrals as a worklist - retrieve non-clinical information (meta-data) about the referral - retrieve attachments which are linked to a referral or triage (RAS) request - retrieve clinical information which has been provided by a referrer - accept or reject a referral request - retrieve Advice & Guidance (A&G) conversations and send responses - convert Advice & Guidance (A&G) conversations into a referral **You cannot use this API to:** - get patient details – instead, use the [[HYPERLINK_PDS]] **You can access the following data:** - referral attachments - referral letters - appointment slots - worklists for referral requests - worklists for triage (RAS) requests - worklists for Advice and Guidance (A&G) requests - conversation histories for Advice and Guidance (A&G) requests ### Access modes This API has two access modes: | Access mode | Authentication via | Functions | Availability | | ----------------------------- | -------------------------- | ----------------------- | ------------------------------- | | Application-restricted, unattended access | [Signed JWT](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication) | [A004](#api-Default-a004-retrieve-reference-data), [A005](#api-Default-a005-retrieve-referral-request), [A006](#api-Default-a006-retrieve-attachment) and [A007](#api-Default-a007-retrieve-clinical-information) | [Alpha](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#api-status) | | Healthcare worker, user-restricted access | [CIS2](https://digital.nhs.uk/services/identity-and-access-management/nhs-care-identity-service-2/care-identity-authentication/ways-to-authenticate-with-nhs-cis2) | All [Endpoints](#api-endpoints) | [Beta](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#api-status) | ##### Application-restricted, unattended access This access mode has been introduced to allow a Partner application which has been [registered with us](https://portal.developer.nhs.uk/create-a-developer-account) and [authenticated via signed JWT](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication) to interact with a subset of e-RS FHIR API endpoints in an unattended and read-only fashion. Application-restricted, unattended access should only be used when authenticating a human user (for example via smartcard) is not possible. Writing changes (such as Create Referral) are not supported via this access mode. ##### Healthcare worker, user-restricted access This access mode allows Partner applications to access e-RS FHIR API endpoints by authenticating users with [NHS Care Identity Service 2 (CIS2)](https://digital.nhs.uk/services/identity-and-access-management/nhs-care-identity-service-2/care-identity-authentication/ways-to-authenticate-with-nhs-cis2). This access mode must be used for writing changes (such as Create Referral). ## Who can use this API You can use this API if you are a software developer wishing to interact with the e-referrals service (e-RS) data. To use this API: - you must have justification for doing so - you must register with the [e-RS Partners Service](https://developer-test.nhs.uk/apis/e-Referrals/getstarted_partner_registration.html) - as an e-RS Partner, we offer you guidance and support for onboarding via the e-RS Partners Service which can be contacted via emailing [nhserspartners@nhs.net](mailto:nhserspartners@nhs.net) - you must [assure](https://developer.nhs.uk/apis/e-Referrals/assure_compliance_approach.html) your solution before we grant access to live data - clinical safety remains your responsibility (and the responsibility of your end user organisations), as laid out in the NHS e-RS Integration API [compliance approach](https://developer.nhs.uk/apis/e-Referrals/assure_compliance_approach.html) See the [[HYPERLINK_ONBOARDING]] section below for more information. ## Related APIs [HL7 V3 API](https://digital.nhs.uk/developer/api-catalogue/e-referral-service-hl7-v3) - this API allows you to manage appointment slots for a Patient Administration System (PAS). ## API status and roadmap ### Application-restricted, unattended access This access mode is in [alpha](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#api-status), meaning: - it is available for testing in the Alpha environment only - we might make breaking changes ### Healthcare worker, user-restricted access The e-RS FHIR STU3 API is in [[HYPERLINK_BETA]] when accessed using [[HYPERLINK_CIS2]]. There is also one FHIR R4 endpoint, [[HYPERLINK_A030]] endpoint, as part of our beta. We plan to move more endpoints into the FHIR R4 standard in the future, as part of our [roadmap](https://digital.nhs.uk/services/e-referral-service/the-future-of-the-nhs-e-referral-service#future-service-roadmap). For the current e-RS roadmap see [the future of the NHS e-referral service](https://digital.nhs.uk/services/e-referral-service/the-future-of-the-nhs-e-referral-service#future-service-roadmap). ## Service level This API is a gold service, meaning it is operational and supported 24 x 7 x 365. For more details, see [service levels](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#service-levels). ## Technology This API is primarily [RESTful](https://digital.nhs.uk/developer/guides-and-documentation/api-technologies-at-nhs-digital#basic-rest) and based on [FHIR](https://digital.nhs.uk/developer/guides-and-documentation/api-technologies-at-nhs-digital#fhir) global standards for health care data exchange. ## Network access This API is available on the internet and, indirectly, on the [Health and Social Care Network (HSCN)](https://digital.nhs.uk/services/health-and-social-care-network). To use this API with NHS smartcards you do need an HSCN connection, although internet-facing alternatives are available. For more details see [Network access for APIs](https://digital.nhs.uk/developer/guides-and-documentation/network-access-for-apis). ## Security and authorisation ### Application-restricted, unattended access This access mode is [application-restricted](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis), meaning we authenticate the calling application but not the end user. You can only use this access mode when authenticating a human user (for example via smartcard) is not possible. To use this access mode, use the following security pattern: - [Application-restricted RESTful API - signed JWT authentication](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication) ### Healthcare worker, user-restricted access This access mode is [user-restricted](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#user-restricted-apis), meaning an end user must be present, authenticated and authorised. The end user must be: - present - a healthcare worker - strongly authenticated and authorised by [NHS Care Identity Service 2 (CIS2)](https://digital.nhs.uk/services/identity-and-access-management/nhs-care-identity-service-2/care-identity-authentication/ways-to-authenticate-with-nhs-cis2) To use this access mode, use one of the following security patterns: - [user-restricted RESTful API - using NHS CIS2 - combined authentication and authorisation](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/user-restricted-restful-apis-nhs-cis2-combined-authentication-and-authorisation) - [user-restricted RESTful API - using NHS CIS2 - separate authentication and authorisation](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/user-restricted-restful-apis-nhs-cis2-separate-authentication-and-authorisation) #### Role and Organisation Validation For most e-RS endpoints requests are made in the context of a specific authorised e-RS Role at a specific Organisation for the authenticated user. The e-RS Role is supplied to the endpoint via the `nhsd-ers-business-function` request header. The Organisation is supplied to the endpoint via the `NHSD-End-User-Organisation-ODS` request header. Suitable values for these request headers can be obtained from the Practitioner Role Bundle returned by [[HYPERLINK_A030]]. #### On Behalf Of User If the `SERVICE_PROVIDER_CLINICIAN_ADMIN` role is used then the User ID of the Service Provider Clinician that the Admin is acting on behalf of must be supplied via the `NHSD-eRS-On-Behalf-Of-User-ID` header. "On behalf of" is only supported for a Service Provider Clinician Admin (SPCA) acting on behalf of a Service Provider Clinician (SPC). ## Environments and testing | Environment | Base URL | | ----------------- | ---------------------------------------------------------------------- | | Sandbox | `https://sandbox.api.service.nhs.uk/referrals/FHIR` | | Alpha | See Alpha testing section below | | Integration test | `https://int.api.service.nhs.uk/referrals/FHIR` | | Production | `https://api.service.nhs.uk/referrals/FHIR` | ### Sandbox testing Our [sandbox](https://digital.nhs.uk/developer/guides-and-documentation/testing#sandbox-testing) environment: - is for developer education and early testing - only covers a limited set of scenarios - is stateless, so does not actually persist any updates - is open access, so does not allow you to test authorisation Try out the sandbox using our 'Try this API' feature, see the documentation for each endpoint. The sandbox will only respond to an input which exactly matches one of the examples provided; it is otherwise stateless. ### Alpha testing Our [alpha](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#api-status) environment: - is available for early developer testing of future functionality - may experience breaking changes or downtime without advance notice, but only if we cannot avoid it - can be accessed by contacting [nhserspartners@nhs.net](mailto:nhserspartners@nhs.net) ### Integration testing Our integration test environment: - is where the majority of your integration efforts will take place - is where we conduct witness testing for your application - is stateful, so data will be persisted ## Onboarding You need to get your software approved by us before it can go live. We call this process onboarding. Onboarding essentially involves connecting to the Path-to-Live (PTL) environments, assuring your solution and going live, in accordance with the [Supplier Conformance Assessment List (SCAL) process](https://digital.nhs.uk/developer/guides-and-documentation/onboarding-process#onboard-using-the-supplier-conformance-assessment-list-scal-process). In order to pass through the onboarding process as efficiently as possible, it is worth planning ahead. When following the general SCAL process, please note: In step 1: to use this API, you need to register with [nhserspartners@nhs.net](mailto:nhserspartners@nhs.net) using [Partner Registration](https://developer.nhs.uk/apis/e-Referrals/getstarted_partner_registration.html) and discuss your use case with us. You must also register with the API Management team via [https://digital.nhs.uk/developer/getting-started](https://digital.nhs.uk/developer/getting-started) to register your application. In step 2: to request a SCAL, please ensure you have discussed your solution with the Partners service via [nhserspartners@nhs.net](mailto:nhserspartners@nhs.net), who will put you in touch with [ersapi.assurance@nhs.net](mailto:ersapi.assurance@nhs.net) who are responsible for assurance of solutions that integrate with the e-RS FHIR API. In step 8: to organise witness testing of your solution, please liaise with [ersapi.assurance@nhs.net](mailto:ersapi.assurance@nhs.net). In step 11: when submitting your SCAL for review, please liaise with [ersapi.assurance@nhs.net](mailto:ersapi.assurance@nhs.net). In step 12: to obtain a Connection Agreement, please liaise with [interop.mgmt@nhs.net](mailto:interop.mgmt@nhs.net). You will need to have successfully passed witness testing with [ersapi.assurance@nhs.net](mailto:ersapi.assurance@nhs.net) and obtained a Technical Conformance Certificate (TCC). In step 13: to obtain the End User Organisation Acceptable Use Policy, please liaise with [interop.mgmt@nhs.net](mailto:interop.mgmt@nhs.net). In step 14: to request production access, send your completed SCAL and TCC to [interop.mgmt@nhs.net](mailto:interop.mgmt@nhs.net). To activate your application in production please [contact us](https://digital.nhs.uk/developer/help-and-support). contact: url: 'https://digital.nhs.uk/developer/help-and-support' email: api.management@nhs.net license: name: MIT servers: - url: 'https://sandbox.api.service.nhs.uk/referrals/FHIR' description: Sandbox environment. - url: 'https://int.api.service.nhs.uk/referrals/FHIR' description: Integration test environment. - url: 'https://api.service.nhs.uk/referrals/FHIR' description: 'Production environment. Not yet available.' paths: /STU3/ReferralRequest/$ers.createReferral: post: security: - bearerAuth: [] description: | ## Overview Use this endpoint to create a referral by choosing a shortlist of bookable services. Please note: this endpoint cannot be used to shortlist triage services. In order to make use of triage services please use [[HYPERLINK_A021]]. ## Supported security patterns - Healthcare worker, user-restricted access ## Pre-requisites In order to use this endpoint you must be an authenticated e-RS user and use one of the following e-RS roles: - `REFERRING_CLINICIAN` - `REFERRING_CLINICIAN_ADMIN` You need to have identified a `patient`, for example via [[HYPERLINK_PDS]]. You need to have found services that meet the referral needs of a patient using [[HYPERLINK_A010]]. ## Use case As an authenticated user I need to create a shortlist of bookable services So I can initiate my patients referral pathway, allowing the patient to book into one of the shortlisted services. ## Related endpoints To allow the patient to book their appointment in their own time, you can generate a letter for the patient by using [[HYPERLINK_A019]]. The letter summarises the current state of the referral and any steps the patient may need to follow (e.g. appointment booking instructions). You can book an appointment for the patient by using [[HYPERLINK_A015]] and [[HYPERLINK_A016]]. For the referral to be processed by the service provider, you must ensure appropriate referral letter information has been added to the referral. You can add/manage referrer letter information by using [[HYPERLINK_A012]]. You can check to see what referral letter information has already been added to a referral by using [[HYPERLINK_A005]], [[HYPERLINK_A007]], and [[HYPERLINK_A006]] endpoints where necessary. You can generate a letter for the patient, which summarises the current state of their referral and any steps the patient may need to follow, by using [[HYPERLINK_A019]]. summary: A011 - Create referral operationId: a011-create-referral parameters: - $ref: 'components/schemas/headers/request/ContentTypeFhirJson.yaml' - $ref: 'components/schemas/headers/request/BearerAuthorization.yaml' - $ref: 'components/schemas/headers/request/OdsCode.yaml' - $ref: 'components/schemas/headers/request/BusinessFunction.yaml' - $ref: 'components/schemas/headers/request/CorrelationID.yaml' requestBody: required: true content: application/fhir+json: schema: $ref: 'components/schemas/eRS-CreateReferral-Parameters.yaml' examples: rc-minimum-request-body: summary: Referring Clinician - minimum request body value: $ref: 'components/examples/createReferral/requests/MinimalRequest.json' rc-request-body-multi-service-shortlist: summary: Referring Clinician - request body using multi-service shortlist value: $ref: 'components/examples/createReferral/requests/RequestTwentyServices.json' create-referral-parameters-twenty-services: summary: Referring Clinician Admin - minimum request body value: $ref: 'components/examples/createReferral/requests/MinimalRequestWithReferringClinician.json' responses: '201': $ref: 'components/schemas/responses/createReferral/201Response.yaml' '400': $ref: 'components/schemas/responses/BadRequest.yaml' '401': $ref: 'components/schemas/responses/Unauthorized.yaml' '403': $ref: 'components/schemas/responses/Forbidden.yaml' '406': $ref: 'components/schemas/responses/NotAcceptable.yaml' '415': $ref: 'components/schemas/responses/UnsupportedMediaType.yaml' '422': $ref: 'components/schemas/responses/CreateReferralErrorOutcome.yaml' '429': $ref: 'components/schemas/responses/TooManyRequests.yaml' '500': $ref: 'components/schemas/responses/InternalServerError.yaml' /STU3/ReferralRequest/$ers.createReferralAndSendForTriage: post: security: - bearerAuth: [] description: | ## Overview Use this endpoint to refer the patient directly to a triage service. Please note: this endpoint cannot be used to shortlist bookable services. In order to shortlist bookable services please use [[HYPERLINK_A011]]. ## Supported security patterns - Healthcare worker, user-restricted access ## Pre-requisites In order to use this endpoint you must be an authenticated e-RS user and use one of the following e-RS roles: - `REFERRING_CLINICIAN` - `REFERRING_CLINICIAN_ADMIN` You need to have identified a `patient`, for example via [[HYPERLINK_PDS]]. You need to have found services that meet the referral needs of a patient using [[HYPERLINK_A010]]. ## Use case As an authenticated user I need to send the patient's referral to a triage service for assessment So that I can put the patient on the appropriate clinical pathway for the chosen service provider. ## Related endpoints For the referral to be processed by the service provider, you must ensure appropriate referral letter information has been added to the referral. You can add/manage referrer letter information by using [[HYPERLINK_A012]]. You can check to see what referral letter information has already been added to a referral by using [[HYPERLINK_A005]], [[HYPERLINK_A007]], and [[HYPERLINK_A006]] endpoints where necessary. You can generate a letter for the patient by using [[HYPERLINK_A019]]. The letter summarises the current state of the referral and any steps the patient may need to follow. You can calculate the date when the patient will need to be contacted (by the triage service) using reference data from [[HYPERLINK_A004]]. summary: A021 - Create referral and send for triage operationId: a021-create-referral-request-and-send-for-triage parameters: - $ref: 'components/schemas/headers/request/ContentTypeFhirJson.yaml' - $ref: 'components/schemas/headers/request/BearerAuthorization.yaml' - $ref: 'components/schemas/headers/request/OdsCode.yaml' - $ref: 'components/schemas/headers/request/BusinessFunction.yaml' - $ref: 'components/schemas/headers/request/CorrelationID.yaml' requestBody: required: true content: application/fhir+json: schema: $ref: 'components/schemas/eRS-CreateReferralAndSendForTriage-Parameters.yaml' examples: parameters: summary: Referring Clinician creates referral to a Triage service value: $ref: 'components/examples/createReferralAndSendForTriage/requests/Parameters.json' parameters-with-named-clinician: summary: Referring Clinician Admin minimum call value: $ref: 'components/examples/createReferralAndSendForTriage/requests/ParametersWithNamedClinician.json' responses: '201': $ref: 'components/schemas/responses/createReferralAndSendForTriage/201Response.yaml' '400': $ref: 'components/schemas/responses/BadRequest.yaml' '401': $ref: 'components/schemas/responses/Unauthorized.yaml' '403': $ref: 'components/schemas/responses/Forbidden.yaml' '406': $ref: 'components/schemas/responses/NotAcceptable.yaml' '415': $ref: 'components/schemas/responses/UnsupportedMediaType.yaml' '422': $ref: 'components/schemas/responses/CreateReferralErrorOutcome.yaml' '429': $ref: 'components/schemas/responses/TooManyRequests.yaml' '500': $ref: 'components/schemas/responses/InternalServerError.yaml' /STU3/HealthcareService/$ers.searchHealthcareServicesForPatient: post: security: - bearerAuth: [] description: | ## Overview Use this endpoint to find services that meet the referral needs of a patient. ## Supported security patterns - Healthcare worker, user-restricted access ## Pre-requisites In order to use this endpoint you must be an authenticated e-RS user and use one of the following e-RS roles: - `REFERRING_CLINICIAN` - `REFERRING_CLINICIAN_ADMIN` You need to have identified a `patient`, for example via [[HYPERLINK_PDS]]. ## Use case As an authenticated user I need to find services I can refer the patient to So that I can offer the patient appropriate services that meet their referral needs ## Related endpoints Once you have identified appropriate services for the patient you can either: - create a referral by choosing a shortlist of bookable services using [[HYPERLINK_A011]], or - refer the patient directly to a triage service using [[HYPERLINK_A021]] summary: A010 - Patient service search operationId: a010-patient-service-search parameters: - $ref: 'components/schemas/headers/request/ContentTypeFhirJson.yaml' - $ref: 'components/schemas/headers/request/BearerAuthorization.yaml' - $ref: 'components/schemas/headers/request/OdsCode.yaml' - $ref: 'components/schemas/headers/request/BusinessFunction.yaml' - $ref: 'components/schemas/headers/request/CorrelationID.yaml' requestBody: required: true content: application/fhir+json: schema: $ref: 'components/schemas/eRS-PatientServiceSearch-Parameters.yaml' examples: rc-minimal: summary: Referring Clinician minimal search value: $ref: 'components/examples/patientServiceSearch/requests/RcMinimal.json' rc-search-by-clinical-term: summary: Referring Clinician search by clinical term value: $ref: 'components/examples/patientServiceSearch/requests/RcSearchByClinicalTerm.json' rc-search-by-named-clinician: summary: Referring Clinician search by named clinician value: $ref: 'components/examples/patientServiceSearch/requests/RcSearchByNamedClinician.json' rca-with-iwt: summary: Referring Clinician Admin search value: $ref: 'components/examples/patientServiceSearch/requests/RcaWithIWT.json' responses: '200': $ref: 'components/schemas/responses/patientServiceSearch/200Response.yaml' '400': $ref: 'components/schemas/responses/BadRequest.yaml' '401': $ref: 'components/schemas/responses/Unauthorized.yaml' '403': $ref: 'components/schemas/responses/Forbidden.yaml' '406': $ref: 'components/schemas/responses/NotAcceptable.yaml' '415': $ref: 'components/schemas/responses/UnsupportedMediaType.yaml' '422': $ref: 'components/schemas/responses/patientServiceSearch/ErrorOutcome.yaml' '429': $ref: 'components/schemas/responses/TooManyRequests.yaml' '500': $ref: 'components/schemas/responses/InternalServerError.yaml' /STU3/CodeSystem/{codeSystemType}: parameters: - $ref: 'components/schemas/path/CodeSystemType.yaml' get: security: - bearerAuth: [] description: | ## Overview Use this endpoint to retrieve a list of reference data codes along with the user-friendly display values used in the e-RS Professional Application. ## Supported security patterns - Application-restricted, unattended access - Healthcare worker, user-restricted access ## Pre-requisites ### Application-restricted access In order to use this endpoint you must be an authenticated e-RS calling application. ### Healthcare worker, user-restricted access In order to use this endpoint you must be an authenticated e-RS user and use one of the following e-RS roles: - `REFERRING_CLINICIAN` - `REFERRING_CLINICIAN_ADMIN` - `SERVICE_PROVIDER_CLINICIAN` - `SERVICE_PROVIDER_CLINICIAN_ADMIN` ## Use case As an authenticated user or application I need to retrieve e-RS reference data So I can use it with other endpoints or display the reference data in a user-friendly format to my users. ## Related endpoints Reference data may be needed for other endpoints, for example when including Specialty and Clinic Type reference data to: - find services that meet the referral needs of a patient using [[HYPERLINK_A010]], and - create a referral using [[HYPERLINK_A011]] or [[HYPERLINK_A021]] You can use the Priority reference data to calculate when a patient can expect to be contacted by the service. This is important because when a patient's appointment is deferred to a service to book, the patient may be informed of the date by which they can expect to be contacted. Similarly, in the case of a triage service, a letter may inform the patient of the date by which they can expect to be contacted. You can calculate this date by: 1. Obtaining the current priority of the referral (via [[HYPERLINK_A005]]) and its associated "deferToProviderContactDays" (for deferred-to services) or "triageContactDays" (for triage services). These represent the number of "working days" and do not include weekends 2. Obtaining the datetime of the appointment resource, e.g. "created" : "2021-05-06T11:21:45.652Z" 3. Adding the "working days" to the datetime of the appointment resource For example: 1. Given a referral with a priority of `TWO_WEEK_WAIT` and a "deferToProviderContactDays" of "2" for priority `TWO_WEEK_WAIT` 2. If the appointment was created on Monday 03/01/2022 for a deferred-to service 3. The calculated date when a patient can expect to be contacted by the service would be on or before 05/01/2022 Note that the "deferToProviderContactDays" and "triageContactDays" values are dynamic, and may change independently from one another, so the above calculation is for illustration purposes only. You may also wish to present the user-friendly names for the reference data, for example when viewing the referral using [[HYPERLINK_A005]] and [[HYPERLINK_A038]]. Documentation for other endpoints will reference this endpoint, where specific reference data is required. ## Sandbox test scenarios You can test the following scenarios in our sandbox environment | Scenario | Request | Response | | --------------------------------------------------------- | ------------------------------------------------------- | ----------------------------------------- | | Retrieve speciality reference data | `codeSystemType`=`SPECIALTY` | Specialty details | | Retrieve clinic type reference data | `codeSystemType`=`CLINIC-TYPE` | Clinic type details | | Retrieve appointment cancellation reason reference data | `codeSystemType`=`APPOINTMENT-CANCELLATION-REASON` | Appointment reason type details | | Retrieve referral cancellation reason reference data | `codeSystemType`=`REFERRAL-CANCELLATION-REASON` | ReferralRequest reason type details | | Retrieve appointment non-attendance reason reference data | `codeSystemType`=`APPOINTMENT-NON-ATTENDANCE-REASON` | Appointment non-attendance reason details | | Retrieve priority reference data | `codeSystemType`=`PRIORITY` | Priority details | summary: A004 - Retrieve reference data operationId: a004-retrieve-reference-data parameters: - $ref: 'components/schemas/headers/request/BearerAuthorization.yaml' - $ref: 'components/schemas/headers/request/OdsCodeOnlyUserRestricted.yaml' - $ref: 'components/schemas/headers/request/BusinessFunctionOnlyUserRestricted.yaml' - $ref: 'components/schemas/headers/request/OnBehalfOfUserIDOnlyUserRestricted.yaml' - $ref: 'components/schemas/headers/request/CorrelationID.yaml' responses: '200': $ref: 'components/schemas/responses/getCodeSystem/200Response.yaml' '401': $ref: 'components/schemas/responses/Unauthorized.yaml' '403': $ref: 'components/schemas/responses/Forbidden.yaml' '404': $ref: 'components/schemas/responses/NotFound.yaml' '406': $ref: 'components/schemas/responses/NotAcceptable.yaml' '429': $ref: 'components/schemas/responses/TooManyRequests.yaml' '500': $ref: 'components/schemas/responses/InternalServerError.yaml' /STU3/Slot: get: description: | ## Overview Use this endpoint to retrieve available appointment slots for a service. ## Supported security patterns - Healthcare worker, user-restricted access ## Pre-requisites In order to use this endpoint you must be an authenticated e-RS user and use one of the following e-RS roles: - `REFERRING_CLINICIAN` - `REFERRING_CLINICIAN_ADMIN` You need to have identified a directly bookable `service` that is on the current referral shortlist. You can do this by using [[HYPERLINK_A005]]. ## Use case As an authenticated user I need to retrieve a list of available appointment slots for a service So that I can offer them to the patient for booking. ## Important note You need to provide the 'commissioning rule organisation' when calling A015 - Retrieve appointment slots to ensure only suitable slots are returned. You can obtain the 'commissioning rule organisation' from [[HYPERLINK_A005]]. ## Related endpoints You can book an appointment to an available slot using [[HYPERLINK_A016]]. You can defer booking to a directly bookable service using [[HYPERLINK_A016]] but only in the following circumstances: - when the service has no available slots - when trying to book an appointment into a service, the slot advertised is no longer available - when trying to book an appointment into a service, no response is received within message timeout period (currently 2 minutes) ## Sandbox test scenarios You can test the following scenarios in our sandbox environment: | Scenario | Request Query Parameters | Response | | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | | Minimum slot search | `schedule.actor:HealthcareService`=`12000`, `appointmentType`=`ROUTINE`, `_count`=`20`, `status`=`free`, `page`=`1` | Illustrates minimum usage/parameters with concise, minimal response. | | Empty slot search response | `schedule.actor:HealthcareService`=`10000`, `appointmentType`=`ROUTINE`, `_count`=`20`, `status`=`free`, `page`=`1` | Illustrates how a 'no slots' response appears. | | Multipage slot search (page 1) | `schedule.actor:HealthcareService`=`11000`, `appointmentType`=`ROUTINE`, `_count`=`5`, `status`=`free`, `page`=`1` | Illustrates first page of multi-page response. | | Multipage slot search (page 2) | `schedule.actor:HealthcareService`=`11000`, `appointmentType`=`ROUTINE`, `_count`=`5`, `status`=`free`, `page`=`2` | Illustrates second page of multi-page response. | | Multipage slot search (invalid page 5) | `schedule.actor:HealthcareService`=`11000`, `appointmentType`=`ROUTINE`, `_count`=`5`, `status`=`free`, `page`=`5` | Illustrates error when page is outside of valid range. | | Multi schedule response | `schedule.actor:HealthcareService`=`13000`, `appointmentType`=`ROUTINE`, `_count`=`5`, `status`=`free`, `page`=`1` | Illustrates response when there is >1 Schedule: one Schedule is for slots with no associated clinician and the other does have an associated clinician. | | Slot clinician search | `schedule.actor:HealthcareService`=`14000`, `schedule.actor:Practitioner`=`921600556514`, `appointmentType`=`ROUTINE`, `_count`=`5`, `status`=`free`, `page`=`1` | Illustrates search for clinician-specific slots | summary: A015 - Retrieve appointment slots operationId: a015-retrieve-appointment-slots parameters: - $ref: 'components/schemas/headers/request/BearerAuthorization.yaml' - $ref: 'components/schemas/headers/request/OdsCode.yaml' - $ref: 'components/schemas/headers/request/BusinessFunction.yaml' - $ref: 'components/schemas/headers/request/CorrelationID.yaml' - $ref: 'components/schemas/headers/request/ErsCommRuleOrg.yaml' - $ref: 'components/schemas/queryParameters/ServiceId.yaml' - $ref: 'components/schemas/queryParameters/Priority.yaml' - $ref: 'components/schemas/queryParameters/Status.yaml' - $ref: 'components/schemas/queryParameters/PageSize.yaml' - $ref: 'components/schemas/queryParameters/PageNumber.yaml' - $ref: 'components/schemas/queryParameters/NamedClinician.yaml' - $ref: 'components/schemas/queryParameters/Include.yaml' responses: '200': $ref: 'components/schemas/responses/retrieveAppointmentSlots/200Response.yaml' '400': $ref: 'components/schemas/responses/retrieveAppointmentSlots/ErrorOutcome.yaml' '401': $ref: 'components/schemas/responses/Unauthorized.yaml' '403': $ref: 'components/schemas/responses/Forbidden.yaml' '406': $ref: 'components/schemas/responses/NotAcceptable.yaml' '429': $ref: 'components/schemas/responses/TooManyRequests.yaml' '500': $ref: 'components/schemas/responses/InternalServerError.yaml' /R4/PractitionerRole: get: security: - bearerAuth: [] description: | ## Overview Use this endpoint to retrieve a list of available e-RS roles (i.e. business functions) at each organisation where the user works. ## Supported security patterns - Healthcare worker, user-restricted access ## Pre-requisites In order to use this endpoint you must be an authenticated user ## Use case As an authenticated user I need to retrieve a list of authorised e-RS roles for organisations I work for So I can choose the appropriate role and organisation to work under when performing tasks. ## Related endpoints You can then use the e-RS roles to perform specific tasks using other e-RS endpoints e.g. to satisfy Role and Organisation validation. ### Role and Organisation Validation The response from a successful call to [[HYPERLINK_A030]] represents a Practitioner Role Bundle. Each Practitioner Role represents an e-RS Role at a specific Organisation. For most e-RS endpoints requests are made in the context of a specific authorised e-RS Role at a specific Organisation for the authenticated user. This is accomplished by setting the values of the `nhsd-ers-business-function` and `NHSD-End-User-Organisation-ODS` request headers. The e-RS Role is supplied to the endpoint via the `nhsd-ers-business-function` request header. The Organisation is supplied to the endpoint via the `NHSD-End-User-Organisation-ODS` request header. The `entry` field in the response from [[HYPERLINK_A030]] is an array of PractitionerRole resources. An example of a PractitionerRole resource is: ```json "resource": { "id": "PractitionerRole-R69-000000000101", "meta": { "lastUpdated": "2021-05-24T16:09:32.252Z", "profile": [ "https://fhir.hl7.org.uk/StructureDefinition/UKCore-PractitionerRole" ] }, "resourceType": "PractitionerRole", "practitioner": { "identifier": { "system": "https://fhir.nhs.uk/Id/sds-user-id", "value": "000000000101" } }, "organization": { "identifier": { "system": "https://fhir.nhs.uk/Id/ods-organization-code", "value": "R69" } }, "code": [ { "coding": [ { "system": "https://fhir.nhs.uk/CodeSystem/eRS-BusinessFunction-1", "code": "SERVICE_DEFINER" } ] }, { "coding": [ { "system": "https://fhir.nhs.uk/CodeSystem/eRS-BusinessFunction-1", "code": "SERVICE_PROVIDER_CLINICIAN" } ] }, { "coding": [ { "system": "https://fhir.nhs.uk/CodeSystem/eRS-BusinessFunction-1", "code": "SERVICE_PROVIDER_ADMIN" } ] } ] }, ``` Each PractitionerRole resource has a `code` field which is an array of codings. The authorised e-RS Roles for the authenticated user at a particilar Organisation are represented by the `value` fields in the `https://fhir.nhs.uk/CodeSystem/eRS-BusinessFunction-1` code system. The `nhsd-ers-business-function` request header value should be the `code` field value from the relevant eRS-Business-Function-1 coding in the PractitionerRole resource e.g. `SERVICE_PROVIDER_CLINICIAN`. Each PractitionerRole resource also has an `organization` field which has an identifier in the `https://fhir.nhs.uk/Id/ods-organization-code` code system. The `NHSD-End-User-Organisation-ODS` request header value should be the `value` field value from the organization identifier in the PractitionerRole resource e.g. "R69". summary: A030 - Retrieve e-RS business functions operationId: a030-retrieve-business-functions parameters: - $ref: 'components/schemas/headers/request/BearerAuthorization.yaml' - $ref: 'components/schemas/headers/request/CorrelationID.yaml' responses: '200': $ref: 'components/schemas/responses/retrieveBusinessFunctions/200Response.yaml' '401': $ref: 'components/schemas/responses/Unauthorized.yaml' '403': $ref: 'components/schemas/responses/Forbidden.yaml' '406': $ref: 'components/schemas/responses/NotAcceptable.yaml' '429': $ref: 'components/schemas/responses/TooManyRequests.yaml' '500': $ref: 'components/schemas/responses/InternalServerError.yaml' /STU3/Binary: post: security: - bearerAuth: [] description: | ## Overview Use this endpoint to upload a file containing clinical information to e-RS ready to be associated with a referral. ## Supported security patterns - Healthcare worker, user-restricted access ## Pre-requisites In order to use this endpoint you must be an authenticated e-RS user and use one of the following e-RS roles: - `REFERRING_CLINICIAN` - `REFERRING_CLINICIAN_ADMIN` - `SERVICE_PROVIDER_CLINICIAN` - `SERVICE_PROVIDER_CLINICIAN_ADMIN` You can only upload file formats that are supported by e-RS. Currently, the supported file formats are: | File type | File extension(s) | | ------------------ | --------------------------- | | Plain Text | `.txt` | | HTML Text | `.html,` `.htm` | | PDF | `.pdf` | | XML Text | `.xml` | | RTF Text | `.rtf`, `.rtx` | | Basic Audio | `.au` | | MPEG audio layer 3 | `.mp3` | | PNG Image | `.png` | | GIF Image | `.gif` | | JPEG Image | `.jpg,` `.jpe`, `.jpeg` | | TIFF Image | `.tif`, `.tiff` | | MPEG Video | `.mpg`, `.mpeg`, `.mpe` | | MSWORD | `.doc`, `.docx` | | DICOM | `.dcm` | Currently, the maximum file size supported by e-RS is 5MB. ## Use case As an authenticated user I need to upload a referral letter or other clinical information file to e-RS So that I can associate the file with an existing referral. ## Important notes: This endpoint **only** performs the file upload. The uploaded file is **not** associated with a referral until the file has been associated with a referral, for example using [[HYPERLINK_A012]]. The resulting URL within e-RS for the uploaded file is returned in the 'Location' header of the response. ## Related endpoints You can associate the uploaded file with a specific referral using [[HYPERLINK_A012]]. summary: A020 - Upload file to document store operationId: a020-upload-file-to-document-store parameters: - $ref: 'components/schemas/headers/request/ContentTypeFileUpload.yaml' - $ref: 'components/schemas/headers/request/BearerAuthorization.yaml' - $ref: 'components/schemas/headers/request/OdsCode.yaml' - $ref: 'components/schemas/headers/request/BusinessFunction.yaml' - $ref: 'components/schemas/headers/request/OnBehalfOfUserID.yaml' - $ref: 'components/schemas/headers/request/CorrelationID.yaml' - $ref: 'components/schemas/headers/request/ErsFileName.yaml' - $ref: 'components/schemas/headers/request/ErsReferralId.yaml' requestBody: required: true content: $ref: 'components/schemas/file/FileContentTypeSchema.yaml' responses: '201': $ref: 'components/schemas/responses/uploadFileToDocumentStore/201Response.yaml' '401': $ref: 'components/schemas/responses/Unauthorized.yaml' '403': $ref: 'components/schemas/responses/Forbidden.yaml' '406': $ref: 'components/schemas/responses/NotAcceptable.yaml' '415': $ref: 'components/schemas/responses/UnsupportedMediaType.yaml' '422': $ref: 'components/schemas/responses/uploadFileToDocumentStore/422Response.yaml' '429': $ref: 'components/schemas/responses/TooManyRequests.yaml' '500': $ref: 'components/schemas/responses/InternalServerError.yaml' /STU3/ReferralRequest/{ubrn}/$ers.generatePatientLetter: post: security: - bearerAuth: [] description: | ## Overview Use this endpoint to download a PDF format letter for the patient summarising the current state of their referral and any steps the patient may need to follow. ## Supported security patterns - Healthcare worker, user-restricted access ## Pre-requisites In order to use this endpoint you must be an authenticated e-RS user and use one of the following e-RS roles: - `REFERRING_CLINICIAN` - `REFERRING_CLINICIAN_ADMIN` You need to use the `Unique Booking Reference Number` (UBRN) of a referral request in order to use this endpoint. ## Use case As an authenticated user I need to generate the patient letter including up-to-date details about their referral and any steps the patient may need to follow So that I can pass it to the patient. summary: A019 - Generate patient letter operationId: a019-generate-patient-letter parameters: - $ref: 'components/schemas/headers/request/BearerAuthorization.yaml' - $ref: 'components/schemas/headers/request/OdsCode.yaml' - $ref: 'components/schemas/headers/request/BusinessFunction.yaml' - $ref: 'components/schemas/headers/request/CorrelationID.yaml' - $ref: 'components/schemas/path/Ubrn.yaml' responses: '200': $ref: 'components/schemas/responses/generatePatientLetter/200Response.yaml' '401': $ref: 'components/schemas/responses/Unauthorized.yaml' '403': $ref: 'components/schemas/responses/Forbidden.yaml' '404': $ref: 'components/schemas/responses/NotFound.yaml' '406': $ref: 'components/schemas/responses/NotAcceptable.yaml' '422': $ref: 'components/schemas/responses/generatePatientLetter/422Response.yaml' '429': $ref: 'components/schemas/responses/TooManyRequests.yaml' '500': $ref: 'components/schemas/responses/InternalServerError.yaml' /STU3/Binary/{attachmentLogicalID}: get: security: - bearerAuth: [] description: | ## Overview Use this endpoint to retrieve a file that is attached to a referral or advice request. ## Supported security patterns - Application-restricted access - Healthcare worker, user-restricted access ## Pre-requisites ### Application-restricted access In order to use this endpoint you must be an authenticated e-RS calling application. ### Healthcare worker, user-restricted access In order to use this endpoint you must be an authenticated e-RS user or application and use one of the following e-RS roles: - `REFERRING_CLINICIAN` - `REFERRING_CLINICIAN_ADMIN` - `SERVICE_PROVIDER_CLINICIAN` - `SERVICE_PROVIDER_CLINICIAN_ADMIN` You need to have retrieved the referral via [[HYPERLINK_A005]] to obtain the URLs for its attachments. ## Important note A referral pathway in e-RS can be made up of more than one UBRN. For example, a referral is booked and seen in a general knee clinical assessment service (UBRN #1), and the service decides to onward refer to a more specialist knee miniscus service (UBRN #2). This would result in two UBRNs for the referral pathway in this example (but there could be more related UBRNs if onward referred multiple times). As such, it is important that all clinical information is obtained from across all the related UBRNs referenced in [[HYPERLINK_A005]]. You can do this using the following endpoints: - [[HYPERLINK_A007]] - A006 - Retrieve Attachment Note: It is possible that the initial UBRN may be the only one in the referral pathway to have clinical information and/or attachments associated. ## Use case As an authenticated user I need to retrieve a clinical attachment associated with a referral So that I can assess its content and decide what further action may be needed. ## Related endpoints You can retrieve a clinical information summary for a referral using [[HYPERLINK_A007]]. summary: A006 - Retrieve attachment operationId: a006-retrieve-attachment parameters: - $ref: 'components/schemas/headers/request/BearerAuthorization.yaml' - $ref: 'components/schemas/headers/request/OdsCodeOnlyUserRestricted.yaml' - $ref: 'components/schemas/headers/request/BusinessFunctionOnlyUserRestricted.yaml' - $ref: 'components/schemas/headers/request/CorrelationID.yaml' - $ref: 'components/schemas/headers/request/OnBehalfOfUserIDOnlyUserRestricted.yaml' - $ref: 'components/schemas/path/AttachmentLogicalID.yaml' responses: '200': $ref: 'components/schemas/responses/retrieveAttachment/200Response.yaml' '401': $ref: 'components/schemas/responses/Unauthorized.yaml' '403': $ref: 'components/schemas/responses/Forbidden.yaml' '404': $ref: 'components/schemas/responses/NotFound.yaml' '406': $ref: 'components/schemas/responses/NotAcceptable.yaml' '422': $ref: 'components/schemas/responses/retrieveAttachment/422Response.yaml' '429': $ref: 'components/schemas/responses/TooManyRequests.yaml' '500': $ref: 'components/schemas/responses/InternalServerError.yaml' /STU3/ReferralRequest/{ubrn}: get: security: - bearerAuth: [ ] description: | ## Overview Use this endpoint to retrieve details of a referral. This includes references to clinical attachments, related referrals and other important data. During the lifecycle of a referral, the state of the referral may change multiple times. To help with understanding the state of a referral, we provide an "at a glance" summary of the referral as detailed below: | Code returned via https://fhir.nhs.uk/STU3/CodeSystem/eRS-ReferralState-1 | Description | | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | `APPT_CANCELLED_BY_PATIENT` | The referral's most recent appointment was cancelled at the request of, or directly by, a patient | | `APPT_CANCELLED_BY_PROVIDER` | The referral's most recent appointment was cancelled by the service provider | | `ASSESSMENT_RESULT` | A service provider has reviewed and drafted, or submitted a clinical assessment for the referral | | `AWAITING_TRIAGE` | The triage referral is currently pending review with a service provider | | `BOOKED` | This referral's appointment indicates a date and time with a service | | `CANCELLED_REFERRAL` | The referral has been cancelled and cannot be progressed any further | | `DEFERRED_TO_PROVIDER` | The service provider will arrange the patient’s appointment | | `DID_NOT_ATTEND` | The patient did not attend their last appointment | | `NOT_BOOKED` | The referral is currently not booked, there is currently no planned patient encounter | | `REJECTED` | The referral was rejected by a provider at their service | | `TRIAGE_RESPONSE` | A service has passed the referral back to the referrer, with advice | | `TRIAGED_PROVIDER_TO_ACTION` | The service provider has recorded a review decision, with the intention of processing this referral | Some referral states may also have a `reason` and some reasons may also have a `comment`. These are described below: ## Reason - The reason is always connected to the current state. This means the reason is likely to change each time the state changes. You cannot currently retrieve previous versions of a referral. - This reason may have been selected by a clinician or automatically applied by the e-RS system at the time the state was persisted. - A reason can be dynamic reference data, from any of the following sets of reference data: `APPOINTMENT-CANCELLATION-REASON`, `REFERRAL-CANCELLATION-REASON`, `APPOINTMENT-NON-ATTENDANCE-REASON`. These are retrievable from [[HYPERLINK_A004]]. - A reason may be static reference data. ## Comments - The comment is always connected to the current reason, and state. This means the comment is likely to change as the state changes. ## Supported security patterns - Application-restricted access - Healthcare worker, user-restricted access ## Pre-requisites ### Application-restricted access In order to use this endpoint you must be an authenticated e-RS calling application. ### Healthcare worker, user-restricted access In order to use this endpoint you must be an authenticated e-RS user or application and use one of the following e-RS roles: - `REFERRING_CLINICIAN` - `REFERRING_CLINICIAN_ADMIN` - `SERVICE_PROVIDER_CLINICIAN` - `SERVICE_PROVIDER_CLINICIAN_ADMIN` You need to use the `Unique Booking Reference Number` (UBRN) of a referral request in order to retrieve details of a referral. ## Use case As an authenticated user or application I want to read details of a referral So that I can decide what further action may be needed. ## Related endpoints You can retrieve attachments that are associated with the referral using [[HYPERLINK_A006]] You can retrieve a clinical information summary for the referral using [[HYPERLINK_A007]] You can search for services appropriate to a referral to form a shortlist using [[HYPERLINK_A010]] If bookable services are on the shortlist of the referral, you can retrieve appointment slots for a service on the shortlist for a referral using [[HYPERLINK_A015]] You can retrieve the patient letter appropriate to the referral using [[HYPERLINK_A019]] You can retrieve reference data used in viewing a referral using [[HYPERLINK_A004]] ## Sandbox test scenarios You can test the following scenarios in our sandbox environment | Scenario | Request | | ------------------------------------------------------------------------ | ----------------------- | | Unbooked `ReferralRequest` | `ubrn`=`000000070000` | | `ReferralRequest` booked to directly-bookable service | `ubrn`=`000000070001` | | `ReferralRequest` booked to indirectly-bookable service | `ubrn`=`000000070002` | | `ReferralRequest` deferred to service provider for booking | `ubrn`=`000000070003` | | `ReferralRequest` that was converted from an Advice and Guidance Request | `ubrn`=`000000070004` | | `ReferralRequest` with related `ReferralRequest` | `ubrn`=`000000070005` | | `ReferralRequest` with additional requirements listed | `ubrn`=`000000070011` | summary: A005 - Retrieve referral request operationId: a005-retrieve-referral-request parameters: - $ref: 'components/schemas/path/Ubrn.yaml' - $ref: 'components/schemas/headers/request/BearerAuthorization.yaml' - $ref: 'components/schemas/headers/request/OdsCodeOnlyUserRestricted.yaml' - $ref: 'components/schemas/headers/request/BusinessFunctionOnlyUserRestricted.yaml' - $ref: 'components/schemas/headers/request/OnBehalfOfUserIDOnlyUserRestricted.yaml' - $ref: 'components/schemas/headers/request/CorrelationID.yaml' responses: '200': $ref: 'components/schemas/responses/retrieveReferralRequest/200Response.yaml' '400': $ref: 'components/schemas/responses/BadRequest.yaml' '401': $ref: 'components/schemas/responses/Unauthorized.yaml' '403': $ref: 'components/schemas/responses/Forbidden.yaml' '404': $ref: 'components/schemas/responses/NotFound.yaml' '406': $ref: 'components/schemas/responses/NotAcceptable.yaml' '422': $ref: 'components/schemas/responses/retrieveReferralRequest/422Response.yaml' '429': $ref: 'components/schemas/responses/TooManyRequests.yaml' '500': $ref: 'components/schemas/responses/InternalServerError.yaml' /STU3/ReferralRequest/{ubrn}/_history/{version}: get: security: - bearerAuth: [ ] description: | ## Overview Use this endpoint to retrieve a specific version of `ReferralRequest`. ## Supported security patterns - Application-restricted access - Healthcare worker, user-restricted access ## Pre-requisites The pre-requisites for this endpoint are the same as for endpoint [[HYPERLINK_A005]]. Note: e-RS only supports the retrieval of the most recent version of `ReferralRequest`. You cannot retrieve earlier versions. ## Use case See [[HYPERLINK_A005]]. ## Related endpoints See [[HYPERLINK_A005]]. ## Sandbox test scenarios You can test the following scenarios in our sandbox environment | Scenario | Request | | ------------------------------------------------------------------------ | ------------------------------------- | | Unbooked `ReferralRequest` | `ubrn`=`000000070000`, `version`=`5` | | `ReferralRequest` booked to directly-bookable service | `ubrn`=`000000070001`, `version`=`5` | | `ReferralRequest` booked to indirectly-bookable service | `ubrn`=`000000070002`, `version`=`5` | | `ReferralRequest` deferred to service provider for booking | `ubrn`=`000000070003`, `version`=`5` | | `ReferralRequest` that was converted from an Advice and Guidance Request | `ubrn`=`000000070004`, `version`=`5` | | `ReferralRequest` with related `ReferralRequest` | `ubrn`=`000000070005`, `version`=`5` | | `ReferralRequest` with additional requirements listed | `ubrn`=`000000070011`, `version`=`5` | summary: A005 - Retrieve referral request (versioned) operationId: a005-retrieve-referral-request-versioned parameters: - $ref: 'components/schemas/path/Ubrn.yaml' - $ref: 'components/schemas/path/Version.yaml' - $ref: 'components/schemas/headers/request/BearerAuthorization.yaml' - $ref: 'components/schemas/headers/request/OdsCodeOnlyUserRestricted.yaml' - $ref: 'components/schemas/headers/request/BusinessFunctionOnlyUserRestricted.yaml' - $ref: 'components/schemas/headers/request/OnBehalfOfUserIDOnlyUserRestricted.yaml' - $ref: 'components/schemas/headers/request/CorrelationID.yaml' responses: '200': $ref: 'components/schemas/responses/retrieveReferralRequest/200Response.yaml' '400': $ref: 'components/schemas/responses/BadRequest.yaml' '401': $ref: 'components/schemas/responses/Unauthorized.yaml' '403': $ref: 'components/schemas/responses/Forbidden.yaml' '404': $ref: 'components/schemas/responses/NotFoundVersioned.yaml' '406': $ref: 'components/schemas/responses/NotAcceptable.yaml' '422': $ref: 'components/schemas/responses/retrieveReferralRequest/422Response.yaml' '429': $ref: 'components/schemas/responses/TooManyRequests.yaml' '500': $ref: 'components/schemas/responses/InternalServerError.yaml' /STU3/ReferralRequest/{ubrn}/$ers.maintainReferralLetter: post: security: - bearerAuth: [] description: | ## Overview Use this endpoint to manage the set of 'referral letter' attachments associated with an existing referral, including adding or removing attachments from a referral. ## Supported security patterns - Healthcare worker, user-restricted access ## Pre-requisites In order to use this endpoint you must be an authenticated e-RS user and use one of the following e-RS roles: - `REFERRING_CLINICIAN` - `REFERRING_CLINICIAN_ADMIN` All new files to be associated with a referral must be uploaded first using [[HYPERLINK_A020]] and then linked to the referral using this endpoint. ## Important information about using this endpoint This endpoint can be used to associate attachments to a referral that has no existing referral letter attachments. In this case you must upload the file first using [[HYPERLINK_A020]] and then associate it to the referral using this endpoint. You can also use this endpoint to modify the *set* of referral letter attachments already associated with a referral. In this case, you must post all referral letter attachments you wish to be (finally) associated to the referral, including any that were already associated. In other words, this endpoint replaces the set of referral letter attachments previously associated - with those specified in your latest request. As such, it is imperative that this call references all the attachments the user wishes to keep, every time it is called. Below are three example scenarios which clarify the behaviour of the endpoint when referral attachments are already present on the referral: 1. Let us consider a referral that has two referral letter attachments associated (say "A.pdf" and "B.pdf"). If you wish to add an additional attachment (say "C.pdf"), you must upload the additional attachment "C.pdf" using [[HYPERLINK_A020]], and then associate attachments "A.pdf", "B.pdf" and "C.pdf" via this endpoint in a single request. That is, all three attachments "A.pdf", "B.pdf" and "C.pdf" must be included in the request to A012 - Maintain referral letter. 2. Let us consider a different referral that has two referral letter attachments (say "D.jpg" and "E.jpg") already associated, and you wish to remove one of them. Lets consider that you wish to remove "D.jpg". To do this, you would call A012 - Maintain referral letter specifying only "E.jpg" in your request. By omitting "D.jpg" from your request, e-RS will dis-associate attachment "D.jpg" from the referral and only attachment "E.jpg" will remain associated. 3. Let us now consider a referral that has four referral letter attachments associated (say "L.doc", "M.doc", "N.doc" and "O.doc"), and you wish to add some more files (say "P.doc" and "Q.doc") and remove some files (say "N.doc" and "O.doc"). To do this you must upload the additional attachment(s) ("N.doc" and "O.doc") using [[HYPERLINK_A020]]. Following that successful upload, you must then associate only all referral letter attachments the user wishes to keep (namely "L.doc", "M.doc", "P.doc" and "Q.doc") in a single request to A012 - Maintain referral letter. Attachments not included in the request (namely "N.doc" and "O.doc") will be dis-associated from the referral as a result. As a developer or software supplier, please ensure your users are made aware or protected from this behaviour. For example, when a referring user wants to update the attachments on a referral, the user should be presented with the currently associated attachments so they can add and/or remove attachments as required. Note: It is not permissible to remove *all* referral letter attachments leaving zero attachments associated. There must be at least one referral letter attachment associated. ## Use case As an authenticated user I need to be able to manage referral letter attachments associated with a referral So I can ensure the service provider has enough information to review/process the referral. ## Related endpoints Documents must be uploaded into the e-RS document store using [[HYPERLINK_A020]] before they can be associated with a referral. You can check to see what referral letter information has been added to a referral by using [[HYPERLINK_A005]], [[HYPERLINK_A007]], and [[HYPERLINK_A006]] endpoints where necessary. ## Sandbox test scenarios You can test the following scenarios in our sandbox environment: | Scenario | Request | | ------------------------------------------------------ | ------------------------------------------------------- | | Add clinical information for first time (single file) | `ubrn`=`000000070000`, `body` as defined in example 1 | | Add clinical information for first time (two files) | `ubrn`=`000000070001`, `body` as defined in example 2 | | Update clinical information | `ubrn`=`000000070001`, `body` as defined in example 3 | summary: A012 - Maintain referral letter operationId: a012-maintain-referral-letter parameters: - $ref: 'components/schemas/headers/request/ContentTypeFhirJson.yaml' - $ref: 'components/schemas/headers/request/BearerAuthorization.yaml' - $ref: 'components/schemas/headers/request/OdsCode.yaml' - $ref: 'components/schemas/headers/request/BusinessFunction.yaml' - $ref: 'components/schemas/headers/request/CorrelationID.yaml' - $ref: 'components/schemas/headers/request/IfMatch.yaml' - $ref: 'components/schemas/path/Ubrn.yaml' requestBody: required: true content: application/fhir+json: schema: $ref: 'components/schemas/eRS-MaintainReferralLetter-Parameters.yaml' examples: single-file: summary: 1 - Add clinical information (single file) value: $ref: 'components/examples/maintainReferralLetter/requests/SingleDocumentReference.json' two-files: summary: 2 - Add clinical information (two files) value: $ref: 'components/examples/maintainReferralLetter/requests/MultipleDocumentReferences.json' update-files: summary: 3 - Update clinical information (removing one file from example above) value: $ref: 'components/examples/maintainReferralLetter/requests/UpdateClinicalInfo.json' responses: '200': $ref: 'components/schemas/responses/maintainReferralLetter/200Response.yaml' '400': $ref: 'components/schemas/responses/BadRequest.yaml' '401': $ref: 'components/schemas/responses/Unauthorized.yaml' '403': $ref: 'components/schemas/responses/Forbidden.yaml' '404': $ref: 'components/schemas/responses/NotFound.yaml' '406': $ref: 'components/schemas/responses/NotAcceptable.yaml' '409': $ref: 'components/schemas/responses/Conflict.yaml' '412': $ref: 'components/schemas/responses/PreconditionFailed.yaml' '415': $ref: 'components/schemas/responses/UnsupportedMediaType.yaml' '422': $ref: 'components/schemas/responses/maintainReferralLetter/422Response.yaml' '423': $ref: 'components/schemas/responses/Locked.yaml' '429': $ref: 'components/schemas/responses/TooManyRequests.yaml' '500': $ref: 'components/schemas/responses/InternalServerError.yaml' /STU3/Appointment: post: security: - bearerAuth: [] description: | ## Overview Use this endpoint to book an appointment to a service if an appointment slot is available or defer booking if no appointment slot is available. ## Supported security patterns - Healthcare worker, user-restricted access ## Pre-requisites In order to use this endpoint you must be an authenticated e-RS user and use one of the following e-RS roles: - `REFERRING_CLINICIAN` - `REFERRING_CLINICIAN_ADMIN` You need to retrieve available appointment slots for a service using [[HYPERLINK_A015]]. You need to use the `Unique Booking Reference Number` (UBRN) of a referral request in order to use this endpoint. ## Important note when deferring to provider You should only defer booking to a directly bookable service in the following circumstances: - when the service has no available slots *or* - when trying to book an appointment into a service, the slot advertised is no longer available *or* - when trying to book an appointment into a service, no response is received within the message timeout period (currently 2 minutes) ## Use case As an authenticated user I need to either: - book an appointment to an available appointment slot for a service *or* - defer booking responsibility for the service to the service provider if a booking is not possible So I can progress my patient's care at that service. ## Related endpoints You can generate a letter for the patient, summarising the current state of their referral and any steps the patient may need to follow using [[HYPERLINK_A019]]. You can calculate the date when the patient will need to be contacted (by the service) using reference data from [[HYPERLINK_A004]]. summary: A016 - Book or defer appointment operationId: a016-book-or-defer-appointment parameters: - $ref: 'components/schemas/headers/request/ContentTypeFhirJson.yaml' - $ref: 'components/schemas/headers/request/BearerAuthorization.yaml' - $ref: 'components/schemas/headers/request/OdsCode.yaml' - $ref: 'components/schemas/headers/request/BusinessFunction.yaml' - $ref: 'components/schemas/headers/request/CorrelationID.yaml' requestBody: required: true content: application/fhir+json: schema: $ref: 'components/schemas/eRS-Appointment.yaml' examples: minimal-booking: summary: Minimum booking value: $ref: 'components/examples/bookOrDeferAppointment/requests/MinimalBooking.json' minimal-deferral: summary: Minimum deferral value: $ref: 'components/examples/bookOrDeferAppointment/requests/MinimalDeferral.json' booking-with-named-clinician: summary: Booking with named clinician value: $ref: 'components/examples/bookOrDeferAppointment/requests/BookingWithNamedClinician.json' deferral-with-slot-reference: summary: Deferral with slot reference value: $ref: 'components/examples/bookOrDeferAppointment/requests/DeferralWithSlotReference.json' deferral-booking-attempt-problem: summary: Deferral booking attempt problem value: $ref: 'components/examples/bookOrDeferAppointment/requests/DeferralBookingAttemptProblem.json' responses: '201': $ref: 'components/schemas/responses/bookOrDeferAppointment/201Response.yaml' '401': $ref: 'components/schemas/responses/Unauthorized.yaml' '403': $ref: 'components/schemas/responses/Forbidden.yaml' '406': $ref: 'components/schemas/responses/NotAcceptable.yaml' '409': $ref: 'components/schemas/responses/Conflict.yaml' '415': $ref: 'components/schemas/responses/UnsupportedMediaType.yaml' '422': $ref: 'components/schemas/responses/bookOrDeferAppointment/422Response.yaml' '423': $ref: 'components/schemas/responses/Locked.yaml' '429': $ref: 'components/schemas/responses/TooManyRequests.yaml' '500': $ref: 'components/schemas/responses/InternalServerError.yaml' '502': $ref: 'components/schemas/responses/bookOrDeferAppointment/502Response.yaml' '504': $ref: 'components/schemas/responses/bookOrDeferAppointment/504Response.yaml' /STU3/ReferralRequest/{ubrn}/$ers.generateCRI: post: security: - bearerAuth: [] description: | ## Overview Use this endpoint to generate a PDF file that summarises clinical information for a referral. ## Supported security patterns - Application-restricted access - Healthcare worker, user-restricted access ## Pre-requisites ### Application-restricted access In order to use this endpoint you must be an authenticated e-RS calling application. ### Healthcare worker, user-restricted access In order to use this endpoint you must be an authenticated e-RS user and use one of the following e-RS roles: - `REFERRING_CLINICIAN` - `REFERRING_CLINICIAN_ADMIN` - `SERVICE_PROVIDER_CLINICIAN` - `SERVICE_PROVIDER_CLINICIAN_ADMIN` You need to use the `Unique Booking Reference Number` (UBRN) of a referral request in order to use this endpoint. ## Important note A referral pathway in e-RS can be made up of more than one UBRN. For example, a referral is booked and seen in a general knee clinical assessment service (UBRN #1), and the service decides to onward refer to a more specialist knee miniscus service (UBRN #2). This would result in two UBRNs for the referral pathway in this example (but there could be more related UBRNs if onward referred multiple times). As such, it is important that all clinical information is obtained from across all the related UBRNs referenced in [[HYPERLINK_A005]]. You can do this using the following endpoints: - A007 - Retrieve Clinical Information - [[HYPERLINK_A006]] Note: It is possible that the initial UBRN may be the only one in the referral pathway to have clinical information and/or attachments associated. ## Use case As an authenticated user or application I need to retrieve a clinical information summary (in PDF format) associated with the referral So that I can assess its content and decide what further action may be needed. ## Related endpoints You can retrieve clinical attachments that are associated with a referral using [[HYPERLINK_A006]]. summary: A007 - Retrieve clinical information operationId: a007-retrieve-clinical-information parameters: - $ref: 'components/schemas/headers/request/BearerAuthorization.yaml' - $ref: 'components/schemas/headers/request/OdsCodeOnlyUserRestricted.yaml' - $ref: 'components/schemas/headers/request/BusinessFunctionOnlyUserRestricted.yaml' - $ref: 'components/schemas/headers/request/OnBehalfOfUserIDOnlyUserRestricted.yaml' - $ref: 'components/schemas/headers/request/CorrelationID.yaml' - $ref: 'components/schemas/path/Ubrn.yaml' responses: '200': $ref: 'components/schemas/responses/retrieveClinicalInformation/200Response.yaml' '401': $ref: 'components/schemas/responses/Unauthorized.yaml' '403': $ref: 'components/schemas/responses/Forbidden.yaml' '404': $ref: 'components/schemas/responses/NotFound.yaml' '406': $ref: 'components/schemas/responses/NotAcceptable.yaml' '422': $ref: 'components/schemas/responses/retrieveClinicalInformation/422Response.yaml' '429': $ref: 'components/schemas/responses/TooManyRequests.yaml' '500': $ref: 'components/schemas/responses/InternalServerError.yaml' /STU3/ReferralRequest/$ers.fetchworklist: post: security: - bearerAuth: [] description: | ## Overview Use this endpoint to retrieve available worklists of referral requests. Service Providers can use [[HYPERLINK_A023]] to retrieve available worklists of advice and guidance requests. There are currently no worklists of advice and guidance requests for Referrers. Worklists provide lists of referral/advice requests that meet certain criteria, typically where a user needs to be aware of something important, or to undertake an action, in order to avoid delays to patient care. ## Supported security patterns - Healthcare worker, user-restricted access ## Referring Organisations Referring organisations can currently access the following referral related worklists: - The 'Letters Outstanding' worklist contains referrals which require a referral letter to be added. - The 'Rejected / Triage Response' worklist contains referrals which have had an appointment rejected or have been returned to the referrer with a response as part of a triage outcome. - The 'Assessment Returned / Cancelled / DNA' worklist contains referrals which have a clinical assessment outcome of 'advise referrer' recorded, or referrals which have been cancelled by someone outside the initial referring organisation, or referrals where the patient did not attend the appointment booking and the provider has returned the referral back to the referrer for action. - The 'Awaiting Booking' worklist contains referrals for which an appointment booking could be made but they do not currently have an appointment booking. This includes referrals that are currently awaiting triage, deferred to provider, or have had their appointment booking cancelled. Filters can be used in requests for service provider organisation worklists, however, filters cannot be used in requests for referring organisation worklists. ### Pre-requisites In order to use this endpoint and retrieve the referring organisation worklists, you must be an authenticated e-RS user and use one of the following e-RS roles: - `REFERRING_CLINICIAN` - `REFERRING_CLINICIAN_ADMIN` - `REFERRING_ADMIN` ### Use case As an authenticated user I need to retrieve a referral worklist for my referring organisation So that I can determine which referrals I need to take further action on ### Related endpoints To retrieve pertinent details relating to a referral: - Use [[HYPERLINK_A005]] to retrieve the details of the referral - Use [[HYPERLINK_A006]] to retrieve the clinical attachments for a referral - Use [[HYPERLINK_A007]] to retrieve the clinical information summary PDF for a referral You can use [[HYPERLINK_A029]] to determine what endpoints an authenticated user is permitted to use for a referral in it's current state. ## Service Providing Organisations Service provider organisations can currently access the following referral related worklists: - The 'Referrals for Review' worklist contains booked and RAS (triage) referrals that require review by the service provider organisation - 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. There are currently no referral related worklists available for referring organisations. ## Supported security patterns - Healthcare worker, user-restricted access ## Pre-requisites In order to use this endpoint you must be an authenticated e-RS user and use one of the following e-RS roles: - `SERVICE_PROVIDER_CLINICIAN` - `SERVICE_PROVIDER_ADMIN` - `SERVICE_PROVIDER_CLINICIAN_ADMIN` If a worklist response exceeds 10MB, a successful response will not be returned. This is due to the size limitation on the APIM platform. ### Use case As an authenticated user I need to retrieve a referral worklist for my service providing organisation So that I can determine which referrals I need to take further action on ### Related endpoints To retrieve pertinent details relating to a referral: - Use [[HYPERLINK_A005]] to retrieve the details of the referral - Use [[HYPERLINK_A006]] to retrieve the clinical attachments for a referral - Use [[HYPERLINK_A007]] to retrieve the clinical information summary PDF for a referral For service providing organisations reviewing booked referrals on the 'Referrals for review' worklist: - Use [[HYPERLINK_A013]] to accept a referral into a bookable service - Use [[HYPERLINK_A014]] to reject a referral from a bookable service - Use [[HYPERLINK_A022]] to request an admin team to rebook or redirect a referral For service providing organisations reviewing triage (RAS) referrals on the 'Referrals for review' worklist: - Use [[HYPERLINK_A028]] to record the triage outcome based on the available clinical information and attachments For service providing organisations reviewing referrals that have been deferred to provider on the 'Appointment slot issues' worklist: - Use [[HYPERLINK_A028]] to record the triage outcome based on the available clinical information and attachments summary: A008 - Retrieve referral worklist operationId: a008-retrieve-worklist parameters: - $ref: 'components/schemas/headers/request/ContentTypeFhirJson.yaml' - $ref: 'components/schemas/headers/request/BearerAuthorization.yaml' - $ref: 'components/schemas/headers/request/OdsCode.yaml' - $ref: 'components/schemas/headers/request/BusinessFunction.yaml' - $ref: 'components/schemas/headers/request/OnBehalfOfUserID.yaml' - $ref: 'components/schemas/headers/request/CorrelationID.yaml' requestBody: required: true content: application/fhir+json: schema: $ref: 'components/schemas/eRS-FetchWorklist-Parameters.yaml' examples: referrals-for-review: summary: Referrals for review value: $ref: 'components/examples/retrieveWorklist/requests/MinimalReferralsForReview.json' appointment-slot-issues: summary: Appointment slot issues value: $ref: 'components/examples/retrieveWorklist/requests/MinimalAppointmentSlotIssues.json' filtered-by-specialty: summary: Filter by specialty value: $ref: 'components/examples/retrieveWorklist/requests/FilteringBySpecialty.json' filtered-by-clinician: summary: Filter by clinician value: $ref: 'components/examples/retrieveWorklist/requests/FilteringByClinician.json' rejected-triage-responses: summary: Rejected Triage Responses value: $ref: 'components/examples/retrieveWorklist/requests/MinimalRejectedTriageResponse.json' assessment-returned-cancelled-dna: summary: Assessment Returned Cancelled DNA value: $ref: 'components/examples/retrieveWorklist/requests/MinimalAssessmentReturnedCancelledDna.json' awaiting-booking: summary: Awaiting Booking value: $ref: 'components/examples/retrieveWorklist/requests/MinimalAwaitingBooking.json' letters-outstanding: summary: Letters Outstanding value: $ref: 'components/examples/retrieveWorklist/requests/MinimalLettersOutstanding.json' responses: '200': $ref: 'components/schemas/responses/retrieveWorklist/200Response.yaml' '400': $ref: 'components/schemas/responses/BadRequest.yaml' '401': $ref: 'components/schemas/responses/Unauthorized.yaml' '403': $ref: 'components/schemas/responses/Forbidden.yaml' '406': $ref: 'components/schemas/responses/NotAcceptable.yaml' '415': $ref: 'components/schemas/responses/UnsupportedMediaType.yaml' '422': $ref: 'components/schemas/responses/retrieveWorklist/422Response.yaml' '429': $ref: 'components/schemas/responses/TooManyRequests.yaml' '500': $ref: 'components/schemas/responses/InternalServerError.yaml' /STU3/CommunicationRequest/$ers.fetchworklist: post: security: - bearerAuth: [] description: | ## Overview Use this endpoint to retrieve available worklists of advice and guidance requests. Use [[HYPERLINK_A008]] to retrieve available worklists of referral requests. Worklists provide lists of referral/advice requests that meet certain criteria, typically where a user needs to be aware of something important, or to undertake an action, in order to avoid delays to patient care. Service provider organisations can retrieve the contents of their 'Advice and guidance requests' worklist using this endpoint. This worklist contains advice and guidance requests the provider has received and which need actioning. There are currently no advice and guidance related worklists available for referring organisations. ## Supported security patterns - Healthcare worker, user-restricted access ## Pre-requisites In order to use this endpoint you must be an authenticated e-RS user and use one of the following e-RS roles: - `SERVICE_PROVIDER_CLINICIAN` - `SERVICE_PROVIDER_ADMIN` - `SERVICE_PROVIDER_CLINICIAN_ADMIN` If a worklist response exceeds 10MB, a successful response will not be returned. This is due to the size limitation on the APIM platform. ## Use case As an authenticated user I need to retrieve a worklist of advice and guidance requests So I can determine which ones I need to take further action on. ## Related endpoints Having used this endpoint to retrieve the 'Advice and Guidance Requests' worklist, entries from it can be used as follows: - Use [[HYPERLINK_A024]] to retrieve contextual summary details of the advice and guidance request - Use [[HYPERLINK_A025]] to retrieve the conversation within the advice and guidance request, including references to attachments - Use [[HYPERLINK_A006]] to retrieve clinical attachments for an advice and guidance request - Use [[HYPERLINK_A026]] to respond to the referrer supplying advice or requesting further information - Use [[HYPERLINK_A027]] to convert the advice and guidance request into a referral. This is only possible if the referrer has authorised the provider to do so summary: A023 - Retrieve advice and guidance requests worklist operationId: a023-retrieve-a&g-worklist parameters: - $ref: 'components/schemas/headers/request/ContentTypeFhirJson.yaml' - $ref: 'components/schemas/headers/request/BearerAuthorization.yaml' - $ref: 'components/schemas/headers/request/OdsCode.yaml' - $ref: 'components/schemas/headers/request/BusinessFunction.yaml' - $ref: 'components/schemas/headers/request/OnBehalfOfUserID.yaml' - $ref: 'components/schemas/headers/request/CorrelationID.yaml' requestBody: required: true content: application/fhir+json: schema: $ref: 'components/schemas/eRS-FetchWorklist-Parameters.yaml' examples: a&g-requests: summary: Advice and guidance requests value: $ref: 'components/examples/retrieveAdviceAndGuidanceWorklist/requests/MinimalAdviceAndGuidanceRequests.json' responses: '200': $ref: 'components/schemas/responses/retrieveAdviceAndGuidanceWorklist/200Response.yaml' '400': $ref: 'components/schemas/responses/BadRequest.yaml' '401': $ref: 'components/schemas/responses/Unauthorized.yaml' '403': $ref: 'components/schemas/responses/Forbidden.yaml' '406': $ref: 'components/schemas/responses/NotAcceptable.yaml' '415': $ref: 'components/schemas/responses/UnsupportedMediaType.yaml' '422': $ref: 'components/schemas/responses/retrieveAdviceAndGuidanceWorklist/422Response.yaml' '429': $ref: 'components/schemas/responses/TooManyRequests.yaml' '500': $ref: 'components/schemas/responses/InternalServerError.yaml' /STU3/CommunicationRequest/{ubrn}: get: security: - bearerAuth: [ ] description: | ## Overview Use this endpoint to retrieve the summary of an advice and guidance request. This endpoint provides important contextual information about the advice and guidance request (e.g. the service/specialty to which advice has been requested, etc). This does not include the actual advice and guidance conversation between the referrer and the service provider. The conversation can be retrieved via [[HYPERLINK_A025]]. ## Supported security patterns - Healthcare worker, user-restricted access ## Pre-requisites In order to use this endpoint you must be an authenticated e-RS user and use one of the following e-RS roles: - `REFERRING_CLINICIAN` - `REFERRING_CLINICIAN_ADMIN` - `SERVICE_PROVIDER_CLINICIAN` - `SERVICE_PROVIDER_CLINICIAN_ADMIN` You need to use the `Unique Booking Reference Number` (UBRN) of the advice and guidance request. For service provider users, you may have identified the UBRN via [[HYPERLINK_A023]]. ## Use case As an authenticated user I need to retrieve the summary of an advice and guidance request So I can understand all of the relevant context for the request. ## Important note The summary includes an indicator of whether the referrer has authorised the providing organisation to convert the advice and guidance request into an appointment request. If authorised, [[HYPERLINK_A027]] can be used to convert the advice and guidance request into an appointment request. ## Related endpoints After using this endpoint, use [[HYPERLINK_A025]] to retrieve the Advice and Guidance conversation itself. ## Sandbox test scenarios You can test the following scenarios in our sandbox environment | Scenario | Request | | ------------------------------------------------------------------------ | ----------------------- | | Simple summary `CommunicationRequest` | `ubrn`=`000000070000` | | Attachment file reference present | `ubrn`=`000000070001` | summary: A024 - Retrieve advice and guidance request summary operationId: a024-retrieve-advice-and-guidance parameters: - $ref: 'components/schemas/path/Ubrn.yaml' - $ref: 'components/schemas/headers/request/BearerAuthorization.yaml' - $ref: 'components/schemas/headers/request/OdsCode.yaml' - $ref: 'components/schemas/headers/request/BusinessFunction.yaml' - $ref: 'components/schemas/headers/request/OnBehalfOfUserID.yaml' - $ref: 'components/schemas/headers/request/CorrelationID.yaml' responses: '200': $ref: 'components/schemas/responses/retrieveAdviceAndGuidanceRequest/200Response.yaml' '400': $ref: 'components/schemas/responses/BadRequest.yaml' '401': $ref: 'components/schemas/responses/Unauthorized.yaml' '403': $ref: 'components/schemas/responses/Forbidden.yaml' '404': $ref: 'components/schemas/responses/NotFound.yaml' '406': $ref: 'components/schemas/responses/NotAcceptable.yaml' '422': $ref: 'components/schemas/responses/retrieveAdviceAndGuidanceRequest/422Response.yaml' '429': $ref: 'components/schemas/responses/TooManyRequests.yaml' '500': $ref: 'components/schemas/responses/InternalServerError.yaml' /STU3/CommunicationRequest/{ubrn}/_history/{version}: get: security: - bearerAuth: [ ] description: | ## Overview Use this endpoint to retrieve a specific version of `CommunicationRequest`. ## Supported security patterns - Healthcare worker, user-restricted access ## Pre-requisites The pre-requisites for this endpoint are the same as for endpoint [[HYPERLINK_A024]]. Note: e-RS only supports the retrieval of the most recent version of `CommunicationRequest`. You cannot retrieve earlier versions. ## Use case See [[HYPERLINK_A005]]. ## Related endpoints See [[HYPERLINK_A024]]. ## Sandbox test scenarios You can test the following scenarios in our sandbox environment | Scenario | Request | | ------------------------------------------------------------------------ | ------------------------------------- | | Simple summary `CommunicationRequest` | `ubrn`=`000000070000`, `version`=`5` | | Attachment file reference present | `ubrn`=`000000070001`, `version`=`5` | summary: A024 - Retrieve advice and guidance request summary (versioned) operationId: a024-retrieve-advice-and-guidance-versioned parameters: - $ref: 'components/schemas/path/Ubrn.yaml' - $ref: 'components/schemas/path/Version.yaml' - $ref: 'components/schemas/headers/request/BearerAuthorization.yaml' - $ref: 'components/schemas/headers/request/OdsCode.yaml' - $ref: 'components/schemas/headers/request/BusinessFunction.yaml' - $ref: 'components/schemas/headers/request/OnBehalfOfUserID.yaml' - $ref: 'components/schemas/headers/request/CorrelationID.yaml' responses: '200': $ref: 'components/schemas/responses/retrieveAdviceAndGuidanceRequest/200Response.yaml' '400': $ref: 'components/schemas/responses/BadRequest.yaml' '401': $ref: 'components/schemas/responses/Unauthorized.yaml' '403': $ref: 'components/schemas/responses/Forbidden.yaml' '404': $ref: 'components/schemas/responses/NotFoundVersioned.yaml' '406': $ref: 'components/schemas/responses/NotAcceptable.yaml' '422': $ref: 'components/schemas/responses/retrieveAdviceAndGuidanceRequest/422Response.yaml' '429': $ref: 'components/schemas/responses/TooManyRequests.yaml' '500': $ref: 'components/schemas/responses/InternalServerError.yaml' /STU3/Communication: get: security: - bearerAuth: [ ] description: | ## Overview Use this endpoint to retrieve the advice and guidance conversation between the referring organisation and service providing organisation. A 'conversation' takes the form of the messages between a referrer (seeking advice) and a provider or specialist. Messages can include attachments. ## Supported security patterns - Healthcare worker, user-restricted access ## Pre-requisites In order to use this endpoint you must be an authenticated e-RS user and use one of the following e-RS roles: - `REFERRING_CLINICIAN` - `REFERRING_CLINICIAN_ADMIN` - `SERVICE_PROVIDER_CLINICIAN` - `SERVICE_PROVIDER_CLINICIAN_ADMIN` You need to use the `Unique Booking Reference Number` (UBRN) of the advice and guidance request. For service provider users, you may have identified the UBRN via [[HYPERLINK_A023]]. You need to use [[HYPERLINK_A024]] to retrieve the summary of an advice and guidance request. This will importantly include the latest version of the request which must be used. ## Use case As an authenticated user I need to retrieve the conversation that is present on an advice and guidance request So that I can review the conversation and potentially contribute further to it. ## Important note The conversation returned includes links to any attachments associated with the conversation. ## Related endpoints After using this endpoint: - Use [[HYPERLINK_A006]] to retrieve any attachments associated with the advice and guidance request. - (For service provider users) Use [[HYPERLINK_A026]] to respond to the referrer supplying advice or requesting further information. - (For service provider users) Use [[HYPERLINK_A027]] to convert the advice and guidance request into a referral. This is only possible if the referrer has authorised the provider to do so. ## Sandbox test scenarios You can test the following scenarios in our sandbox environment | Scenario | Request | | -------------------------------------------------------------- | --------------------------------------------------------- | | Single message from referrer | `based-on`=`CommunicationRequest/000000070000/_history/1` | | One message each way | `based-on`=`CommunicationRequest/000000070000/_history/2` | | Attachment present in each direction | `based-on`=`CommunicationRequest/000000070001/_history/6` | | Multi-way conversation | `based-on`=`CommunicationRequest/000000070002/_history/1` | | Attachment uploaded from RCS before A&G creation | `based-on`=`CommunicationRequest/000000070003/_history/7` | summary: A025 - Retrieve advice and guidance conversation operationId: a025-retrieve-advice-and-guidance-conversation parameters: - $ref: 'components/schemas/queryParameters/BasedOn.yaml' - $ref: 'components/schemas/queryParameters/Include-Communication.yaml' - $ref: 'components/schemas/headers/request/BearerAuthorization.yaml' - $ref: 'components/schemas/headers/request/OdsCode.yaml' - $ref: 'components/schemas/headers/request/BusinessFunction.yaml' - $ref: 'components/schemas/headers/request/OnBehalfOfUserID.yaml' - $ref: 'components/schemas/headers/request/CorrelationID.yaml' responses: '200': $ref: 'components/schemas/responses/retrieveAdviceAndGuidanceConversation/200Response.yaml' '400': $ref: 'components/schemas/responses/retrieveAdviceAndGuidanceConversation/400Response.yaml' '401': $ref: 'components/schemas/responses/Unauthorized.yaml' '403': $ref: 'components/schemas/responses/Forbidden.yaml' '404': $ref: 'components/schemas/responses/NotFoundVersioned.yaml' '406': $ref: 'components/schemas/responses/NotAcceptable.yaml' '429': $ref: 'components/schemas/responses/TooManyRequests.yaml' '500': $ref: 'components/schemas/responses/InternalServerError.yaml' /STU3/CommunicationRequest/{ubrn}/$ers.sendCommunicationToRequester: post: security: - bearerAuth: [] description: | ## Overview Use this endpoint, as a service provider, to respond to an advice and guidance request your service provider organisation has received. You can either provide guidance back to the referrer or request further information from the referrer. This will return the advice and guidance request back to the referrer for action. Note: If you want to convert an advice and guidance request into a referral, and provide a final guidance response back to the referrer at the same time, please use [[HYPERLINK_A027]] instead. This option is only permissible if the referrer has authorised the provider to convert the advice and guidance request into a referral. ## Supported security patterns - Healthcare worker, user-restricted access ## Pre-requisites In order to use this endpoint you must be an authenticated e-RS user and use one of the following e-RS roles: - `SERVICE_PROVIDER_CLINICIAN` - `SERVICE_PROVIDER_CLINICIAN_ADMIN` You need to use [[HYPERLINK_A024]] to retrieve the summary of an advice and guidance request. You need to use [[HYPERLINK_A025]] to retrieve the conversation within an advice and guidance request. If you want to include attachments with the response, you need to use [[HYPERLINK_A020]] so they are ready to be associated with the response. ## Use case As an authenticated user I need to return an advice and guidance request back to the referrer with some guidance So that I can progress the conversation regarding the patient's care. ## Related endpoints You can use [[HYPERLINK_A007]] to generate a PDF file that summarises the advice and guidance request and associated conversation. You can use [[HYPERLINK_A024]] to retrieve the latest summary of the advice and guidance request. You can use [[HYPERLINK_A025]] to retrieve the latest conversation within the advice and guidance request. summary: A026 - Send advice and guidance response operationId: a026-send-a&g-response parameters: - $ref: 'components/schemas/headers/request/ContentTypeFhirJson.yaml' - $ref: 'components/schemas/path/Ubrn.yaml' - $ref: 'components/schemas/headers/request/BearerAuthorization.yaml' - $ref: 'components/schemas/headers/request/OdsCode.yaml' - $ref: 'components/schemas/headers/request/BusinessFunction.yaml' - $ref: 'components/schemas/headers/request/OnBehalfOfUserID.yaml' - $ref: 'components/schemas/headers/request/CorrelationID.yaml' - $ref: 'components/schemas/headers/request/IfMatch.yaml' requestBody: required: true content: application/fhir+json: schema: $ref: 'components/schemas/eRS-SendCommunicationToRequester-Request-Parameters.yaml' examples: require-further-information: summary: Require further information value: $ref: 'components/examples/sendAdviceAndGuidanceResponse/requests/RequireFurtherInformation.json' return-to-referrer-with-advice: summary: Return to referrer with advice value: $ref: 'components/examples/sendAdviceAndGuidanceResponse/requests/ReturnToReferrerWithAdvice.json' attachment-included: summary: Attachment included value: $ref: 'components/examples/sendAdviceAndGuidanceResponse/requests/AttachmentIncluded.json' responses: '200': $ref: 'components/schemas/responses/sendAdviceAndGuidanceResponse/200Response.yaml' '400': $ref: 'components/schemas/responses/BadRequest.yaml' '401': $ref: 'components/schemas/responses/Unauthorized.yaml' '403': $ref: 'components/schemas/responses/Forbidden.yaml' '404': $ref: 'components/schemas/responses/NotFound.yaml' '406': $ref: 'components/schemas/responses/NotAcceptable.yaml' '409': $ref: 'components/schemas/responses/Conflict.yaml' '415': $ref: 'components/schemas/responses/UnsupportedMediaType.yaml' '422': $ref: 'components/schemas/responses/sendAdviceAndGuidanceResponse/422Response.yaml' '423': $ref: 'components/schemas/responses/Locked.yaml' '429': $ref: 'components/schemas/responses/TooManyRequests.yaml' '500': $ref: 'components/schemas/responses/InternalServerError.yaml' /STU3/ReferralRequest/$ers.createFromCommunicationRequestActionLater: post: security: - bearerAuth: [] description: | ## Overview Use this endpoint, as a service provider, to: - convert the advice and guidance request you have received into a referral, AND - create a task for the service provider admin team to select/shortlist appropriate services for the patient, AND - provide final guidance response details back to the referrer Note: This endpoint is only allowed to be used if the referrer has authorised the provider to convert the advice and guidance request into a referral. ## Supported security patterns - Healthcare worker, user-restricted access ## Pre-requisites In order to use this endpoint you must be an authenticated e-RS user and use one of the following e-RS roles: - `SERVICE_PROVIDER_CLINICIAN` - `SERVICE_PROVIDER_CLINICIAN_ADMIN` You need to use [[HYPERLINK_A024]] to retrieve the summary of an advice and guidance request. This will include whether or not the referrer has authorised the provider to be able to convert an advice and guidance request into a referral, and thus dictate whether this endpoint can be used. You need to use [[HYPERLINK_A025]] to retrieve the conversation within an advice and guidance request. If you want to include attachments with the admin task and/or the response to the referrer, you need to use [[HYPERLINK_A020]] so they are ready to be associated when this endpoint is called. ## Use case As an authenticated user I need to convert an inbound advice and guidance request into a referral and task my admin team to shortlist appropriate services for the patient So that I can progress the patient's care along the most appropriate referral pathway. ## Important notes When this endpoint is successfully used, an entry will be added to the service providers Appointments For Booking worklist for the admin team to action the task. The provider admin team will currently only be able to progress the referral via the e-RS Professional Application user interface (e.g. shortlisting appropriate services for the patient). ## Related endpoints You can use [[HYPERLINK_A005]] to retrieve the details of the referral. You can use [[HYPERLINK_A024]] to retrieve the latest summary of the advice and guidance request. You can use [[HYPERLINK_A025]] to retrieve the latest conversation within the advice and guidance request. You can use [[HYPERLINK_A006]] to retrieve the clinical attachments for a referral/advice request. You can use [[HYPERLINK_A007]] to retrieve the clinical information summary PDF for a referral. summary: A027 - Convert advice and guidance request to referral operationId: a027-convert-a&g-to-referral parameters: - $ref: 'components/schemas/headers/request/ContentTypeFhirJson.yaml' - $ref: 'components/schemas/headers/request/BearerAuthorization.yaml' - $ref: 'components/schemas/headers/request/OdsCode.yaml' - $ref: 'components/schemas/headers/request/BusinessFunction.yaml' - $ref: 'components/schemas/headers/request/OnBehalfOfUserID.yaml' - $ref: 'components/schemas/headers/request/CorrelationID.yaml' requestBody: required: true content: application/fhir+json: schema: $ref: 'components/schemas/eRS-CreateFromCommunicationRequestActionLater-Request-Parameters.yaml' examples: no-attachments: summary: No attachments value: $ref: 'components/examples/convertAdviceAndGuidanceToReferral/requests/NoAttachments.json' with-attachments: summary: With attachments value: $ref: 'components/examples/convertAdviceAndGuidanceToReferral/requests/WithAttachments.json' responses: '201': $ref: 'components/schemas/responses/convertAdviceAndGuidanceToReferral/201Response.yaml' '400': $ref: 'components/schemas/responses/BadRequest.yaml' '401': $ref: 'components/schemas/responses/Unauthorized.yaml' '403': $ref: 'components/schemas/responses/Forbidden.yaml' '404': $ref: 'components/schemas/responses/NotFound.yaml' '406': $ref: 'components/schemas/responses/NotAcceptable.yaml' '409': $ref: 'components/schemas/responses/Conflict.yaml' '415': $ref: 'components/schemas/responses/UnsupportedMediaType.yaml' '422': $ref: 'components/schemas/responses/convertAdviceAndGuidanceToReferral/422Response.yaml' '423': $ref: 'components/schemas/responses/Locked.yaml' '429': $ref: 'components/schemas/responses/TooManyRequests.yaml' '500': $ref: 'components/schemas/responses/InternalServerError.yaml' /STU3/ReferralRequest/{ubrn}/$ers.recordReviewOutcome: post: security: - bearerAuth: [] description: | ## Overview Use this endpoint, as a service provider, to record a triage outcome for the following referrals awaiting review: - referrals sent into a triage service - referrals deferred into a directly bookable service because of appointment slot unavailability ## Supported security patterns - Healthcare worker, user-restricted access ## Pre-requisites In order to use this endpoint you must be an authenticated e-RS user and use one of the following e-RS roles: - `SERVICE_PROVIDER_CLINICIAN` - `SERVICE_PROVIDER_CLINICIAN_ADMIN` You need to use [[HYPERLINK_A008]] to retrieve the contents of the 'Referrals For Review' worklist. [[HYPERLINK_A028]] can only be used for referrals sent into triage services, and not the referrals booked into bookable services. You need to use [[HYPERLINK_A008]] to retrieve the contents of the 'Appointment Slot Issues' worklist. This provides a list of referrals that have been deferred into directly bookable services. - Referrals from this worklist may already have been reviewed or may not have any referral clinical information associated, in which case [[HYPERLINK_A028]] cannot be used. - [[HYPERLINK_A028]] can only be used for those referrals, on the 'Appointment Slot Issues' worklist, which are pending review. - As such, you need to use [[HYPERLINK_A029]] to determine if [[HYPERLINK_A028]] is a permissible action. You need to use [[HYPERLINK_A005]] to retrieve the details for the referral. You need to use [[HYPERLINK_A006]] to retrieve the clinical attachments for the referral. You need to use [[HYPERLINK_A007]] to retrieve the clinical information summary PDF for the referral. If you want to include attachments with the triage outcome, you need to use [[HYPERLINK_A020]] so they are ready to be associated when this endpoint is called. ## Use cases As an authenticated user I need to return the referral back to the referrer with some advice So that I can progress the patient's care appropriately with the referrer. As an authenticated user I need to accept the referral and task my admin team to shortlist appropriate services for the patient So that I can progress the patient's care along the most appropriate referral pathway. ## Important notes - The only outcomes that are supported by this endpoint are 'Return to referrer with advice' and 'Accept and refer/book later'. 'Refer/book now' is not supported. - The triage comment text is mandatory. This comment provided will be sent to: - The initial referrer when the 'Return to referrer with advice' triage outcome is chosen. - An administrator at the receiving service provider when the 'Accept and refer/book later' outcome is chosen. - The priority of the referral can be changed as part of recording the triage outcome - When this endpoint is successfully used for recording an outcome of 'Accept and refer/book later', an entry will be added to the service providers Appointments For Booking worklist for the admin team to action the task. The provider admin team will only be able to progress the referral via the e-RS Professional Application user interface (e.g. shortlisting appropriate services for the patient). summary: A028 - Record triage outcome operationId: a028-record-triage-outcome parameters: - $ref: 'components/schemas/headers/request/ContentTypeFhirJson.yaml' - $ref: 'components/schemas/headers/request/BearerAuthorization.yaml' - $ref: 'components/schemas/headers/request/OdsCode.yaml' - $ref: 'components/schemas/headers/request/BusinessFunction.yaml' - $ref: 'components/schemas/headers/request/OnBehalfOfUserID.yaml' - $ref: 'components/schemas/headers/request/CorrelationID.yaml' - $ref: 'components/schemas/path/Ubrn.yaml' requestBody: required: true content: application/fhir+json: schema: $ref: 'components/schemas/eRS-RecordReviewOutcome-Parameters.yaml' examples: return-to-referrer-with-advice: summary: Return to referrer with advice value: $ref: 'components/examples/recordTriageOutcome/requests/ReturnToReferrerWithAdvice.json' accept-refer-book-later: summary: Accept refer book later value: $ref: 'components/examples/recordTriageOutcome/requests/AcceptReferBookLater.json' attachment-included: summary: Attachment included value: $ref: 'components/examples/recordTriageOutcome/requests/AttachmentIncluded.json' responses: '200': $ref: 'components/schemas/responses/recordTriageOutcome/200Response.yaml' '400': $ref: 'components/schemas/responses/BadRequest.yaml' '401': $ref: 'components/schemas/responses/Unauthorized.yaml' '403': $ref: 'components/schemas/responses/Forbidden.yaml' '404': $ref: 'components/schemas/responses/NotFound.yaml' '406': $ref: 'components/schemas/responses/NotAcceptable.yaml' '409': $ref: 'components/schemas/responses/Conflict.yaml' '415': $ref: 'components/schemas/responses/UnsupportedMediaType.yaml' '422': $ref: 'components/schemas/responses/recordTriageOutcome/422Response.yaml' '423': $ref: 'components/schemas/responses/Locked.yaml' '429': $ref: 'components/schemas/responses/TooManyRequests.yaml' '500': $ref: 'components/schemas/responses/InternalServerError.yaml' /STU3/ReferralRequest/{ubrn}/$ers.acceptReferral: post: security: - bearerAuth: [] description: | ## Overview Use this endpoint, as a service provider, to accept a referral that is booked into your bookable service and awaiting review. ## Supported security patterns - Healthcare worker, user-restricted access ## Pre-requisites In order to use this endpoint you must be an authenticated e-RS user and use one of the following e-RS roles: - `SERVICE_PROVIDER_CLINICIAN` - `SERVICE_PROVIDER_CLINICIAN_ADMIN` You need to use [[HYPERLINK_A008]] to retrieve the contents of the 'Referrals For Review' worklist. [[HYPERLINK_A013]] can only be used for referrals booked into bookable services, and not the referrals sent into triage services. You need to use [[HYPERLINK_A005]] to retrieve the details for the referral. You need to use [[HYPERLINK_A006]] to retrieve the clinical attachments for the referral. You need to use [[HYPERLINK_A007]] to retrieve the clinical information summary PDF for the referral. ## Use cases As an authenticated user I need to accept an inbound referral after its review So that I can confirm the patient's referral is appropriate for the current service and booked appointment date/time. summary: A013 - Accept referral operationId: a013-accept-referral parameters: - $ref: 'components/schemas/headers/request/BearerAuthorization.yaml' - $ref: 'components/schemas/headers/request/OdsCode.yaml' - $ref: 'components/schemas/headers/request/BusinessFunction.yaml' - $ref: 'components/schemas/headers/request/OnBehalfOfUserID.yaml' - $ref: 'components/schemas/headers/request/CorrelationID.yaml' - $ref: 'components/schemas/path/Ubrn.yaml' - $ref: 'components/schemas/headers/request/IfMatch.yaml' responses: '200': $ref: 'components/schemas/responses/acceptReferral/200Response.yaml' '400': $ref: 'components/schemas/responses/BadRequest.yaml' '401': $ref: 'components/schemas/responses/Unauthorized.yaml' '403': $ref: 'components/schemas/responses/Forbidden.yaml' '404': $ref: 'components/schemas/responses/NotFound.yaml' '406': $ref: 'components/schemas/responses/NotAcceptable.yaml' '409': $ref: 'components/schemas/responses/Conflict.yaml' '412': $ref: 'components/schemas/responses/PreconditionFailed.yaml' '422': $ref: 'components/schemas/responses/acceptReferral/422Response.yaml' '423': $ref: 'components/schemas/responses/Locked.yaml' '429': $ref: 'components/schemas/responses/TooManyRequests.yaml' '500': $ref: 'components/schemas/responses/InternalServerError.yaml' /STU3/ReferralRequest/{ubrn}/$ers.rejectReferral: post: security: - bearerAuth: [] description: | ## Overview Use this endpoint, as a service provider, to reject a referral that is booked into your bookable service and awaiting review. This returns the referral to the referrer with a mandatory user comment to explain why it has been rejected. Consider using [[HYPERLINK_A022]] instead if you wish to ask your admin team to get the patient into the most appropriate service. ## Supported security patterns - Healthcare worker, user-restricted access ## Pre-requisites In order to use this endpoint you must be an authenticated e-RS user and use one of the following e-RS roles: - `SERVICE_PROVIDER_CLINICIAN` - `SERVICE_PROVIDER_CLINICIAN_ADMIN` You need to use [[HYPERLINK_A008]] to retrieve the contents of the 'Referrals For Review' worklist. [[HYPERLINK_A014]] can only be used for referrals booked into bookable services, and not the referrals sent into triage services. You need to use [[HYPERLINK_A005]] to retrieve the details for the referral. You need to use [[HYPERLINK_A006]] to retrieve the clinical attachments for the referral. You need to use [[HYPERLINK_A007]] to retrieve the clinical information summary PDF for the referral. You need to use [[HYPERLINK_A004]] to retrieve a list of rejection reason reference data codes along with their user-friendly display names. To find relevant rejection reasons, obtain reference data from `APPOINTMENT-CANCELLATION-REASON` and filter as follows: - `appointmentBookingCancellationReasonType` must be `PROVIDER_REJECT` - `effectiveFrom` must be in the past, and - `effectiveTo` must not be in the past ## Use cases As an authenticated user I need to reject an inbound referral back to the referrer after its review with an explanation of why So that the referrer can address the reason for rejection and progress the referral appropriately. summary: A014 - Reject referral operationId: a014-reject-referral parameters: - $ref: 'components/schemas/headers/request/ContentTypeFhirJson.yaml' - $ref: 'components/schemas/headers/request/BearerAuthorization.yaml' - $ref: 'components/schemas/headers/request/OdsCode.yaml' - $ref: 'components/schemas/headers/request/BusinessFunction.yaml' - $ref: 'components/schemas/headers/request/OnBehalfOfUserID.yaml' - $ref: 'components/schemas/headers/request/CorrelationID.yaml' - $ref: 'components/schemas/path/Ubrn.yaml' - $ref: 'components/schemas/headers/request/IfMatch.yaml' requestBody: required: true content: application/fhir+json: schema: $ref: 'components/schemas/eRS-RejectReferral-Parameters.yaml' examples: basic-example-ibs: summary: Basic example for IBS value: $ref: 'components/examples/rejectReferral/requests/BasicExampleIbs.json' basic-example-dbs: summary: Basic example for DBS value: $ref: 'components/examples/rejectReferral/requests/BasicExampleDbs.json' responses: '200': $ref: 'components/schemas/responses/rejectReferral/200Response.yaml' '400': $ref: 'components/schemas/responses/BadRequest.yaml' '401': $ref: 'components/schemas/responses/Unauthorized.yaml' '403': $ref: 'components/schemas/responses/Forbidden.yaml' '404': $ref: 'components/schemas/responses/NotFound.yaml' '406': $ref: 'components/schemas/responses/NotAcceptable.yaml' '409': $ref: 'components/schemas/responses/Conflict.yaml' '412': $ref: 'components/schemas/responses/PreconditionFailed.yaml' '415': $ref: 'components/schemas/responses/UnsupportedMediaType.yaml' '422': $ref: 'components/schemas/responses/rejectReferral/422Response.yaml' '423': $ref: 'components/schemas/responses/Locked.yaml' '429': $ref: 'components/schemas/responses/TooManyRequests.yaml' '500': $ref: 'components/schemas/responses/InternalServerError.yaml' '504': $ref: 'components/schemas/responses/rejectReferral/504Response.yaml' /STU3/Task: get: security: - bearerAuth: [ ] description: | ## Overview This endpoint allows an authenticated e-RS user to check ahead of performing an action, whether or not the action is permitted. This endpoint performs a search for available and supported actions that can be *currently* performed, by the *current* e-RS user on a *specific* referral. When a permitted action is returned, the e-RS user could immediately attempt to perform a permitted action. You SHOULD NOT cache the list of available user actions returned because this endpoint gives the *current* actions for the *current* e-RS user, for the referral in context and is therefore, transient; a future call for a different e-RS user, referral, or at a different point in time, might result in a different set of actions, leading to potential failure flows. ## Supported security patterns - Healthcare worker, user-restricted access ## Pre-requisites In order to use this endpoint you must be an authenticated e-RS user and use one of the following e-RS roles: - `REFERRING_CLINICIAN` - `REFERRING_CLINICIAN_ADMIN` - `SERVICE_PROVIDER_CLINICIAN` - `SERVICE_PROVIDER_CLINICIAN_ADMIN` You should obtain a `Unique Booking Reference Number` (UBRN) before using this endpoint, as the current UBRN version is required. ## Use case As an authenticated user I want to know what actions I might currently perform on a referral prior to attempting to do so So that I can review my options, and do not try to persist a prohibited action ## Related endpoints To retrieve pertinent details relating to a referral: - Use [[HYPERLINK_A005]] to retrieve the details of the referral, UBRN and UBRN version. Below is a list of actions that could be returned by calling [[HYPERLINK_A029]] - Use [[HYPERLINK_A028]] to record a review outcome based on the available clinical information and attachments. - Use [[HYPERLINK_A016]] to Book, or if unable, Defer, an appointment to a specific service on the current shortlist. - Use [[HYPERLINK_A031]] to change the shortlist of bookable services on an existing referral. - Use [[HYPERLINK_A032]] to change the shortlist to a single triage service and refer the patient directly to that triage service. ## Sandbox test scenarios You can test the following scenarios in our sandbox environment | Scenario | Request | | --------------------------------------------------- | ---------------------------------------------------------------------------------------- | | No "action" is available | `focus`=`ReferralRequest/000000070000/_history/6`, `intent`=`proposal`, `status`=`ready` | | "Record Review Outcome" is available | `focus`=`ReferralRequest/000000070001/_history/6`, `intent`=`proposal`, `status`=`ready` | | "Create Appointment" is available | `focus`=`ReferralRequest/000000070002/_history/6`, `intent`=`proposal`, `status`=`ready` | | "Change Shortlist" is available | `focus`=`ReferralRequest/000000070003/_history/6`, `intent`=`proposal`, `status`=`ready` | | "Change Shortlist and Send for Triage" is available | `focus`=`ReferralRequest/000000070004/_history/6`, `intent`=`proposal`, `status`=`ready` | | "Cancel Referral" is available | `focus`=`ReferralRequest/000000070005/_history/6`, `intent`=`proposal`, `status`=`ready` | | "Cancel Directly Booked Appointment" is available | `focus`=`ReferralRequest/000000070006/_history/6`, `intent`=`proposal`, `status`=`ready` | summary: A029 - Available actions for user list operationId: a029-available-actions-for-user-list parameters: - $ref: 'components/schemas/headers/request/BearerAuthorization.yaml' - $ref: 'components/schemas/headers/request/OdsCode.yaml' - $ref: 'components/schemas/headers/request/BusinessFunction.yaml' - $ref: 'components/schemas/headers/request/OnBehalfOfUserID.yaml' - $ref: 'components/schemas/headers/request/CorrelationID.yaml' - $ref: 'components/schemas/queryParameters/Focus.yaml' - $ref: 'components/schemas/queryParameters/Intent.yaml' - $ref: 'components/schemas/queryParameters/TaskStatus.yaml' responses: '200': $ref: 'components/schemas/responses/availableActionsForUserList/200Response.yaml' '400': $ref: 'components/schemas/responses/availableActionsForUserList/400Response.yaml' '401': $ref: 'components/schemas/responses/Unauthorized.yaml' '403': $ref: 'components/schemas/responses/Forbidden.yaml' '406': $ref: 'components/schemas/responses/NotAcceptable.yaml' '429': $ref: 'components/schemas/responses/TooManyRequests.yaml' '500': $ref: 'components/schemas/responses/InternalServerError.yaml' /STU3/ReferralRequest/{ubrn}/$ers.cancelAppointmentActionLater: post: security: - bearerAuth: [] description: | ## Overview Use this endpoint, as a service provider, to task your admin team to rebook/redirect a referral that is booked into your bookable service and awaiting review. Note: this will also cancel the current appointment. ## Supported security patterns - Healthcare worker, user-restricted access ## Pre-requisites In order to use this endpoint you must be an authenticated e-RS user and use one of the following e-RS roles: - `SERVICE_PROVIDER_CLINICIAN` - `SERVICE_PROVIDER_CLINICIAN_ADMIN` You need to use [[HYPERLINK_A008]] to retrieve the contents of the 'Referrals For Review' worklist. [[HYPERLINK_A022]] can only be used for referrals booked into bookable services, and not the referrals sent into triage services. You need to use [[HYPERLINK_A005]] to retrieve the details for the referral. You need to use [[HYPERLINK_A006]] to retrieve the clinical attachments for the referral. You need to use [[HYPERLINK_A007]] to retrieve the clinical information summary PDF for the referral. If you want to include attachments with the admin task, you need to use [[HYPERLINK_A020]] so they are ready to be associated when this endpoint is called. ## Use cases As an authenticated user I need to task my admin team to rebook/redirect a referral I have reviewed (whilst also cancelling the current appointment) So that I can progress the patient's care along the most appropriate referral pathway. ## Important notes - The priority of the referral can be changed as part of this endpoint. - A comment must be added to explain to the administrator what is required and can include optional attachments. - The current appointment is cancelled as part of this endpoint. If the current appointment is booked to an indirectly bookable service, you must indicate whether the appointment has been cancelled on the local provider system. If indicated as not cancelled, the referral will be added to the 'Indirectly Booked Appointments to Cancel in PAS' worklist to task the admin team to do so. - When this endpoint is successfully used, an entry will be added to the service providers 'Appointments For Booking' worklist for the admin team to action the task. The provider admin team will only be able to progress the referral via the e-RS Professional Application user interface (e.g. shortlisting appropriate services for the patient). summary: A022 - Cancel appointment, action later operationId: a022-cancel-appointment-action-later parameters: - $ref: 'components/schemas/headers/request/ContentTypeFhirJson.yaml' - $ref: 'components/schemas/headers/request/BearerAuthorization.yaml' - $ref: 'components/schemas/headers/request/OdsCode.yaml' - $ref: 'components/schemas/headers/request/BusinessFunction.yaml' - $ref: 'components/schemas/headers/request/OnBehalfOfUserID.yaml' - $ref: 'components/schemas/headers/request/CorrelationID.yaml' - $ref: 'components/schemas/path/Ubrn.yaml' - $ref: 'components/schemas/headers/request/IfMatch.yaml' requestBody: required: true content: application/fhir+json: schema: $ref: 'components/schemas/eRS-cancelAppointmentActionLater-Parameters.yaml' examples: basic-example-dbs: summary: Basic example for DBS value: $ref: 'components/examples/cancelAppointmentActionLater/requests/MinimalExampleDBS.json' example-priority-change-and-attachments: summary: Example for priority change and attachments value: $ref: 'components/examples/cancelAppointmentActionLater/requests/PriorityChangeAndWithAttachmentsDBS.json' basic-example-ibs: summary: Basic example for IBS value: $ref: 'components/examples/cancelAppointmentActionLater/requests/MinimalExampleIBS.json' responses: '200': $ref: 'components/schemas/responses/cancelAppointmentActionLater/200Response.yaml' '400': $ref: 'components/schemas/responses/BadRequest.yaml' '401': $ref: 'components/schemas/responses/Unauthorized.yaml' '403': $ref: 'components/schemas/responses/Forbidden.yaml' '404': $ref: 'components/schemas/responses/NotFound.yaml' '406': $ref: 'components/schemas/responses/NotAcceptable.yaml' '409': $ref: 'components/schemas/responses/Conflict.yaml' '412': $ref: 'components/schemas/responses/PreconditionFailed.yaml' '415': $ref: 'components/schemas/responses/UnsupportedMediaType.yaml' '422': $ref: 'components/schemas/responses/cancelAppointmentActionLater/422Response.yaml' '423': $ref: 'components/schemas/responses/Locked.yaml' '429': $ref: 'components/schemas/responses/TooManyRequests.yaml' '500': $ref: 'components/schemas/responses/InternalServerError.yaml' /R4/HealthcareService/{id}: get: security: - bearerAuth: [] description: | ## Overview A patient may have 0 to 20 services associated with a single referral. A service is a place where a referrer can send a patient or obtain clinical advice concerning a specific patient. Services have attributes that can be used to understand a services functionality, terms of use, and contact information. You can use this endpoint to obtain the current version and attributes of a single service. ## Supported security patterns - Healthcare worker, user-restricted access ## Pre-requisites In order to use this endpoint you must be an authenticated e-RS user and use one of the following e-RS roles: - `REFERRING_CLINICIAN` - `REFERRING_CLINICIAN_ADMIN` You need to have identified one service ID in order to use this endpoint. ## Use case As an authenticated user I would like to be able to see current service information So that I can trust that the service information is correct for my patient's referral ## Related endpoints - You can retrieve service IDs on a referral via [[HYPERLINK_A005]] as long as the referral has a shortlist containing at least a single service. - You can check if a cached service has changed via [[HYPERLINK_A037]]. - You can retrieve the attributes of an entire shortlist of services (1-20) via [[HYPERLINK_A035]]. ## Sandbox test scenarios You can test the following scenarios in our sandbox environment | Scenario | Service Id | | ------------------------------------------------------------------------ | ---------- | | `Service` and minimal attributes | `1` | | `Service` and its attributes | `2` | summary: A033 - Retrieve healthcare service operationId: a033-retrieve-healthcare-service parameters: - $ref: 'components/schemas/headers/request/BearerAuthorization.yaml' - $ref: 'components/schemas/path/ServiceId.yaml' - $ref: 'components/schemas/headers/request/OdsCode.yaml' - $ref: 'components/schemas/headers/request/BusinessFunction.yaml' - $ref: 'components/schemas/headers/request/CorrelationID.yaml' responses: '200': $ref: 'components/schemas/responses/getService/200Response.yaml' '403': $ref: 'components/schemas/responses/Forbidden.yaml' '404': $ref: 'components/schemas/responses/NotFound.yaml' '429': $ref: 'components/schemas/responses/TooManyRequests.yaml' '500': $ref: 'components/schemas/responses/InternalServerError.yaml' head: security: - bearerAuth: [] description: | A Patient may have 0 to 20 services associated with a single referral. A service is a place where a referrer can send a patient or obtain clinical advice concerning a specific patient. You can use this endpoint to obtain the current service's "version" held in e-RS, in order to compare to a locally cached version. ## Supported security patterns - Healthcare worker, user-restricted access ## Pre-requisites In order to use this endpoint you must be an authenticated e-RS user and use one of the following e-RS roles: - `REFERRING_CLINICIAN` - `REFERRING_CLINICIAN_ADMIN` You need to have identified one service ID in order to use this endpoint. ## Use case As an authenticated user I would like to be able to see the current information about a service on my patients current shortlist So that I can review and trust the information is still valid within the context of my patients needs ## Related endpoints - You can obtain Service IDs on a referral via [[HYPERLINK_A005]] as long as the referral has a shortlist containing at least one service. - You can retrieve a set of services and their attributes via [[HYPERLINK_A035]]. - You can fetch the attributes of a single service via [[HYPERLINK_A033]]. ## Sandbox test scenarios You can test the following scenarios in our sandbox environment | Scenario | Service Id | | ------------------------------------------------------------------------ | ---------- | | Get `Service` Version | `1` | summary: A037 - Retrieve healthcare service version operationId: a037-retrieve-healthcare-service-version parameters: - $ref: 'components/schemas/headers/request/BearerAuthorization.yaml' - $ref: 'components/schemas/path/ServiceId.yaml' - $ref: 'components/schemas/headers/request/OdsCode.yaml' - $ref: 'components/schemas/headers/request/BusinessFunction.yaml' - $ref: 'components/schemas/headers/request/CorrelationID.yaml' responses: '200': $ref: 'components/schemas/responses/retrieveServiceVersion/200Response.yaml' '403': $ref: 'components/schemas/responses/Forbidden.yaml' '404': $ref: 'components/schemas/responses/NotFound.yaml' '429': $ref: 'components/schemas/responses/TooManyRequests.yaml' '500': $ref: 'components/schemas/responses/InternalServerError.yaml' /R4/HealthcareService: get: security: - bearerAuth: [] description: | ## Overview A Patient may have 0 to 20 Services associated with a single referral. A service is a place where a referrer can send a patient or obtain clinical advise concerning a specific patient. You can use this endpoint to obtain a set of services (up to 20) and their associated attributes, in a single call. ## Supported security patterns - Healthcare worker, user-restricted access ## Pre-requisites In order to use this endpoint you must be an authenticated e-RS user and use one of the following e-RS roles: - `REFERRING_CLINICIAN` - `REFERRING_CLINICIAN_ADMIN` You need to have identified one service ID in order to use this endpoint. ## Use case As an authenticated user I would like to obtain information about all services on my patients current shortlist So that I can review the entire shortlist of services and each services current attributes ## Related endpoints - You can retrieve service IDs on a referral via [[HYPERLINK_A005]] as long as the referral has a shortlist of at least one service. - You can check if a cached service has changed via [[HYPERLINK_A037]]. - You can fetch the attributes of a single service via [[HYPERLINK_A033]]. ## Sandbox test scenarios You can test the following scenarios in our sandbox environment | Scenario | Service Id | | ------------------------------------------------------------------------------------------------------------ | ---------- | | Search for multiple service with minimal attributes | `1,2` | | Search for multiple service max and min attributes | `3`,`4` | | Search for multiple service, where the service IDs are formatted correctly, but non of the service IDs match | `5`,`6` | summary: A035 - Search for healthcare services operationId: a035-search-for-healthcare-services parameters: - $ref: 'components/schemas/headers/request/BearerAuthorization.yaml' - $ref: 'components/schemas/headers/request/OdsCode.yaml' - $ref: 'components/schemas/headers/request/BusinessFunction.yaml' - $ref: 'components/schemas/headers/request/CorrelationID.yaml' - in: query name: _id description: | One or many service ID(s) to include as part of the search. Must be supplied, otherwise a 400 response will be returned. required: true schema: type: string example: '1,2' responses: '200': $ref: 'components/schemas/responses/searchForService/200Response.yaml' '400': $ref: 'components/schemas/responses/searchForService/400Response.yaml' '403': $ref: 'components/schemas/responses/Forbidden.yaml' '404': $ref: 'components/schemas/responses/NotFound.yaml' '406': $ref: 'components/schemas/responses/NotAcceptable.yaml' '415': $ref: 'components/schemas/responses/UnsupportedMediaType.yaml' '429': $ref: 'components/schemas/responses/TooManyRequests.yaml' '500': $ref: 'components/schemas/responses/InternalServerError.yaml' /STU3/ReferralRequest/{ubrn}/$ers.changeShortlist: post: security: - bearerAuth: [] description: | ## Overview Use this endpoint to change the shortlist of bookable services on an existing referral. Please note: this endpoint cannot be used to shortlist triage services. In order to make use of triage services please use [[HYPERLINK_A032]]. A patient can request assistance at a service (e.g. a translator, transport or advocacy) when a shortlist is created within the e-RS web application, meaning that all services shortlisted would support the patient's additional requirements to attend. The e-RS APIs do not currently support patients' additional requirements so you can neither specify services that support patients' additional requirements, arrange additional requirements for a patient, or view comments associated with the request for additional requirements. You must consider if you are fully meeting the patient's additional requirement needs if there are additional requirements associated with the referral. If you do not know whether the patient has an existing additional requirement need and the referral may have been shortlisted within the e-RS web application, be mindful that if you chose to amend the shortlist via changing the services, you could remove this patient need. If you are changing services to send the patient to a triage service, the triaging service will not support additional requirements but will need to consider if the patient has any additional requirements as part of their decision for future care. You can view additional requirements on a referral via the e-RS web application or by fetching [[HYPERLINK_A005]]. ## Supported security patterns - Healthcare worker, user-restricted access ## Pre-requisites In order to use this endpoint you must be an authenticated e-RS user and use one of the following e-RS roles: - `REFERRING_CLINICIAN` - `REFERRING_CLINICIAN_ADMIN` You need to use the `Unique Booking Reference Number` (UBRN) of a referral request in order to use this endpoint. You need to have found services that meet the referral needs of a patient using [[HYPERLINK_A010]]. ## Use case As an authenticated user I need to change the shortlist of bookable services on an existing referral So that I can adequately manage my patients referral pathway, allowing the patient to book into an appropriate service. ## Related endpoints To allow the patient to book their appointment in their own time, you can generate a letter for the patient by using [[HYPERLINK_A019]]. The letter summarises the current state of the referral and any steps the patient may need to follow (e.g. appointment booking instructions). You can book an appointment for the patient by using [[HYPERLINK_A015]] and [[HYPERLINK_A016]]. For the referral to be processed by the service provider, you must ensure appropriate referral letter information has been added to the referral. You can add/manage referrer letter information by using [[HYPERLINK_A012]]. You can check to see what referral letter information has already been added to a referral by using [[HYPERLINK_A005]], [[HYPERLINK_A007]], and [[HYPERLINK_A006]] endpoints where necessary. summary: A031 - Change shortlist operationId: a031-change-shortlist parameters: - $ref: 'components/schemas/headers/request/ContentTypeFhirJson.yaml' - $ref: 'components/schemas/headers/request/BearerAuthorization.yaml' - $ref: 'components/schemas/headers/request/OdsCode.yaml' - $ref: 'components/schemas/headers/request/BusinessFunction.yaml' - $ref: 'components/schemas/headers/request/CorrelationID.yaml' - $ref: 'components/schemas/headers/request/IfMatch.yaml' - $ref: 'components/schemas/path/Ubrn.yaml' requestBody: required: true content: application/fhir+json: schema: $ref: 'components/schemas/eRS-ChangeShortlist-Parameters.yaml' examples: unbookedReferralRequest: summary: Unbooked ReferralRequest description: Changing the shortlist of an unbooked `ReferralRequest` (single service shortlist) value: $ref: 'components/examples/changeShortlist/requests/UnbookedReferral.json' unbookedReferralRequestMultipleServices: summary: Unbooked ReferralRequest with Multiple Services description: Changing the shortlist of an unbooked `ReferralRequest` (multiple services shortlist) value: $ref: 'components/examples/changeShortlist/requests/UnbookedReferralMultipleServices.json' responses: '200': $ref: 'components/schemas/responses/changeShortlist/200Response.yaml' '400': $ref: 'components/schemas/responses/BadRequest.yaml' '401': $ref: 'components/schemas/responses/Unauthorized.yaml' '403': $ref: 'components/schemas/responses/Forbidden.yaml' '404': $ref: 'components/schemas/responses/NotFound.yaml' '409': $ref: 'components/schemas/responses/Conflict.yaml' '406': $ref: 'components/schemas/responses/NotAcceptable.yaml' '415': $ref: 'components/schemas/responses/UnsupportedMediaType.yaml' '422': $ref: 'components/schemas/responses/changeShortlist/422Response.yaml' '423': $ref: 'components/schemas/responses/Locked.yaml' '429': $ref: 'components/schemas/responses/TooManyRequests.yaml' '500': $ref: 'components/schemas/responses/InternalServerError.yaml' /STU3/ReferralRequest/{ubrn}/$ers.changeShortlistAndSendForTriage: post: security: - bearerAuth: [] description: | ## Overview Use this endpoint to change the shortlist to a single triage service and refer the patient directly to that triage service. Please note: this endpoint cannot be used to shortlist bookable services. In order to shortlist bookable services on an existing referral please use [[HYPERLINK_A031]]. A patient can request assistance at a service (e.g. a translator, transport or advocacy) when a shortlist is created within the e-RS web application, meaning that all services shortlisted would support the patient's additional requirements to attend. The e-RS APIs do not currently support patients' additional requirements so you can neither specify services that support patients' additional requirements, arrange additional requirements for a patient, or view comments associated with the request for additional requirements. You must consider if you are fully meeting the patient's additional requirement needs if there are additional requirements associated with the referral. If you do not know whether the patient has an existing additional requirement need and the referral may have been shortlisted within the e-RS web application, be mindful that if you chose to amend the shortlist via changing the services, you could remove this patient need. If you are changing services to send the patient to a triage service, the triaging service will not support additional requirements but will need to consider if the patient has any additional requirements as part of their decision for future care. You can view additional requirements on a referral via the e-RS web application or by fetching [[HYPERLINK_A005]]. ## Supported security patterns - Healthcare worker, user-restricted access ## Pre-requisites In order to use this endpoint you must be an authenticated e-RS user and use one of the following e-RS roles: - `REFERRING_CLINICIAN` - `REFERRING_CLINICIAN_ADMIN` You need to use the `Unique Booking Reference Number` (UBRN) of a referral request in order to use this endpoint. You need to have found services that meet the referral needs of a patient using [[HYPERLINK_A010]]. ## Use case As an authenticated user I need to change the shortlist and refer the patient to a triage service for assessment So that I can put the patient on the appropriate clinical pathway for the chosen service provider. ## Related endpoints For the referral to be processed by the service provider, you must ensure appropriate referral letter information has been added to the referral. You can add/manage referrer letter information by using [[HYPERLINK_A012]]. You can check to see what referral letter information has already been added to a referral by using [[HYPERLINK_A005]], [[HYPERLINK_A006]], and [[HYPERLINK_A007]] endpoints where necessary. You can calculate the date when the patient will need to be contacted (by the triage service) using reference data from [[HYPERLINK_A004]]. summary: A032 - Change shortlist and send for triage operationId: a032-change-shortlist-and-send-for-triage parameters: - $ref: 'components/schemas/headers/request/ContentTypeFhirJson.yaml' - $ref: 'components/schemas/headers/request/BearerAuthorization.yaml' - $ref: 'components/schemas/headers/request/OdsCode.yaml' - $ref: 'components/schemas/headers/request/BusinessFunction.yaml' - $ref: 'components/schemas/headers/request/CorrelationID.yaml' - $ref: 'components/schemas/headers/request/IfMatch.yaml' - $ref: 'components/schemas/path/Ubrn.yaml' requestBody: required: true content: application/fhir+json: schema: $ref: 'components/schemas/eRS-ChangeShortlistAndSendForTriage-Request-Parameters.yaml' examples: parameters: summary: Unbooked ReferralRequest description: Changing the service list of an unbooked `ReferralRequest` and sending to Triage value: $ref: 'components/examples/changeShortlistAndSendForTriage/requests/MinimalRequest.json' responses: '200': $ref: 'components/schemas/responses/changeShortlistAndSendForTriage/200Response.yaml' '400': $ref: 'components/schemas/responses/BadRequest.yaml' '401': $ref: 'components/schemas/responses/Unauthorized.yaml' '403': $ref: 'components/schemas/responses/Forbidden.yaml' '404': $ref: 'components/schemas/responses/NotFound.yaml' '409': $ref: 'components/schemas/responses/Conflict.yaml' '406': $ref: 'components/schemas/responses/NotAcceptable.yaml' '415': $ref: 'components/schemas/responses/UnsupportedMediaType.yaml' '422': $ref: 'components/schemas/responses/changeShortlist/422Response.yaml' '423': $ref: 'components/schemas/responses/Locked.yaml' '429': $ref: 'components/schemas/responses/TooManyRequests.yaml' '500': $ref: 'components/schemas/responses/InternalServerError.yaml' /STU3/Appointment/{id}: put: security: - bearerAuth: [] description: | ## Overview Use this endpoint to cancel an appointment that is booked into a directly-bookable service. Appointments made to directly-bookable services always have a date and time. You can only ever update the current appointment, i.e. an appointment that is related to a service on the current shortlist *and* the most recent appointment made. Currently, this endpoint only allows cancellation of an appointment as an update. Future developments may permit further updates. To cancel the referral, use [[HYPERLINK_A036]]. ## Supported security patterns - Healthcare worker, user-restricted access ## Pre-requisites In order to use this endpoint you must be an authenticated e-RS user and use one of the following e-RS roles: - `REFERRING_CLINICIAN` - `REFERRING_CLINICIAN_ADMIN` You must use [[HYPERLINK_A004]] to retrieve reference data from the set `APPOINTMENT-CANCELLATION-REASON`. To find out which reference data from this set can be used to cancel an appointment, filter as follows: - *usage* must be `CANCEL`, - *businessFunction* must be `REFERRING_CLINICIAN` or `REFERRING_CLINICIAN_ADMIN` (depending which authenticated user will be performing the action), - *effectiveFrom* must be in the past, and - *effectiveTo* must not be in the past Both the appointment reference, and version, are needed to update an appointment: You must use [[HYPERLINK_A005]] to obtain the current appointment reference (via *Extension-eRS-Appointment-Reference-1*). You must use [[HYPERLINK_A038]] to obtain the current appointment and get the current appointment's version. ## Use case As an authenticated user I need to update the current appointment So that I can manage the patients care appropriately. ## Related endpoints You can retrieve the reference data needed to cancel an appointment by using [[HYPERLINK_A004]]. This contains "reasons" for cancellation. You can check if you currently can cancel the appointment by checking [[HYPERLINK_A029]]. You must use [[HYPERLINK_A005]] to obtain the current appointment reference (via *Extension-eRS-Appointment-Reference-1*) . You must use [[HYPERLINK_A038]] to obtain the current appointment and get the current appointment's version. You can use [[HYPERLINK_A031]] after updating an appointment, to create a new shortlist of services. After changing a shortlist, you may be able to [[HYPERLINK_A016]]. summary: A034 - Update appointment operationId: a034-update-appointment parameters: - $ref: 'components/schemas/headers/request/ContentTypeFhirJson.yaml' - $ref: 'components/schemas/headers/request/BearerAuthorization.yaml' - $ref: 'components/schemas/headers/request/OdsCode.yaml' - $ref: 'components/schemas/headers/request/BusinessFunction.yaml' - $ref: 'components/schemas/headers/request/CorrelationID.yaml' - $ref: 'components/schemas/path/AppointmentId.yaml' - $ref: 'components/schemas/headers/request/IfMatch.yaml' requestBody: required: true content: application/fhir+json: schema: $ref: 'components/schemas/eRS-Appointment.yaml' examples: minimal-cancellation-reason-only: summary: Minimal Cancellation - Only Reason Provided (when a cancellation comment is not mandatory) value: $ref: 'components/examples/updateAppointment/requests/MinimalCancellationReasonOnlyCommentNotMandatory.json' cancellation-reason-and-comment: summary: Reason and Comment Provided value: $ref: 'components/examples/updateAppointment/requests/CancellationReasonAndMandatoryComment.json' cancellation-reason-only-comment-mandatory: summary: Only Reason Provided (when a cancellation comment is mandatory) value: $ref: 'components/examples/updateAppointment/requests/CancellationReasonOnlyCommentMandatory.json' unauthorised-cancellation-reason: summary: Unauthorised Cancellation Reason value: $ref: 'components/examples/updateAppointment/requests/CancellationInvalidReason.json' responses: '200': $ref: 'components/schemas/responses/updateAppointment/200Response.yaml' '400': $ref: 'components/schemas/responses/BadRequest.yaml' '403': $ref: 'components/schemas/responses/Forbidden.yaml' '404': $ref: 'components/schemas/responses/NotFound.yaml' '406': $ref: 'components/schemas/responses/NotAcceptable.yaml' '409': $ref: 'components/schemas/responses/Conflict.yaml' '412': $ref: 'components/schemas/responses/PreconditionFailed.yaml' '415': $ref: 'components/schemas/responses/UnsupportedMediaType.yaml' '422': $ref: 'components/schemas/responses/updateAppointment/422Response.yaml' '423': $ref: 'components/schemas/responses/Locked.yaml' '429': $ref: 'components/schemas/responses/TooManyRequests.yaml' '500': $ref: 'components/schemas/responses/InternalServerError.yaml' '502': $ref: 'components/schemas/responses/updateAppointment/502Response.yaml' '504': $ref: 'components/schemas/responses/updateAppointment/504Response.yaml' get: security: - bearerAuth: [] description: | ## Overview Use this endpoint to retrieve the current version of an appointment. An appointment is made to a service so a patient can be seen or for the referral to be reviewed, prior to care. A referral may, or may not, have an appointment and an appointment will always relate to a specific referral. It is possible to have more than one appointment during the life of the referral, but never concurrent appointments. This endpoint only returns the current appointment and does not support historic views. The outcome of a referral review can be recorded on an appointment. Cancellation or maintenance of an appointment (such as the intent to cancel the current appointment and book another one later) are recorded against the current appointment. e-RS currently supports a number of appointment scenarios: - Where a booking has been made to a directly-bookable service (DBS) - Where a deferred booking is made when a slot could not be found at a directly-bookable service. In this case, the service "books" the appointment - Where a booking has been made to a indirectly-bookable service (IBS) - Where a review is required by a triage service - Where a review has been conducted by a triage service - Where a service has rejected, or accepted an appointment - Where an appointment has been cancelled, and no further action is possible - Where an appointment is currently cancelled, but a future appointment may be made by a service later ## Supported security patterns - Healthcare worker, user-restricted access ## Pre-requisites In order to use this endpoint you must be an authenticated e-RS user and use one of the following e-RS roles: - `REFERRING_CLINICIAN` - `REFERRING_CLINICIAN_ADMIN` - `SERVICE_PROVIDER_CLINICIAN` - `SERVICE_PROVIDER_CLINICIAN_ADMIN` You need to use the `Unique Booking Reference Number` (UBRN) of a referral in order to retrieve details of an appointment that it relates to. Note: e-RS only supports the retrieval of the most recent version of Appointment. You cannot retrieve earlier versions. ## Use case As an authenticated user I want to read details of an appointment So that I can decide what further action may be needed. ## Related endpoints Note that in some cases below, an appointment forms part of the referral returned. You can always retrieve the current version of an existing appointment via [[HYPERLINK_A005]]. When successfully accepting an appointment, the accepted appointment is returned via [[HYPERLINK_A013]]. When successfully rejecting an appointment, the rejected appointment is returned via [[HYPERLINK_A014]]. When booking or deferring an appointment, the appointment is returned via [[HYPERLINK_A016]]. When sending an appointment to a service to review, an appointment is returned via [[HYPERLINK_A021]]. In this case the "appointment" is to review a referral. When changing a shortlist and sending an instruction to a service to review, an appointment is returned via [[HYPERLINK_A032]] indicating an "appointment" to review a referral. When successfully cancelling an appointment, to action it later, the cancelled appointment is returned via [[HYPERLINK_A022]]. When converting an advice and guidance to a referral, if the referral has an appointment, it will be returned via [[HYPERLINK_A027]]. Having successfully reviewed a referral, details of that review are shown on the appointment returned via [[HYPERLINK_A028]]. You will need the appointment version when using [[HYPERLINK_A034]], which can be obtained from [[HYPERLINK_A038]]. If an appointment is cancelled as part of [[HYPERLINK_A036]], an appointment will be returned as part of a successful response. ## Sandbox test scenarios You can test the following scenarios in our sandbox environment | Scenario | Request | | --------------------------------------------------------------------------------------------------------- | ----------------------- | | `Appointment` booked to directly-bookable service | `appointmentId`=`70000` | | `Appointment` booked to indirectly-bookable service | `appointmentId`=`70001` | | `Appointment` deferred to service provider for booking | `appointmentId`=`70002` | | `Appointment` sent for triage | `appointmentId`=`70003` | | `Appointment` triage response (Record Triage Outcome) | `appointmentId`=`70004` | | `Appointment` Cancel Appointment, Action Later | `appointmentId`=`70005` | | `Appointment` cancelled | `appointmentId`=`70006` | | `Appointment` converted from an Advice and Guidance Request and booked to a directly-bookable service | `appointmentId`=`70007` | summary: A038 - Retrieve appointment operationId: a038-retrieve-appointment parameters: - $ref: 'components/schemas/headers/request/BearerAuthorization.yaml' - $ref: 'components/schemas/headers/request/OdsCode.yaml' - $ref: 'components/schemas/headers/request/BusinessFunction.yaml' - $ref: 'components/schemas/headers/request/OnBehalfOfUserID.yaml' - $ref: 'components/schemas/headers/request/CorrelationID.yaml' - $ref: 'components/schemas/path/AppointmentId.yaml' responses: '200': $ref: 'components/schemas/responses/retrieveAppointment/200Response.yaml' '400': $ref: 'components/schemas/responses/BadRequest.yaml' '401': $ref: 'components/schemas/responses/Unauthorized.yaml' '403': $ref: 'components/schemas/responses/Forbidden.yaml' '404': $ref: 'components/schemas/responses/NotFound.yaml' '406': $ref: 'components/schemas/responses/NotAcceptable.yaml' '422': $ref: 'components/schemas/responses/retrieveAppointment/422Response.yaml' '429': $ref: 'components/schemas/responses/TooManyRequests.yaml' '500': $ref: 'components/schemas/responses/InternalServerError.yaml' /STU3/Appointment/{id}/_history/{version}: get: security: - bearerAuth: [ ] description: | ## Overview Use this endpoint to retrieve a specific version of an `Appointment`. ## Supported security patterns - Healthcare worker, user-restricted access ## Pre-requisites The pre-requisites for this endpoint are the same as for endpoint [[HYPERLINK_A038]]. Note: e-RS only supports the retrieval of the most recent version of an `Appointment`. You cannot retrieve earlier versions. ## Use case See [[HYPERLINK_A038]]. ## Related endpoints See [[HYPERLINK_A038]]. ## Sandbox test scenarios You can test the following scenarios in our sandbox environment | Scenario | Request | | --------------------------------------------------------------------------------------------------------- | -------------------------------------- | | `Appointment` booked to directly-bookable service | `appointmentId`=`70000`, `version`=`5` | | `Appointment` booked to indirectly-bookable service | `appointmentId`=`70001`, `version`=`5` | | `Appointment` deferred to service provider for booking | `appointmentId`=`70002`, `version`=`5` | | `Appointment` sent for triage | `appointmentId`=`70003`, `version`=`5` | | `Appointment` triage response (Record Triage Outcome) | `appointmentId`=`70004`, `version`=`5` | | `Appointment` Cancel Appointment, Action Later | `appointmentId`=`70005`, `version`=`5` | | `Appointment` cancelled | `appointmentId`=`70006`, `version`=`5` | | `Appointment` converted from an Advice and Guidance Request and booked to a directly-bookable service | `appointmentId`=`70007`, `version`=`5` | summary: A038 - Retrieve appointment (versioned) operationId: a038-retrieve-appointment-versioned parameters: - $ref: 'components/schemas/headers/request/BearerAuthorization.yaml' - $ref: 'components/schemas/headers/request/OdsCode.yaml' - $ref: 'components/schemas/headers/request/BusinessFunction.yaml' - $ref: 'components/schemas/headers/request/OnBehalfOfUserID.yaml' - $ref: 'components/schemas/headers/request/CorrelationID.yaml' - $ref: 'components/schemas/path/AppointmentId.yaml' - $ref: 'components/schemas/path/Version.yaml' responses: '200': $ref: 'components/schemas/responses/retrieveAppointment/200Response.yaml' '400': $ref: 'components/schemas/responses/BadRequest.yaml' '401': $ref: 'components/schemas/responses/Unauthorized.yaml' '403': $ref: 'components/schemas/responses/Forbidden.yaml' '404': $ref: 'components/schemas/responses/NotFound.yaml' '406': $ref: 'components/schemas/responses/NotAcceptable.yaml' '422': $ref: 'components/schemas/responses/retrieveAppointment/422Response.yaml' '429': $ref: 'components/schemas/responses/TooManyRequests.yaml' '500': $ref: 'components/schemas/responses/InternalServerError.yaml' /STU3/ReferralRequest/{ubrn}/$ers.cancelReferral: post: security: - bearerAuth: [] description: | ## Overview Use this endpoint to cancel a referral and the current appointment, if there is one. Cancelling a referral is a one-way process and results in an end-state. No further progression of care can occur once this action has been performed. A reason for cancelling an appointment must be provided. A comment on the cancellation is conditionally mandatory depending on the reason selected. See pre-requisites and related referrals for more information. You can check if you can cancel a referral by calling [[HYPERLINK_A029]]. e-RS does not allow a referral to be cancelled, without also cancelling the current appointment. Therefore, if there is a current appointment associated with the referral, this *must* be cancelled in advance, or at the same time. In order to cancel (only) an appointment you must use [[HYPERLINK_A034]]. ## Supported security patterns - Healthcare worker, user-restricted access ## Pre-requisites In order to use this endpoint you must be an authenticated e-RS user and use one of the following e-RS roles: - `REFERRING_CLINICIAN` - `REFERRING_CLINICIAN_ADMIN` You must use [[HYPERLINK_A004]] to retrieve a list of reference data, which detail the reason the cancellation is being performed. You can only use reference data from the set `REFERRAL-CANCELLATION-REASON`. To find out which reference data from this set can be used, the following filters can be used depending on the cancellation scenario: ***1. I want to cancel the referral and the current appointment*** * Obtain reference data from `REFERRAL-CANCELLATION-REASON` and filter: * `referrerUsage` must be `CANCEL_REFERRAL`, and * `businessFunction` must be `REFERRING_CLINICIAN` or `REFERRING_CLINICIAN_ADMIN` (depending which authenticated user will be performing the action), and * `canCancelAppointment` must be true, and * `effectiveFrom` must be in the past, and * if provided, `effectiveTo` must **not** be in the past ***2. I want to cancel a referral, for which there is no current appointment*** * Obtain reference data from `REFERRAL-CANCELLATION-REASON` and filter: * `referrerUsage` must be `CANCEL_REFERRAL`, and * `businessFunction` must be `REFERRING_CLINICIAN` or `REFERRING_CLINICIAN_ADMIN` *(depending which authenticated user will be performing the action), and * `canCancelAppointment` could be true or false, and * `effectiveFrom` must be in the past, and * if provided, `effectiveTo` must **not** be in the past You need to use [[HYPERLINK_A005]] to retrieve details of the referral in order to make this clinical decision. ## Use case As an authenticated user I need to cancel a referral, and any active appointments So that the referral is no longer processed ## Related endpoints You can retrieve the reference data needed to cancel a referral by using [[HYPERLINK_A004]]. This contains "reasons" for cancellation. You can check if you can cancel the referral by checking [[HYPERLINK_A029]]. You can use [[HYPERLINK_A005]] to obtain a current appointment reference, if there is one. This endpoint will also provide you with the current UBRN version. You can use [[HYPERLINK_A038]] to view the current appointment (where applicable). ## Sandbox test scenarios You can test the following scenarios in our sandbox environment: | Scenario | Request details | | ------------------------------------------------------------------------ | --------------------------------- | | Reason for Cancellation without Comment (Comment Not Mandatory) | Intend Private With No Comment | | Reason for Cancellation with Comment (Comment Mandatory) | Patient Cancellation With Comment | | Cancelled Referral | Raised in Error | | Cancelled Appointment and Referral | Referrer Cancellation | | Cancelled Referral After Prior Appointment Cancellation | Treatment No Longer Required | | Cancelled Referral with Existing Review Outcome | Intend Private With Comment | summary: A036 - Cancel referral operationId: a036-cancel-referral parameters: - $ref: 'components/schemas/headers/request/ContentTypeFhirJson.yaml' - $ref: 'components/schemas/headers/request/BearerAuthorization.yaml' - $ref: 'components/schemas/headers/request/OdsCode.yaml' - $ref: 'components/schemas/headers/request/BusinessFunction.yaml' - $ref: 'components/schemas/headers/request/CorrelationID.yaml' - $ref: 'components/schemas/path/Ubrn.yaml' - $ref: 'components/schemas/headers/request/IfMatch.yaml' requestBody: required: true content: application/fhir+json: schema: $ref: 'components/schemas/eRS-CancelReferral-Request-Parameters.yaml' examples: cancel-referral-without-comment: summary: Reason for Cancellation without Comment (Comment Not Mandatory) value: $ref: 'components/examples/cancelReferral/requests/IntendPrivateWithoutComment.json' cancel-referral-patient-cancellation: summary: Reason for Cancellation with Comment (Comment Mandatory) value: $ref: 'components/examples/cancelReferral/requests/PatientRequestCancellationOther.json' cancel-referral-raised-in-error: summary: Cancelled Referral value: $ref: 'components/examples/cancelReferral/requests/RaisedInError.json' cancel-referral-referrer-cancellation: summary: Cancelled Appointment and Referral value: $ref: 'components/examples/cancelReferral/requests/ReferrerCancellation.json' cancel-referral-no-longer-required: summary: Cancelled Referral After Prior Appointment Cancellation value: $ref: 'components/examples/cancelReferral/requests/NoLongerRequired.json' cancel-referral-with-reason-and-comment: summary: Cancelled Referral with Existing Review Outcome value: $ref: 'components/examples/cancelReferral/requests/IntendPrivateWithComment.json' responses: '200': $ref: 'components/schemas/responses/cancelReferral/200Response.yaml' '400': $ref: 'components/schemas/responses/BadRequest.yaml' '401': $ref: 'components/schemas/responses/Unauthorized.yaml' '403': $ref: 'components/schemas/responses/Forbidden.yaml' '404': $ref: 'components/schemas/responses/NotFound.yaml' '406': $ref: 'components/schemas/responses/NotAcceptable.yaml' '409': $ref: 'components/schemas/responses/Conflict.yaml' '412': $ref: 'components/schemas/responses/PreconditionFailed.yaml' '415': $ref: 'components/schemas/responses/UnsupportedMediaType.yaml' '422': $ref: 'components/schemas/responses/cancelReferral/422Response.yaml' '423': $ref: 'components/schemas/responses/Locked.yaml' '429': $ref: 'components/schemas/responses/TooManyRequests.yaml' '500': $ref: 'components/schemas/responses/InternalServerError.yaml' '502': $ref: 'components/schemas/responses/cancelReferral/502Response.yaml' '504': $ref: 'components/schemas/responses/cancelReferral/504Response.yaml' components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT