diff --git a/specification/components/r4/schemas/endpoints/a033-retrieve-healthcare-service.yaml b/specification/components/r4/schemas/endpoints/a033-retrieve-healthcare-service.yaml index e70fc8059..0ddacd5d0 100644 --- a/specification/components/r4/schemas/endpoints/a033-retrieve-healthcare-service.yaml +++ b/specification/components/r4/schemas/endpoints/a033-retrieve-healthcare-service.yaml @@ -35,6 +35,9 @@ description: | - 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]]. + ## Known Issues + The HealthcareService.type attribute is being returned as a singular object by this endpoint. As per the [FHIR standard](https://hl7.org/fhir/R4/), this attribute should be an array. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information. + ## Sandbox test scenarios You can test the following scenarios in our sandbox environment diff --git a/specification/components/r4/schemas/endpoints/a035-search-for-healthcare-services.yaml b/specification/components/r4/schemas/endpoints/a035-search-for-healthcare-services.yaml index b38e02185..95b3345b8 100644 --- a/specification/components/r4/schemas/endpoints/a035-search-for-healthcare-services.yaml +++ b/specification/components/r4/schemas/endpoints/a035-search-for-healthcare-services.yaml @@ -34,6 +34,9 @@ description: | - You can check if a cached service has changed via [[HYPERLINK_A037]]. - You can fetch the attributes of a single service via [[HYPERLINK_A033]]. + ## Known Issues + The HealthcareService.type attribute is being returned as a singular object by this endpoint. As per the [FHIR standard](https://hl7.org/fhir/R4/), this attribute should be an array. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information. + ## Sandbox test scenarios You can test the following scenarios in our sandbox environment diff --git a/specification/components/r4/schemas/endpoints/a042-retrieve-attachment.yaml b/specification/components/r4/schemas/endpoints/a042-retrieve-attachment.yaml index 282bc0a61..41bc67c0d 100644 --- a/specification/components/r4/schemas/endpoints/a042-retrieve-attachment.yaml +++ b/specification/components/r4/schemas/endpoints/a042-retrieve-attachment.yaml @@ -4,6 +4,15 @@ description: | ## Overview Use this endpoint to retrieve a file that is attached to a referral or advice request. + Referral information can also include: + - Structured clinical information added by an integrated primary care system + - Service provider activity + - Advice and guidance conversation + + This additional clinical information must be retrieved via [[HYPERLINK_A007]] + + [Read](https://digital.nhs.uk/developer/guides-and-documentation/building-healthcare-software/referrals-and-bookings/e-referral-service/retrieve-clinical-referral-information-as-a-service-provider) our building healthcare software guide for detailed information. + ## Supported security patterns - Application-restricted, unattended access - Healthcare worker, user-restricted access diff --git a/specification/components/stu3/schemas/endpoints/a005-retrieve-referral-request.yaml b/specification/components/stu3/schemas/endpoints/a005-retrieve-referral-request.yaml index 3589f78a9..fd198619f 100644 --- a/specification/components/stu3/schemas/endpoints/a005-retrieve-referral-request.yaml +++ b/specification/components/stu3/schemas/endpoints/a005-retrieve-referral-request.yaml @@ -93,6 +93,11 @@ description: | You can retrieve reference data used in viewing a referral using [[HYPERLINK_A004]] + ## Known Issues + + 1. The Participant.type attribute is being mapped as a single type for this endpoint. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be an array. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information. + 2. The participant of an Appointment references a value set. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be a coding system. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information. + ## Sandbox test scenarios You can test the following scenarios in our sandbox environment diff --git a/specification/components/stu3/schemas/endpoints/a007-retrieve-clinical-information.yaml b/specification/components/stu3/schemas/endpoints/a007-retrieve-clinical-information.yaml index 15c2d415a..5d08d2fe2 100644 --- a/specification/components/stu3/schemas/endpoints/a007-retrieve-clinical-information.yaml +++ b/specification/components/stu3/schemas/endpoints/a007-retrieve-clinical-information.yaml @@ -5,6 +5,10 @@ description: | Use this endpoint to generate a PDF file that summarises clinical information for a referral. + This does not include files attached to a referral or advice request. These must be retrieved via [[HYPERLINK_A042]] + + [Read](https://digital.nhs.uk/developer/guides-and-documentation/building-healthcare-software/referrals-and-bookings/e-referral-service/retrieve-clinical-referral-information-as-a-service-provider) our building healthcare software guide for detailed information. + ## Supported security patterns - Application-restricted access - Healthcare worker, user-restricted access diff --git a/specification/components/stu3/schemas/endpoints/a011-create-referral.yaml b/specification/components/stu3/schemas/endpoints/a011-create-referral.yaml index ad8cbcf1e..75300ebeb 100644 --- a/specification/components/stu3/schemas/endpoints/a011-create-referral.yaml +++ b/specification/components/stu3/schemas/endpoints/a011-create-referral.yaml @@ -11,6 +11,9 @@ description: | The maximum amount of services allowed on a given shortlist is 20. The act of shortlisting alone will not result in a referral being sent/booked to any of the shortlisted services (even if only one service is shortlisted). + Use [[HYPERLINK_A016]] if there is a need to support the sending/booking of the referral into a shortlisted service. + A shortlist of a single triage service should be avoided as this relies on the patient to progress the referral, potentially leading to a delay to care. Especially if the referral priority is 2WW or Urgent. + Use [[HYPERLINK_A016]] if there is a need to support the sending/booking of the referral into a shortlisted service. ## Important notes when sending an e-Referral Pathway Start Date @@ -60,6 +63,11 @@ description: | 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]]. + ## Known Issues + + 1. The Participant.type attribute is being mapped as a single type for this endpoint. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be an array. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information. + 2. The participant of an Appointment references a value set. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be a coding system. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information. + summary: Create referral (A011, FHIR STU3) operationId: a011-create-referral tags: diff --git a/specification/components/stu3/schemas/endpoints/a012-maintain-referral-letter.yaml b/specification/components/stu3/schemas/endpoints/a012-maintain-referral-letter.yaml index ff16049e4..894cf08cc 100644 --- a/specification/components/stu3/schemas/endpoints/a012-maintain-referral-letter.yaml +++ b/specification/components/stu3/schemas/endpoints/a012-maintain-referral-letter.yaml @@ -75,6 +75,11 @@ description: | 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. + ## Known Issues + + 1. The Participant.type attribute is being mapped as a single type for this endpoint. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be an array. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information. + 2. The participant of an Appointment references a value set. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be a coding system. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information. + ## Sandbox test scenarios You can test the following scenarios in our sandbox environment: diff --git a/specification/components/stu3/schemas/endpoints/a013-accept-referral.yaml b/specification/components/stu3/schemas/endpoints/a013-accept-referral.yaml index aa508169d..640bdf1f8 100644 --- a/specification/components/stu3/schemas/endpoints/a013-accept-referral.yaml +++ b/specification/components/stu3/schemas/endpoints/a013-accept-referral.yaml @@ -41,6 +41,11 @@ description: | 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. + + ## Known Issues + + 1. The Participant.type attribute is being mapped as a single type for this endpoint. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be an array. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information. + 2. The participant of an Appointment references a value set. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be a coding system. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information. summary: Accept referral (A013, FHIR STU3) operationId: a013-accept-referral diff --git a/specification/components/stu3/schemas/endpoints/a014-reject-referral.yaml b/specification/components/stu3/schemas/endpoints/a014-reject-referral.yaml index a8cce4d0e..5009cf60d 100644 --- a/specification/components/stu3/schemas/endpoints/a014-reject-referral.yaml +++ b/specification/components/stu3/schemas/endpoints/a014-reject-referral.yaml @@ -44,6 +44,11 @@ description: | 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. + + ## Known Issues + + 1. The Participant.type attribute is being mapped as a single type for this endpoint. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be an array. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information. + 2. The participant of an Appointment references a value set. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be a coding system. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information. summary: Reject referral (A014, FHIR STU3) operationId: a014-reject-referral diff --git a/specification/components/stu3/schemas/endpoints/a015-retrieve-appointment-slots.yaml b/specification/components/stu3/schemas/endpoints/a015-retrieve-appointment-slots.yaml index 9d0aab2c0..8703217b2 100644 --- a/specification/components/stu3/schemas/endpoints/a015-retrieve-appointment-slots.yaml +++ b/specification/components/stu3/schemas/endpoints/a015-retrieve-appointment-slots.yaml @@ -24,6 +24,10 @@ description: | ## Important note You need to provide the 'commissioning rule organisation' when calling [[HYPERLINK_A015]] to ensure only suitable slots are returned. You can obtain the 'commissioning rule organisation' from [[HYPERLINK_A005]]. + + When slots are retrieved using this endpoint, they can include slots with or without a named clinician associated with them. Your integrated application must support both scenarios. + + Slots with a named clinician will have an additional "actor" which defines the SDS User ID of the clinician, this will be on the Schedule associated to the Slot. ## Related endpoints @@ -34,6 +38,9 @@ description: | - 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) + ## Known Issues + This endpoint is using the :Practitioner search parameter. The "schedule.actor" search parameter is incorrectly using the ":Practitioner" modifier. As per the [FHIR standard](https://hl7.org/fhir/R4/) the ":identifier" modifier should be used when searching to indicate that an Identifer is used rather than a literal, relative, internal or absolute reference. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information. + ## Sandbox test scenarios You can test the following scenarios in our sandbox environment: diff --git a/specification/components/stu3/schemas/endpoints/a016-book-or-defer-appointment.yaml b/specification/components/stu3/schemas/endpoints/a016-book-or-defer-appointment.yaml index a95fbb34b..8ec4092ee 100644 --- a/specification/components/stu3/schemas/endpoints/a016-book-or-defer-appointment.yaml +++ b/specification/components/stu3/schemas/endpoints/a016-book-or-defer-appointment.yaml @@ -27,6 +27,12 @@ description: | - 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) + ## Important note when booking slots + + When appointment slots are booked using this endpoint, it may be necessary to provide the named clinician details. This is because slots can be setup with or without a named clinician. Your integrated application must support both scenarios. + + When booking a slot using [[HYPERLINK_A016]], the named clinician details must be added to the “Appointment.partcipant” list. As shown in the “Booking with named clinician” example. + ## Use case As an authenticated user @@ -43,6 +49,11 @@ description: | Where deferring the booking responsibility to a directly bookable service, or referring the patient into a triage service, you can calculate the date when the patient can expect to be contacted (by the receiving service) using reference data from [[HYPERLINK_A004]]. + ## Known Issues + + 1. The Participant.type attribute is being mapped as a single type for this endpoint. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be an array. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information. + 2. The participant of an Appointment references a value set. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be a coding system. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information. + summary: Book or defer appointment (A016, FHIR STU3) operationId: a016-book-or-defer-appointment tags: diff --git a/specification/components/stu3/schemas/endpoints/a021-create-referral-request-and-send-for-triage.yaml b/specification/components/stu3/schemas/endpoints/a021-create-referral-request-and-send-for-triage.yaml index f9c88deae..ff92676dd 100644 --- a/specification/components/stu3/schemas/endpoints/a021-create-referral-request-and-send-for-triage.yaml +++ b/specification/components/stu3/schemas/endpoints/a021-create-referral-request-and-send-for-triage.yaml @@ -39,6 +39,11 @@ description: | You can calculate the date when the patient will need to be contacted (by the triage service) using reference data from [[HYPERLINK_A004]]. + ## Known Issues + + 1. The Participant.type attribute is being mapped as a single type for this endpoint. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be an array. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information. + 2. The participant of an Appointment references a value set. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be a coding system. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information. + summary: Create referral and send for triage (A021, FHIR STU3) [deprecated] operationId: a021-create-referral-request-and-send-for-triage tags: diff --git a/specification/components/stu3/schemas/endpoints/a022-cancel-appointment-action-later.yaml b/specification/components/stu3/schemas/endpoints/a022-cancel-appointment-action-later.yaml index 78fbb778a..4b1d8449f 100644 --- a/specification/components/stu3/schemas/endpoints/a022-cancel-appointment-action-later.yaml +++ b/specification/components/stu3/schemas/endpoints/a022-cancel-appointment-action-later.yaml @@ -51,6 +51,11 @@ description: | The availability status of attachments associated with a referral are returned via this endpoint as a eRS-AvailabilityStatus-1 code. - Further details on attachment availability status and eRS-AvailabilityStatus-1 codes can be found in the [[HYPERLINK_A005]] and [[HYPERLINK_A042]] specifications. + ## Known Issues + + 1. The Participant.type attribute is being mapped as a single type for this endpoint. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be an array. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information. + 2. The participant of an Appointment references a value set. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be a coding system. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information. + summary: Cancel appointment, action later (A022, FHIR STU3) operationId: a022-cancel-appointment-action-later tags: diff --git a/specification/components/stu3/schemas/endpoints/a024-retrieve-advice-and-guidance.yaml b/specification/components/stu3/schemas/endpoints/a024-retrieve-advice-and-guidance.yaml index ae936ca49..248a9b3fb 100644 --- a/specification/components/stu3/schemas/endpoints/a024-retrieve-advice-and-guidance.yaml +++ b/specification/components/stu3/schemas/endpoints/a024-retrieve-advice-and-guidance.yaml @@ -8,6 +8,10 @@ description: | 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]]. + An advice request can include file attachments and structured clinical data added via an integrated primary care system. These must be retrieved via [[HYPERLINK_A042]] and [[HYPERLINK_A043]], respectively. + + [Read](https://digital.nhs.uk/developer/guides-and-documentation/building-healthcare-software/referrals-and-bookings/e-referral-service/retrieve-clinical-referral-information-as-a-service-provider) our building healthcare software guide for detailed information. + ## Supported security patterns - Application-restricted access, unattended access - Healthcare worker, user-restricted access diff --git a/specification/components/stu3/schemas/endpoints/a025-retrieve-advice-and-guidance-conversation.yaml b/specification/components/stu3/schemas/endpoints/a025-retrieve-advice-and-guidance-conversation.yaml index e27d504e5..1db0c6b60 100644 --- a/specification/components/stu3/schemas/endpoints/a025-retrieve-advice-and-guidance-conversation.yaml +++ b/specification/components/stu3/schemas/endpoints/a025-retrieve-advice-and-guidance-conversation.yaml @@ -7,6 +7,10 @@ description: | A 'conversation' takes the form of the messages between a referrer (seeking advice) and a provider or specialist. Messages can include attachments. + A conversation takes the form of messages between a referrer (seeking advice) and a provider or specialist. Messages can include file attachments. These must be retrieved via [[HYPERLINK_A042]] + + [Read](https://digital.nhs.uk/developer/guides-and-documentation/building-healthcare-software/referrals-and-bookings/e-referral-service/retrieve-clinical-referral-information-as-a-service-provider) our building healthcare software guide for detailed information. + ## Supported security patterns - Application-restricted access, unattended access - Healthcare worker, user-restricted access diff --git a/specification/components/stu3/schemas/endpoints/a027-convert-a&g-to-referral.yaml b/specification/components/stu3/schemas/endpoints/a027-convert-a&g-to-referral.yaml index b481007b0..e075c559b 100644 --- a/specification/components/stu3/schemas/endpoints/a027-convert-a&g-to-referral.yaml +++ b/specification/components/stu3/schemas/endpoints/a027-convert-a&g-to-referral.yaml @@ -61,6 +61,11 @@ description: | 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. + + ## Known Issues + + 1. The Participant.type attribute is being mapped as a single type for this endpoint. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be an array. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information. + 2. The participant of an Appointment references a value set. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be a coding system. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information. summary: Convert advice and guidance request to referral (A027, FHIR STU3) operationId: a027-convert-a&g-to-referral diff --git a/specification/components/stu3/schemas/endpoints/a028-record-triage-outcome.yaml b/specification/components/stu3/schemas/endpoints/a028-record-triage-outcome.yaml index 757eaf7b5..dc5ada426 100644 --- a/specification/components/stu3/schemas/endpoints/a028-record-triage-outcome.yaml +++ b/specification/components/stu3/schemas/endpoints/a028-record-triage-outcome.yaml @@ -74,7 +74,12 @@ description: | - In order to retrieve an attachment using the [[HYPERLINK_A042]] (or deprecated [[HYPERLINK_A006]]) endpoint, the attachment must be available for download. The availability status of attachments associated with a referral are returned via this endpoint as a eRS-AvailabilityStatus-1 code. - Further details on attachment availability status and eRS-AvailabilityStatus-1 codes can be found in the [[HYPERLINK_A005]] and [[HYPERLINK_A042]] specifications. - + + ## Known Issues + + 1. The Participant.type attribute is being mapped as a single type for this endpoint. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be an array. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information. + 2. The participant of an Appointment references a value set. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be a coding system. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information. + summary: Record triage outcome (A028, FHIR STU3) operationId: a028-record-triage-outcome tags: diff --git a/specification/components/stu3/schemas/endpoints/a029-available-actions-for-user-list.yaml b/specification/components/stu3/schemas/endpoints/a029-available-actions-for-user-list.yaml index 6915238c8..69aa06daa 100644 --- a/specification/components/stu3/schemas/endpoints/a029-available-actions-for-user-list.yaml +++ b/specification/components/stu3/schemas/endpoints/a029-available-actions-for-user-list.yaml @@ -42,6 +42,20 @@ description: | So that I can review my options, and do not try to persist a prohibited action + ## Important information about using this endpoint + + This endpoint can be used to check permitted actions on a referral. Only a select number of results will be returned for which a corresponding action can be performed via the API. Not all actions are currently supported. + + As a referrer, the actions returned can include: + - Cancel Directly Booked Appointment + - Cancel Referral + - Create Appointment + - Change Shortlist + - Change Shortlist and Send for Triage + + As a service provider, the only action returned will be: + - Record Review Outcome + ## Related endpoints To retrieve pertinent details relating to a referral: diff --git a/specification/components/stu3/schemas/endpoints/a031-change-shortlist.yaml b/specification/components/stu3/schemas/endpoints/a031-change-shortlist.yaml index 01ba59677..9f990831e 100644 --- a/specification/components/stu3/schemas/endpoints/a031-change-shortlist.yaml +++ b/specification/components/stu3/schemas/endpoints/a031-change-shortlist.yaml @@ -12,6 +12,8 @@ description: | The maximum amount of services allowed on a given shortlist is 20. The act of changing a shortlist alone will not result in a referral being sent/booked to any of the shortlisted services (even if only one service is shortlisted). + A shortlist of a single triage service should be avoided as this relies on the patient to progress the referral, potentially leading to a delay to care. Especially if the referral priority is 2WW or Urgent. + Use [[HYPERLINK_A016]] if there is a need to support the sending/booking of the referral into a shortlisted service. 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. @@ -57,6 +59,12 @@ description: | 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. + + ## Known Issues + + 1. The Participant.type attribute is being mapped as a single type for this endpoint. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be an array. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information. + 2. The participant of an Appointment references a value set. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be a coding system. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information. + summary: Change shortlist (A031, FHIR STU3) operationId: a031-change-shortlist tags: diff --git a/specification/components/stu3/schemas/endpoints/a032-change-shortlist-and-send-for-triage.yaml b/specification/components/stu3/schemas/endpoints/a032-change-shortlist-and-send-for-triage.yaml index c45b485f4..7c944950a 100644 --- a/specification/components/stu3/schemas/endpoints/a032-change-shortlist-and-send-for-triage.yaml +++ b/specification/components/stu3/schemas/endpoints/a032-change-shortlist-and-send-for-triage.yaml @@ -52,6 +52,11 @@ description: | You can calculate the date when the patient will need to be contacted (by the triage service) using reference data from [[HYPERLINK_A004]]. + ## Known Issues + + 1. The Participant.type attribute is being mapped as a single type for this endpoint. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be an array. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information. + 2. The participant of an Appointment references a value set. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be a coding system. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information. + summary: Change shortlist and send for triage (A032, FHIR STU3) [deprecated] operationId: a032-change-shortlist-and-send-for-triage tags: diff --git a/specification/components/stu3/schemas/endpoints/a034-update-appointment.yaml b/specification/components/stu3/schemas/endpoints/a034-update-appointment.yaml index 9f2eb852f..20a63c269 100644 --- a/specification/components/stu3/schemas/endpoints/a034-update-appointment.yaml +++ b/specification/components/stu3/schemas/endpoints/a034-update-appointment.yaml @@ -48,6 +48,11 @@ description: | 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]]. + + ## Known Issues + + 1. The Participant.type attribute is being mapped as a single type for this endpoint. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be an array. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information. + 2. The participant of an Appointment references a value set. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be a coding system. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information. summary: Update appointment (A034, FHIR STU3) operationId: a034-update-appointment diff --git a/specification/components/stu3/schemas/endpoints/a036-cancel-referral.yaml b/specification/components/stu3/schemas/endpoints/a036-cancel-referral.yaml index 7f432a961..1c6d8395d 100644 --- a/specification/components/stu3/schemas/endpoints/a036-cancel-referral.yaml +++ b/specification/components/stu3/schemas/endpoints/a036-cancel-referral.yaml @@ -80,6 +80,11 @@ description: | You can use [[HYPERLINK_A038]] to view the current appointment (where applicable). + ## Known Issues + + 1. The Participant.type attribute is being mapped as a single type for this endpoint. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be an array. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information. + 2. The participant of an Appointment references a value set. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be a coding system. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information. + ## Sandbox test scenarios You can test the following scenarios in our sandbox environment: diff --git a/specification/components/stu3/schemas/endpoints/a038-retrieve-appointment.yaml b/specification/components/stu3/schemas/endpoints/a038-retrieve-appointment.yaml index 99eb72b6a..fbf20cf51 100644 --- a/specification/components/stu3/schemas/endpoints/a038-retrieve-appointment.yaml +++ b/specification/components/stu3/schemas/endpoints/a038-retrieve-appointment.yaml @@ -64,6 +64,11 @@ description: | If an appointment is cancelled as part of [[HYPERLINK_A036]], an appointment will be returned as part of a successful response. + ## Known Issues + + 1. The Participant.type attribute is being mapped as a single type for this endpoint. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be an array. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information. + 2. The participant of an Appointment references a value set. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be a coding system. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information. + ## Sandbox test scenarios You can test the following scenarios in our sandbox environment diff --git a/specification/e-referrals-service-api.yaml b/specification/e-referrals-service-api.yaml index 739d9ca83..1772c3655 100644 --- a/specification/e-referrals-service-api.yaml +++ b/specification/e-referrals-service-api.yaml @@ -17,6 +17,8 @@ info: ## 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 @@ -52,6 +54,23 @@ info: - 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 @@ -59,7 +78,7 @@ info: | Access mode | Authentication via | Functions | Availability | | ----------------------------- | -------------------------- | ----------------------- | ------------------------------- | - | Application-restricted,
unattended access | [[HYPERLINK_SIGNED_JWT]] | | [[HYPERLINK_PRODUCTION]] | + | 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 @@ -83,27 +102,12 @@ info: 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: + To use this API you must: - - 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. - -
-
-
- - - -
-
-

For a non-technical overview of how to build software that deals with referrals and bookings, see Building healthcare software - referrals and bookings.

-
-
+ - 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 @@ -112,32 +116,16 @@ info: ## API status and roadmap - ### Application-restricted, unattended access + ### This API has two access modes: + - Application-restricted, unattended access + - Healthcare worker, user-restricted access - This access mode is [[HYPERLINK_PRODUCTION]]. We are onboarding Partners to use it. - - Please note that it can only be used: - - - when authenticating a human user is not possible - - by 'Provider Organisations' or 'Referrer Organisations' - - for accessing endpoints - - [[HYPERLINK_A004]] - - [[HYPERLINK_A005]] - - [[HYPERLINK_A006]] - - [[HYPERLINK_A007]] - - [[HYPERLINK_A008]] - - [[HYPERLINK_A013]] - - [[HYPERLINK_A024]] - - [[HYPERLINK_A025]] - - [[HYPERLINK_A028]] - - [[HYPERLINK_A029]] - - [[HYPERLINK_A033]] - - [[HYPERLINK_A035]] - - [[HYPERLINK_A037]] - - [[HYPERLINK_A043]] - - For more information, please see [[HYPERLINK_NETWORK_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]]. We are onboarding Partners to use it. @@ -148,7 +136,9 @@ info: ### 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). + 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. @@ -180,12 +170,18 @@ info: ## 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) @@ -206,6 +202,10 @@ info: 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. @@ -251,27 +251,9 @@ info: ## Onboarding - You need to get your software approved by us before it can go live. We call this process 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. - 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. + 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: