Search loading...

API Hub

Explore and Make use of Nationally Defined Messaging APIs

 

A027: Convert Advice Request to Referral

Status: Live

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

Method URL Authentication
POST {Base URL}/STU3/v1/ReferralRequest/$ers.createFromCommunicationRequestActionLater Session Token (Details)
  • {Base URL} (Dev1) = https://api.dev1.ers.ncrs.nhs.uk/ers-api

Operation Definition

eRS-sendCommuncationToRequest-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 CommuncationRequest to ensure they are converting with the most recent version of the CommuncationRequest.
  • 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-CreateFromCommuncationrRequestActionLater-Request-Parameters-1

Request Operation: Parameters

Name Cardinality Type Description
createFrom 1..1 Reference Identifies the Advice and Guidance Request a Professional wants to update and the version last seen by that Professional. Only the most recent version can be converted.

Must of value and format createFrom=CommunicationRequest/{ubrn}/_history/
guidance 1..1 String Response back to the Referrer on the Advice and Guidance Request (Max 2000 char)
guidanceAttachmentFile 0..* Resource Document(s) sent back to the Referrer on the Advice and Guidance Request
Must be eRS-DocumentReference-1
reviewComments 1..1 string Comment the Professional (admin) staff will see on the created Referral (Max 2000 char)
reviewAttachmentFile 0..* Resource Document(s) to associate with the created Referral
Must be eRS-DocumentReference-1
newReferralPriority 1..1 Coding Priority to attribute to the created Referral
Must be from ValueSet eRS-Priority-1

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.

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 CommuncationRequest 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..

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:

OutcomeKey Description Suggested Diagnostic
INAPPROPRIATE_VALUE reviewAttachmentFile
type is not ‘PROVIDER’
parameter[x]/resource/type/coding[0] must be ‘PROVIDER’ for Binary/70000-70001
INAPPROPRIATE_VALUE Guidance Response Clinical Attachments type is not ‘GUIDANCE_RESPONSE’ parameter[x]/resource/type/coding[0] must be ‘GUIDANCE_RESPONSE’ for Binary/70000-70001
NO_SUCH_REQUEST Request of type Advice and Guidance Request with this UBRN does not exist HTTP response only (404)
VERSION_CONFLICT The UBRN version number is not current HTTP response only (409)
DUPLICATE_FILENAME The File Name of one of the files to be associated with the Request exactly matches (including extension) that of a Provider Clinical Attachment, Advice Request Clinical Attachment, Guidance Response Clinical Attachment or Referrer Clinical Attachment ‘Filename’ matches the name of a file already associated with the request
NO_RELATIONSHIP The person authenticated does not have a relationship with the Request so cannot view it No legitimate relationship with referral UBRN
PATIENT_ERROR   An error occurred while retrieving the requested patient (NHS Number). Do not attempt again
INVALID_REQUEST_STATE An Advice and Guidance Request must be in progress An Advice and Guidance Request must be in progress
INVALID_REQUEST_STATE A Referrer must give permission to create a Referral from an Advice and Guidance Request. This Referral is not permitted to be created into a Referral. This Advice and Guidance Request is not permitted to be converted to a Referral

All content is available under the Open Government Licence v3.0, except where otherwise stated