# 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), [A007](#api-Default-a007-retrieve-clinical-information), [A024](#api-Default-a024-retrieve-advice-and-guidance), [A025](#api-Default-a025-retrieve-advice-and-guidance-conversation) and [A043](#api-Default-a043-retrieve-advice-and-guidance-overview-pdf) | [In production, beta](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses) | | 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) | [In production, beta](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses) | ##### 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, for use in a professional, clinical setting. 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 production, beta](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses). We are onboarding Partners to use it. Please note that it can only be used: - when authenticating a human user is not possible - for endpoints that offer read-only functionality - by ‘Provider Organisations’ (currently) - for accessing endpoints [A004](#api-Default-a004-retrieve-reference-data), [A005](#api-Default-a005-retrieve-referral-request), [A006](#api-Default-a006-retrieve-attachment), [A007](#api-Default-a007-retrieve-clinical-information), [A024](#api-Default-a024-retrieve-advice-and-guidance), [A025](#api-Default-a025-retrieve-advice-and-guidance-conversation) and [A043](#api-Default-a043-retrieve-advice-and-guidance-overview-pdf) (currently) For more information, please see [Network access](#api-description__network-access). ### Healthcare worker, user-restricted access This access mode is [in production, beta](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses). We are onboarding Partners to use it. This access mode allows you to use [all endpoints](#api-endpoints) . A human user must be present and authenticated. For more information, please see [Network access](#api-description__network-access). ### 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#statuses) 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](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 it can go live. We call this process onboarding. Onboarding essentially involves connecting to the e-RS FHIR API Integration (INT) environment, 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 configure 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 [liveserviceonboarding@nhs.net](mailto:liveserviceonboarding@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 (EUOAUP), please liaise with [liveserviceonboarding@nhs.net](mailto:liveserviceonboarding@nhs.net). In step 14: following receipt, review and acceptance of your signed Connection Agreement, the e-RS FHIR API Partners team will contact you to facilitate production access for your application. ## 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.' paths: /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/HealthcareService/$ers.searchHealthcareServicesForPatient: post: $ref: 'components/stu3/schemas/endpoints/a010-patient-service-search.yaml' /STU3/CodeSystem/{codeSystemType}: get: $ref: 'components/stu3/schemas/endpoints/a004-retrieve-reference-data.yaml' /STU3/Slot: get: $ref: 'components/stu3/schemas/endpoints/a015-retrieve-appointment-slots.yaml' /R4/PractitionerRole: get: $ref: 'components/r4/schemas/endpoints/a030-retrieve-business-functions.yaml' /STU3/Binary: post: $ref: 'components/stu3/schemas/endpoints/a020-upload-file-to-document-store.yaml' /STU3/ReferralRequest/{ubrn}/$ers.generatePatientLetter: post: $ref: 'components/stu3/schemas/endpoints/a019-generate-patient-letter.yaml' /STU3/Binary/{attachmentLogicalID}: get: $ref: 'components/stu3/schemas/endpoints/a006-retrieve-attachment.yaml' /STU3/ReferralRequest/{ubrn}: get: $ref: 'components/stu3/schemas/endpoints/a005-retrieve-referral-request.yaml' /STU3/ReferralRequest/{ubrn}/_history/{version}: get: $ref: 'components/stu3/schemas/endpoints/a005-retrieve-referral-request-versioned.yaml' /STU3/ReferralRequest/{ubrn}/$ers.maintainReferralLetter: post: $ref: 'components/stu3/schemas/endpoints/a012-maintain-referral-letter.yaml' /STU3/Appointment: post: $ref: 'components/stu3/schemas/endpoints/a016-book-or-defer-appointment.yaml' /STU3/ReferralRequest/{ubrn}/$ers.generateCRI: post: $ref: 'components/stu3/schemas/endpoints/a007-retrieve-clinical-information.yaml' /STU3/ReferralRequest/$ers.fetchworklist: post: $ref: 'components/stu3/schemas/endpoints/a008-retrieve-worklist.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' /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/Task: get: $ref: 'components/stu3/schemas/endpoints/a029-available-actions-for-user-list.yaml' /STU3/ReferralRequest/{ubrn}/$ers.cancelAppointmentActionLater: post: $ref: 'components/stu3/schemas/endpoints/a022-cancel-appointment-action-later.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' /R4/HealthcareService: get: $ref: 'components/r4/schemas/endpoints/a035-search-for-healthcare-services.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' /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' /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' components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT