Status:

This endpoint has been deprecated, meaning you should not use it for new integrations.

Instead, please use our newer e-RS FHIR API solution which is documented here: https://digital.nhs.uk/developer/api-catalogue/e-referral-service-fhir

Description

This functionality allows a Service Provider to reference an existing Advice and Guidance Request, and if validation passes, allows that Service Provider to create a Referral from that Advice and Guidance Request. As part of the Referral creation, notes, and optionally attachments, for other staff (e.g. Service Provider Clinician Admin staff) are recorded so that the person who picks up the Referral next has some context. The created referral is the responsibility of the Service which created the Referral, until they decide what to do with it (e.g. Book / Defer / Send to another service, cancel etc).

The Advice and Guidance Request is “closed” and sent back to the Referrer as a result of this action.

Request Operation: URL

• {Base URL} (Dev1) = https://api.dev1.ers.ncrs.nhs.uk/ers-api

Operation Definition

eRS-SendCommunicationToRequester-Operation-1

Input

eRS-SendCommunicationToRequester-Request-Parameters-1

Output

eRS-SendCommunicationToRequester-Response-Parameters-1

Prerequisite Conditions

• An Advice and Guidance request must exist and not be “closed”, I.e. a conversation between the Provider and Referrer must be on-going.
• The caller should have reviewed the most recent Advice and Guidance Request. This can be accessed via two endpoints
  • Advice and Guidance Request Summary
  • Advice and Guidance Conversation

Compliance Requirements

• This feature checks the version of the CommunicationRequest last viewed (via a parameter denoting the CommunicationRequest version: createFrom=CommunicationRequest/{ubrn}/_history/). However, it does NOT check that the caller has seen the most recent Communication(s). Therefore it follows that:
• Supplier systems MUST get the most recent Communication(s) to ensure that they are converting with the most recent Clinical Information to hand.
• Supplier systems MUST get the most recent CommunicationRequest to ensure they are converting with the most recent version of the CommunicationRequest.
• Currently ALL Advice and Guidance Request attachments are included under SupportingInfo under the ReferralRequest meaning, if you can view the ReferralRequest, you can view the Advice and Guidance Request Clinical Attachments (except any “structured information”). Since this feature adds reference to the Advice and Guidance Request in the Pathway, arguably, there is no need to include these attachments on the ReferralRequest anymore. There is no current business need to make a distinction, and it might be a breaking change to do so. Making this a future Business need might make LR easier to manage. Currently you can only “fetch” the attachments if you have LR with the attachment anyways, so we are somewhat protected.

INPUT

eRS-CreateFromCommunicationRequestActionLater-Request-Parameters-1

Request Operation: Parameters

Example Request Header

XAPI_ASID:999000000045
HTTP_X_SESSION_KEY:pro-api-session:e96357b1-298d-4159-ac58-a8953c3262c6"
Content-Type:application/fhir+json

Example Request Body

Note: These examples may contain environment specific URLs and test data, these should be replaced with appropriate values for your implementation.

• A027_Request.json

OUTPUT

Response: Success

If successful we return as per A005: Retrieve Referral Request but it’s worth translating some of what is returned into business language.

1. Immediately after creating a Referral from an Advice and Guidance Request
   • The FHIR “status” element will be “proposed”
   • The FHIR “reason.coding.system.value” will be PROVIDER_CONVERTED_ADVICE_AND_GUIDANCE_ADMIN_TO_REFER. This is so that the person picking up the Referral understands what happened to it i.e. the Provider has, from an Advice and Guidance Request, created a Referral, accepting the responsibility to refer it
   • The FHIR “comment” element will be the value submitted on the reviewComments parameter so that the person picking up the Referral can see the comments added
   • The FHIR “participant[0].actor.identifier.value” will be the Service which created the Referral
2. After a newly created Referral converted from an Advice and Guidance Request is processed (e.g. booked, sent for triage etc), the values detailed in (1) may no longer be present due to state changes, but you can still tell if there was an Advice and Guidance Request in the Pathway due to the following:
   • The FHIR “supportingInfo[CommunicationRequest]” references the CommunicationRequest from which the Referral was created. This is only “fetchable” if you are allowed to view the Advice and Guidance Request and can be fetched from View Advice and Guidance Summary endpoint
   • The FHIR “supportingInfo[DocumentReference]” references
   • Any attachments on the Referral (as per existing)
   • Now includes all Advice and Guidance attachments
   • It will also contain any attachment(s) uploaded as part of the Referral creation (via reviewAttachmentFile )
   • AND may (unless removed via the Pro App) contain a reference to an automatically generated PDF
   • The automatically generated PDF is a copy of the Advice and Guidance Conversation that eRS creates when the Referral is created from the Advice and Guidance Request
   • eRS-AttachmentType-1 value tells a Supplier what type of attachment is referenced. In other words, if it was uploaded and associated to the Request as part of Advice and Guidance, by a Referrer, Provider (etc)
   • The Structured Clinical Information is still only accessible via A007: Retrieve Clinical Information

Example Response Body

Note: These examples may contain environment specific URLs and test data, these should be replaced with appropriate values for your implementation..

• A027_Response.json

Response: Failure

If an error occurs, the relating HTTP status code will be returned in the header.

Where status code 422 (Unprocessable Entity) is returned then an eRS-OperationOutcome-1 will be included in the body, as detailed below: