# 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://digital.nhs.uk/developer/api-catalogue/e-referral-service-fhir' 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). For an overview of how you can plan and prepare for your integration with e-RS, see our [API onboarding guide](https://digital.nhs.uk/services/e-referral-service/api). **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 - create a new advice and guidance request **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 - cancel 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

To discover the most common use cases, see our Building Healthcare Software guides.

### Access modes This API has two access modes: | Access mode | Authentication via | Functions | Availability | | ----------------------------- | -------------------------- | ----------------------- | ------------------------------- | | Application-restricted,
unattended access | [[HYPERLINK_SIGNED_JWT]] | | [[HYPERLINK_PRODUCTION]] | | Healthcare worker,
user-restricted access | [[HYPERLINK_CIS_AUTH_SHORT]] | All Endpoints | [[HYPERLINK_PRODUCTION]] | ##### 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. Write operations are currently supported for specific use cases via: - [[HYPERLINK_A028]] - [[HYPERLINK_A013]] - [[HYPERLINK_A036]] You will be required to submit your use case for review when using these endpoints via application-restricted, unattended access. ##### Healthcare worker, user-restricted access This access mode allows Partner applications to access e-RS FHIR API endpoints by authenticating users with [[HYPERLINK_CIS_AUTH_LONG]]. 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, for use in a professional, clinical setting. To use this API you must: - have justification for doing so - [register with us](https://digital.nhs.uk/services/e-referral-service/api/integration-process/stage-1-design#1-8-register-with-us) - ensure you have a [valid use case](https://digital.nhs.uk/services/e-referral-service/api/integration-process/stage-1-design#1-2-validate-your-use-case) before you go too far with your development - [assure](https://digital.nhs.uk/services/e-referral-service/api/integration-process/stage-3-assure) your solution before we grant access to live data ## 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 ### This API has two access modes: - Application-restricted, unattended access - Healthcare worker, user-restricted access ### Application-restricted, unattended access This access mode is [[HYPERLINK_PRODUCTION]], meaning: - we avoid making routine [breaking changes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/sunsetting-policy#breaking-changes), except in exceptional circumstances - if we need to deprecate an endpoint, we will give advance notice on our [board](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/deprecation-notices). Our [sunsetting page](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/sunsetting-policy) details our deprecation and retirement policy. ### Healthcare worker, user-restricted access This access mode is [[HYPERLINK_PRODUCTION]], meaning: - we avoid making routine [breaking changes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/sunsetting-policy#breaking-changes), except in exceptional circumstances - if we need to deprecate an endpoint, we will give advance notice on our [board](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/deprecation-notices). Our [sunsetting page](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/sunsetting-policy) details our deprecation and retirement policy. ### Roadmap Visit our [roadmap page](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/roadmap) for details of what we are working on. To suggest, comment or vote on features for this API, see our [interactive product backlog](https://portal.productboard.com/qhpkcqgctqtk3ujk8jyoajp8/tabs/4-new-requests). ## Service level This API is a gold service, meaning it is operational and supported 24 hours a day, 365 days a year. 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. This API supports FHIR STU3 and FHIR R4. ### FHIR STU3 The e-RS FHIR STU3 API is built against the set of profiles called [CareConnect](https://nhsconnect.github.io/CareConnectAPI/). ### FHIR R4 The e-RS FHIR R4 API is built alongside the [NHS England FHIR Implementation Guide](https://simplifier.net/guide/nhsdigital), which is built on top of [FHIR UK Core](https://digital.nhs.uk/services/fhir-uk-core). The canonical URLs listed in the schema can be resolved with [https://simplifier.net/resolve](https://simplifier.net/resolve). ## 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 This API has two access modes: - Application-restricted, unattended access - Healthcare worker, user-restricted access ### 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. Write operations are currently only supported by [[HYPERLINK_A028]] for non-clinical use cases. You will be required to submit your use case for review when using this endpoint via application-restricted, unattended access. 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 [[HYPERLINK_CIS_AUTH_LONG]] In order to successfully authenticate with CIS2, the NHS e-Referral Service requires end users to be authenticated to the following standards: - an [Identity Assurance Level (IAL)](https://digital.nhs.uk/services/care-identity-service/applications-and-services/cis2-authentication/guidance-for-developers/detailed-guidance/scopes-and-claims#claims ) of IAL3 - an [Authenticator Assurance Level (AAL)](https://digital.nhs.uk/services/care-identity-service/applications-and-services/cis2-authentication/guidance-for-developers/detailed-guidance/acr-values#authentication-methods) of AAL2 or AAL3 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) We strongly recommend the use of separate authentication and authorisation. This mode will provide you access to the healthcare workers identity, allowing you to reuse it across multiple applications such as PDS. You can [learn more](https://digital.nhs.uk/services/e-referral-service/api/integration-process/stage-1.4---select-your-authentication-level#1-access-modes) about each access mode option on our onboarding guide. #### 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` | | 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. ### Integration testing Our [integration test](https://digital.nhs.uk/developer/guides-and-documentation/testing#integration-testing-with-our-restful-apis) 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 you can go live with this API. We call this onboarding. The onboarding process can sometimes be quite long, so it's worth planning well ahead. We use the Supplier Conformance Assessment List (SCAL) process. [Learn more](https://digital.nhs.uk/services/e-referral-service/api/integration-process/stage-1-design#1-7-learn-how-to-onboard) about onboarding. ## Errors We use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range: * 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action * 400 to 499 if it failed because of a client error by your application * 500 to 599 if it failed because of an error on our server Errors specific to each API are shown in the Endpoints section, under Response. See our [reference guide](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#http-status-codes) for more on errors. 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.' tags: - name: Retrieve user information - name: Refer patient - name: Arrange appointment - name: Arrange triage - name: Request advice - name: Retrieve healthcare service information - name: Change appointment - name: Manage referral - name: Retrieve clinical information - name: Review referral requests - name: Review advice and guidance requests paths: /STU3/CodeSystem/{codeSystemType}: get: $ref: 'components/stu3/schemas/endpoints/a004-retrieve-reference-data.yaml' /STU3/ReferralRequest/$ers.fetchworklist: post: $ref: 'components/stu3/schemas/endpoints/a008-retrieve-worklist.yaml' /STU3/ReferralRequest/{ubrn}: get: $ref: 'components/stu3/schemas/endpoints/a005-retrieve-referral-request.yaml' /STU3/Task: get: $ref: 'components/stu3/schemas/endpoints/a029-available-actions-for-user-list.yaml' /STU3/ReferralRequest/{ubrn}/_history/{version}: get: $ref: 'components/stu3/schemas/endpoints/a005-retrieve-referral-request-versioned.yaml' /STU3/Binary/{attachmentLogicalID}: get: $ref: 'components/stu3/schemas/endpoints/a006-retrieve-attachment.yaml' /R4/Binary/{id}: get: $ref: 'components/r4/schemas/endpoints/a042-retrieve-attachment.yaml' /STU3/ReferralRequest/{ubrn}/$ers.generateCRI: post: $ref: 'components/stu3/schemas/endpoints/a007-retrieve-clinical-information.yaml' /STU3/HealthcareService/$ers.searchHealthcareServicesForPatient: post: $ref: 'components/stu3/schemas/endpoints/a010-patient-service-search.yaml' /STU3/ReferralRequest/$ers.createReferral: post: $ref: 'components/stu3/schemas/endpoints/a011-create-referral.yaml' /STU3/ReferralRequest/$ers.createReferralAndSendForTriage: post: $ref: 'components/stu3/schemas/endpoints/a021-create-referral-request-and-send-for-triage.yaml' /STU3/Slot: get: $ref: 'components/stu3/schemas/endpoints/a015-retrieve-appointment-slots.yaml' /STU3/Appointment: post: $ref: 'components/stu3/schemas/endpoints/a016-book-or-defer-appointment.yaml' /STU3/Binary: post: $ref: 'components/stu3/schemas/endpoints/a020-upload-file-to-document-store.yaml' /STU3/ReferralRequest/{ubrn}/$ers.maintainReferralLetter: post: $ref: 'components/stu3/schemas/endpoints/a012-maintain-referral-letter.yaml' /STU3/ReferralRequest/{ubrn}/$ers.acceptReferral: post: $ref: 'components/stu3/schemas/endpoints/a013-accept-referral.yaml' /STU3/ReferralRequest/{ubrn}/$ers.rejectReferral: post: $ref: 'components/stu3/schemas/endpoints/a014-reject-referral.yaml' /STU3/ReferralRequest/{ubrn}/$ers.generatePatientLetter: post: $ref: 'components/stu3/schemas/endpoints/a019-generate-patient-letter.yaml' /STU3/ReferralRequest/{ubrn}/$ers.cancelAppointmentActionLater: post: $ref: 'components/stu3/schemas/endpoints/a022-cancel-appointment-action-later.yaml' /STU3/CommunicationRequest/$ers.fetchworklist: post: $ref: 'components/stu3/schemas/endpoints/a023-retrieve-a&g-worklist.yaml' /STU3/CommunicationRequest/{ubrn}: get: $ref: 'components/stu3/schemas/endpoints/a024-retrieve-advice-and-guidance.yaml' /STU3/CommunicationRequest/{ubrn}/_history/{version}: get: $ref: 'components/stu3/schemas/endpoints/a024-retrieve-advice-and-guidance-versioned.yaml' /STU3/Communication: get: $ref: 'components/stu3/schemas/endpoints/a025-retrieve-advice-and-guidance-conversation.yaml' /STU3/CommunicationRequest/{ubrn}/$ers.sendCommunicationToRequester: post: $ref: 'components/stu3/schemas/endpoints/a026-send-a&g-response.yaml' /STU3/ReferralRequest/$ers.createFromCommunicationRequestActionLater: post: $ref: 'components/stu3/schemas/endpoints/a027-convert-a&g-to-referral.yaml' /STU3/ReferralRequest/{ubrn}/$ers.recordReviewOutcome: post: $ref: 'components/stu3/schemas/endpoints/a028-record-triage-outcome.yaml' /R4/PractitionerRole: get: $ref: 'components/r4/schemas/endpoints/a030-retrieve-business-functions.yaml' /STU3/ReferralRequest/{ubrn}/$ers.changeShortlist: post: $ref: 'components/stu3/schemas/endpoints/a031-change-shortlist.yaml' /STU3/ReferralRequest/{ubrn}/$ers.changeShortlistAndSendForTriage: post: $ref: 'components/stu3/schemas/endpoints/a032-change-shortlist-and-send-for-triage.yaml' /R4/HealthcareService/{id}: get: $ref: 'components/r4/schemas/endpoints/a033-retrieve-healthcare-service.yaml' head: $ref: 'components/r4/schemas/endpoints/a037-retrieve-healthcare-service-version.yaml' /STU3/Appointment/{id}: put: $ref: 'components/stu3/schemas/endpoints/a034-update-appointment.yaml' get: $ref: 'components/stu3/schemas/endpoints/a038-retrieve-appointment.yaml' /STU3/Appointment/{id}/_history/{version}: get: $ref: 'components/stu3/schemas/endpoints/a038-retrieve-appointment-versioned.yaml' /R4/HealthcareService: get: $ref: 'components/r4/schemas/endpoints/a035-search-for-healthcare-services.yaml' /STU3/ReferralRequest/{ubrn}/$ers.cancelReferral: post: $ref: 'components/stu3/schemas/endpoints/a036-cancel-referral.yaml' /R4/Practitioner: get: $ref: 'components/r4/schemas/endpoints/a040-retrieve-practitioner-info.yaml' /STU3/CommunicationRequest/{ubrn}/$ers.generateCRI: post: $ref: 'components/stu3/schemas/endpoints/a043-retrieve-advice-and-guidance-overview-pdf.yaml' /STU3/CommunicationRequest/$ers.createAdviceAndGuidance: post: $ref: 'components/stu3/schemas/endpoints/a044-create-advice-and-guidance-request.yaml' /R4/ServiceRequest: get: $ref: 'components/r4/schemas/endpoints/a041-search-service-request.yaml' components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT