e-Referral Service - FHIR API

Access the e-Referral Service (e-RS) - the national service for creating and managing paperless referrals in primary and secondary care.

Overview

Use this API to create paperless referrals from primary to secondary care with the e-Referral Service (e-RS).

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 currently use this API to:

get patient details – instead, use the Personal Demographic Service (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 access mode is in production and stable. This access mechanism is documented on the older 'API Hub' documentation portal. Using this authentication mechanism allows full use of all e-RS endpoints. This access mode requires the creation of a professional session and selection of a role in order to authenticate.

e-RS has recently released a new solution which allows authentication over the internet, using NHS Care Identity Service 2 (CIS2). The documentation you are currently reading must be used when you wish to authenticate over the internet. Not every endpoint is available yet: we have only released the endpoints you see listed below in the Endpoints section below. This access mode requires the use of A030 - Retrieve e-RS business functions endpoint to authenticate. Please note that this is currently in beta, meaning we might make breaking changes, but only if we cannot avoid it.

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.

To use this API:

you must have justification for doing so
you must register with the e-RS Partners Service
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
you must assure 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

See the onboarding section below for more information.

Related APIs

The following API also gives access to the e-referrals service (e-RS) data:

e-RS FHIR v2 API - this is deprecated and we plan to retire it. Do not integrate with this API

API status and roadmap

The e-RS FHIR STU3 API is stable, when accessed via HSCN network with a smartcard.

The e-RS FHIR STU3 API is in beta when accessed via the internet using CIS2. There is also one FHIR R4 endpoint, A030 - Retrieve e-RS business functions endpoint, as part of our beta. We plan to move more endpoints into the FHIR R4 standard in the future, as part of our roadmap.

For the current e-RS roadmap see the future of the NHS e-referral service.

Technology

This API is primarily RESTful and based on 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).

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.

Security and authorisation

For users with access to the Health and Social Care Network (HSCN), access is user-restricted, meaning an end user must be present, authenticated and authorised.

The end user must also be:

a healthcare worker
strongly authenticated using an NHS smartcard

For more details see Authentication and Authorisation.

If you wish to authenticate users without smartcards, access is still user-restricted but uses the following security patterns instead:

Environments and testing

Environment	Base URL
Sandbox	`https://sandbox.api.service.nhs.uk/referrals`
Integration test	`https://int.api.service.nhs.uk/referrals`
Production	Not yet available

Sandbox testing

Our sandbox environment:

is for early developer 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 environment:

is for formal integration testing
is where we will 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 with this API. We call this onboarding. The onboarding process can sometimes be quite long, so it’s worth planning well ahead.

To onboard for this API, follow the Supplier Conformance Assessment List (SCAL) process.

When following the SCAL process, note that:

In step 1: to confirm your use case for this API, you need to register with nhserspartners@nhs.net using Partner Registration and discuss your use case with us.

In step 2: when requesting the SCAL, please liaise with functional.assurance@nhs.net directly, they are responsible for solutions assurance of e-RS APIs.

In step 8: to organise witness testing of your solution, please liaise with functional.assurance@nhs.net directly.

In step 11: when submitting your SCAL for review, please liaise with functional.assurance@nhs.net directly.

In step 12: to obtain a Connection Agreement, please liaise with interop.mgmt@nhs.net. You will need to provide your approved SCAL including an embedded Technical Conformance Certificate.

In step 13: to obtain the End User Organisation Acceptable Use Policy, please liaise with interop.mgmt@nhs.net.

In step 14: to request production access, you need to liaise with both interop.mgmt@nhs.net (for all methods of access) and also api.management@nhs.net if your users are not on HSCN, using smartcards.

Endpoints

A004 - Retrieve reference data

get

/STU3/v1/CodeSystem/{codeSystemType}

Overview

Use this endpoint to retrieve a list of reference data codes along with the user-friendly display values used in the e-RS Professional Application.

Pre-requisites

In order to use this endpoint you must be an authenticated e-RS user and use one of the following e-RS roles:

REFERRING_CLINICIAN
REFERRING_CLINICIAN_ADMIN
SERVICE_PROVIDER_CLINICIAN

Use case

As an authenticated user

I need to retrieve e-RS reference data

So I can use it with other endpoints or display the reference data in a user-friendly format to my users.

Related endpoints

Reference data may be needed for other endpoints, for example when including Specialty and Clinic Type reference data to:

find services that meet the referral needs of a patient using A010 - Patient service search, and
create a referral using A011 - Create referral or A021 - Create referral and send for triage

You may also wish to present the user-friendly names for the reference data, for example when viewing the referral using A005 - Retrieve referral request.

Sandbox test scenarios

You can test the following scenarios in our sandbox environment

Scenario	Request	Response
Retrieve speciality reference data	`codeSystemType`=`SPECIALTY`	Specialty details
Retrieve clinic type reference data	`codeSystemType`=`CLINIC-TYPE`	Clinic type details
Retrieve appointment cancellation reason reference data	`codeSystemType`=`APPOINTMENT-CANCELLATION-REASON`	Appointment reason type details

Request

Path parameters

Name Description

Name	Description
`codeSystemType`	String The requested code system Allowed values: SPECIALTY, APPOINTMENT-CANCELLATION-REASON, CLINIC-TYPE Example: SPECIALTY Required

codeSystemType

String

The requested code system

Allowed values: SPECIALTY, APPOINTMENT-CANCELLATION-REASON, CLINIC-TYPE

Example: SPECIALTY

Required

Headers

Name	Description
`Authorization`	String (^Bearer\ [[:ascii:]]+$) An OAuth 2.0 bearer token. Required in all environments except sandbox. Example: Bearer g1112R_ccQ1Ebbb4gtHBP1aaaNM Required
`nhsd-ers-ods-code`	String The ODS code of the caller's Organisation Example: R69 Required
`nhsd-ers-business-function`	String The e-RS Business Function of the caller Allowed values: REFERRING_CLINICIAN, REFERRING_CLINICIAN_ADMIN, REFERRING_ADMIN, BMS_HCP_PROXY, BMS_ADMIN, COMMISSIONER, SERVICE_DEFINER, ERS_ADMIN, SERVICE_PROVIDER_CLINICIAN, SERVICE_PROVIDER_ADMIN, INFORMATION_ANALYST, BOOKING_MANAGER, ADDITIONAL_REQUIREMENTS_MANAGER, REFERRER_RIGHTS_MANAGER Example: REFERRING_CLINICIAN Required
`X-Correlation-Id`	String Arbitrary string value provided by API Consumer Tends to be unique, but does not have to be Returned, unchanged, in the response Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA

Response

HTTP status: 200

e-RS Reference Data

Headers

Name Description

Name	Description
`x-correlation-id`	String The X-Correlation-ID from the request header, if supplied, mirrored back. Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA
`x-request-id`	String The e-RS transaction id Example: 58621d65-d5ad-4c3a-959f-0438e355990e-1

x-correlation-id

String

The X-Correlation-ID from the request header, if supplied, mirrored back.

Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA

x-request-id

String

The e-RS transaction id

Example: 58621d65-d5ad-4c3a-959f-0438e355990e-1

Body

Content type: application/fhir+json

Examples

Specialty Reference Data

This is example data only and should not be taken as the real reference data. Specialty data may have 'effectiveTo' dates in the past

{
  "id" : "SPECIALTY",
  "meta" : {
    "profile" : [ "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-Specialty-CodeSystem-1" ]
  },
  "resourceType" : "CodeSystem",
  "url" : "_baseUrl_/STU3/v1/CodeSystem/SPECIALTY",
  "name" : "e-RS Specialty",
  "status" : "active",
  "date" : "2021-05-26T13:47:38.185000+00:00",
  "publisher" : "e-Referral Service",
  "description" : "e-RS Specialty",
  "copyright" : "Copyright © 2016 HL7 UK",
  "content" : "complete",
  "property" : [ {
    "code" : "effectiveFrom",
    "uri" : "https://fhir.nhs.uk/STU3/CodeSystem/eRS-Concept-Properties-1#effectiveFrom",
    "type" : "dateTime"
  }, {
    "code" : "effectiveTo",
    "uri" : "https://fhir.nhs.uk/STU3/CodeSystem/eRS-Concept-Properties-1#effectiveTo",
    "type" : "dateTime"
  } ],
  "concept" : [ {
    "extension" : [ {
      "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-EffectivefromDate-1",
      "valueDate" : "2004-06-01"
    }, {
      "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-EffectivetoDate-1",
      "valueDate" : "2008-05-09"
    } ],
    "code" : "ADULT_MENTAL_ILLNESS",
    "display" : "Adult Mental Illness",
    "property" : [ {
      "code" : "effectiveFrom",
      "valueDateTime" : "2004-06-01T00:00:00+00:00"
    }, {
      "code" : "effectiveTo",
      "valueDateTime" : "2008-05-09T00:00:00+00:00"
    } ]
  }, {
    "extension" : [ {
      "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-EffectivefromDate-1",
      "valueDate" : "2004-06-01"
    } ],
    "code" : "ALLERGY",
    "display" : "Allergy",
    "property" : [ {
      "code" : "effectiveFrom",
      "valueDateTime" : "2004-06-01T00:00:00+00:00"
    } ]
  }, {
    "extension" : [ {
      "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-EffectivefromDate-1",
      "valueDate" : "2004-06-01"
    }, {
      "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-EffectivetoDate-1",
      "valueDate" : "2008-05-09"
    } ],
    "code" : "AUDIOLOGICAL_MEDICINE",
    "display" : "Audiological Medicine",
    "property" : [ {
      "code" : "effectiveFrom",
      "valueDateTime" : "2004-06-01T00:00:00+00:00"
    }, {
      "code" : "effectiveTo",
      "valueDateTime" : "2008-05-09T00:00:00+00:00"
    } ]
  }, {
    "extension" : [ {
      "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-EffectivefromDate-1",
      "valueDate" : "2004-06-01"
    }, {
      "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-EffectivetoDate-1",
      "valueDate" : "2008-05-09"
    } ],
    "code" : "BONE_AND_MARROW_TRANSPLANTATION",
    "display" : "Bone and Marrow Transplantation",
    "property" : [ {
      "code" : "effectiveFrom",
      "valueDateTime" : "2004-06-01T00:00:00+00:00"
    }, {
      "code" : "effectiveTo",
      "valueDateTime" : "2008-05-09T00:00:00+00:00"
    } ]
  } ]
}

Clinic Type Reference Data

This is example data only and should not be taken as the real reference data.

{
  "id" : "CLINIC-TYPE",
  "meta" : {
    "profile" : [ "http://hl7.org/fhir/StructureDefinition/shareablecodesystem" ]
  },
  "resourceType" : "CodeSystem",
  "url" : "_baseUrl_/STU3/v1/CodeSystem/CLINIC-TYPE",
  "name" : "e-RS Clinic Type",
  "status" : "active",
  "date" : "2021-05-26T13:49:36.514000+00:00",
  "publisher" : "e-Referral Service",
  "description" : "e-RS Clinic Type",
  "copyright" : "Copyright © 2016 HL7 UK",
  "content" : "complete",
  "property" : [ {
    "code" : "effectiveFrom",
    "uri" : "https://fhir.nhs.uk/STU3/CodeSystem/eRS-Concept-Properties-1#effectiveFrom",
    "type" : "dateTime"
  }, {
    "code" : "effectiveTo",
    "uri" : "https://fhir.nhs.uk/STU3/CodeSystem/eRS-Concept-Properties-1#effectiveTo",
    "type" : "dateTime"
  }, {
    "code" : "specialty",
    "uri" : "https://fhir.nhs.uk/STU3/CodeSystem/eRS-Concept-Properties-1#specialty",
    "type" : "Coding"
  } ],
  "concept" : [ {
    "code" : "GENERAL_ADULT_MENTAL_ILLNESS",
    "display" : "General Adult Mental Illness",
    "property" : [ {
      "code" : "effectiveFrom",
      "valueDateTime" : "2004-06-01T00:00:00+00:00"
    }, {
      "code" : "effectiveTo",
      "valueDateTime" : "2008-05-09T00:00:00+00:00"
    }, {
      "code" : "specialty",
      "valueCoding" : {
        "system" : "_baseUrl_/STU3/v1/CodeSystem/SPECIALTY",
        "code" : "ADULT_MENTAL_ILLNESS"
      }
    } ]
  }, {
    "code" : "ALLERGY_1",
    "display" : "Allergy",
    "property" : [ {
      "code" : "effectiveFrom",
      "valueDateTime" : "2004-06-01T00:00:00+00:00"
    }, {
      "code" : "specialty",
      "valueCoding" : {
        "system" : "_baseUrl_/STU3/v1/CodeSystem/SPECIALTY",
        "code" : "ALLERGY"
      }
    } ]
  }, {
    "code" : "FOOD_AND_DRUG_ALLERGY",
    "display" : "Food and Drug Allergy",
    "property" : [ {
      "code" : "effectiveFrom",
      "valueDateTime" : "2004-06-01T00:00:00+00:00"
    }, {
      "code" : "effectiveTo",
      "valueDateTime" : "2009-03-14T00:00:00+00:00"
    }, {
      "code" : "specialty",
      "valueCoding" : {
        "system" : "_baseUrl_/STU3/v1/CodeSystem/SPECIALTY",
        "code" : "ALLERGY"
      }
    } ]
  }, {
    "code" : "GENERAL_PAEDIATRIC_AUDIOLOGICAL_MEDICINE",
    "display" : "General Paediatric Audiological Medicine",
    "property" : [ {
      "code" : "effectiveFrom",
      "valueDateTime" : "2004-06-01T00:00:00+00:00"
    }, {
      "code" : "effectiveTo",
      "valueDateTime" : "2007-11-16T00:00:00+00:00"
    }, {
      "code" : "specialty",
      "valueCoding" : {
        "system" : "_baseUrl_/STU3/v1/CodeSystem/SPECIALTY",
        "code" : "AUDIOLOGICAL_MEDICINE"
      }
    } ]
  }, {
    "code" : "GENERAL_ADULT_AUDIOLOGICAL_MEDICINE",
    "display" : "General Adult Audiological Medicine",
    "property" : [ {
      "code" : "effectiveFrom",
      "valueDateTime" : "2004-06-01T00:00:00+00:00"
    }, {
      "code" : "effectiveTo",
      "valueDateTime" : "2008-05-09T00:00:00+00:00"
    }, {
      "code" : "specialty",
      "valueCoding" : {
        "system" : "_baseUrl_/STU3/v1/CodeSystem/SPECIALTY",
        "code" : "AUDIOLOGICAL_MEDICINE"
      }
    } ]
  }, {
    "code" : "GENERAL_AUDIOLOGICAL_MEDICINE",
    "display" : "General Audiological Medicine",
    "property" : [ {
      "code" : "effectiveFrom",
      "valueDateTime" : "2004-06-01T00:00:00+00:00"
    }, {
      "code" : "effectiveTo",
      "valueDateTime" : "2008-05-09T00:00:00+00:00"
    }, {
      "code" : "specialty",
      "valueCoding" : {
        "system" : "_baseUrl_/STU3/v1/CodeSystem/SPECIALTY",
        "code" : "AUDIOLOGICAL_MEDICINE"
      }
    } ]
  }, {
    "code" : "GENERAL_BONE_AND_MARROW_TRANSPLANTATION",
    "display" : "General Bone and Marrow Transplantation",
    "property" : [ {
      "code" : "effectiveFrom",
      "valueDateTime" : "2004-06-01T00:00:00+00:00"
    }, {
      "code" : "effectiveTo",
      "valueDateTime" : "2008-05-09T00:00:00+00:00"
    }, {
      "code" : "specialty",
      "valueCoding" : {
        "system" : "_baseUrl_/STU3/v1/CodeSystem/SPECIALTY",
        "code" : "BONE_AND_MARROW_TRANSPLANTATION"
      }
    } ]
  } ]
}

Appointment Reference Data

This is example data only and should not be taken as the real reference data.

{
  "id" : "APPOINTMENT-CANCELLATION-REASON",
  "meta" : {
    "profile" : [ "http://hl7.org/fhir/StructureDefinition/shareablecodesystem" ]
  },
  "resourceType" : "CodeSystem",
  "url" : "_baseUrl_/STU3/v1/CodeSystem/APPOINTMENT-CANCELLATION-REASON",
  "name" : "e-RS Appointment Cancellation Reason",
  "status" : "active",
  "date" : "2021-05-26T13:47:15.123000+00:00",
  "publisher" : "e-Referral Service",
  "description" : "e-RS Appointment Cancellation Reason",
  "copyright" : "Copyright © 2016 HL7 UK",
  "content" : "complete",
  "property" : [ {
    "code" : "effectiveFrom",
    "uri" : "https://fhir.nhs.uk/STU3/CodeSystem/eRS-Concept-Properties-1#effectiveFrom",
    "type" : "dateTime"
  }, {
    "code" : "effectiveTo",
    "uri" : "https://fhir.nhs.uk/STU3/CodeSystem/eRS-Concept-Properties-1#effectiveTo",
    "type" : "dateTime"
  }, {
    "code" : "appointmentBookingCancellationReasonType",
    "uri" : "https://fhir.nhs.uk/STU3/CodeSystem/eRS-Concept-Properties-1#appointmentBookingCancellationReasonType",
    "type" : "Coding"
  }, {
    "code" : "willCancelWholeRequest",
    "uri" : "https://fhir.nhs.uk/STU3/CodeSystem/eRS-Concept-Properties-1#willCancelWholeRequest",
    "type" : "boolean"
  }, {
    "code" : "commentIsMandatory",
    "uri" : "https://fhir.nhs.uk/STU3/CodeSystem/eRS-Concept-Properties-1#commentIsMandatory",
    "type" : "boolean"
  } ],
  "concept" : [ {
    "code" : "FURTHER_INFORMATION_REQUIRED",
    "display" : "Further Information Required",
    "property" : [ {
      "code" : "effectiveFrom",
      "valueDateTime" : "2004-06-01T00:00:00+00:00"
    }, {
      "code" : "appointmentBookingCancellationReasonType",
      "valueCoding" : {
        "system" : "https://fhir.nhs.uk/STU3/CodeSystem/eRS-AppointmentBookingCancellationReasonType-1",
        "code" : "PROVIDER_REJECT"
      }
    }, {
      "code" : "willCancelWholeRequest",
      "valueBoolean" : false
    }, {
      "code" : "commentIsMandatory",
      "valueBoolean" : false
    } ]
  }, {
    "code" : "OTHER",
    "display" : "Other reason",
    "property" : [ {
      "code" : "effectiveFrom",
      "valueDateTime" : "2004-06-01T00:00:00+00:00"
    }, {
      "code" : "appointmentBookingCancellationReasonType",
      "valueCoding" : {
        "system" : "https://fhir.nhs.uk/STU3/CodeSystem/eRS-AppointmentBookingCancellationReasonType-1",
        "code" : "PROVIDER_REJECT"
      }
    }, {
      "code" : "willCancelWholeRequest",
      "valueBoolean" : false
    }, {
      "code" : "commentIsMandatory",
      "valueBoolean" : false
    } ]
  }, {
    "code" : "OUTPATIENT_APPT_NOT_REQUIRED",
    "display" : "Outpatient appointment not required",
    "property" : [ {
      "code" : "effectiveFrom",
      "valueDateTime" : "2004-06-01T00:00:00+00:00"
    }, {
      "code" : "appointmentBookingCancellationReasonType",
      "valueCoding" : {
        "system" : "https://fhir.nhs.uk/STU3/CodeSystem/eRS-AppointmentBookingCancellationReasonType-1",
        "code" : "PROVIDER_REJECT"
      }
    }, {
      "code" : "willCancelWholeRequest",
      "valueBoolean" : false
    }, {
      "code" : "commentIsMandatory",
      "valueBoolean" : false
    } ]
  }, {
    "code" : "SERVICE_INAPPROPRIATE",
    "display" : "Inappropriate service",
    "property" : [ {
      "code" : "effectiveFrom",
      "valueDateTime" : "2004-06-01T00:00:00+00:00"
    }, {
      "code" : "appointmentBookingCancellationReasonType",
      "valueCoding" : {
        "system" : "https://fhir.nhs.uk/STU3/CodeSystem/eRS-AppointmentBookingCancellationReasonType-1",
        "code" : "PROVIDER_REJECT"
      }
    }, {
      "code" : "willCancelWholeRequest",
      "valueBoolean" : false
    }, {
      "code" : "commentIsMandatory",
      "valueBoolean" : false
    } ]
  }, {
    "code" : "SERVICE_PREREQUISITES_NOT_COMPLETE",
    "display" : "Pre-requisites for service not complete",
    "property" : [ {
      "code" : "effectiveFrom",
      "valueDateTime" : "2004-06-01T00:00:00+00:00"
    }, {
      "code" : "appointmentBookingCancellationReasonType",
      "valueCoding" : {
        "system" : "https://fhir.nhs.uk/STU3/CodeSystem/eRS-AppointmentBookingCancellationReasonType-1",
        "code" : "PROVIDER_REJECT"
      }
    }, {
      "code" : "willCancelWholeRequest",
      "valueBoolean" : false
    }, {
      "code" : "commentIsMandatory",
      "valueBoolean" : false
    } ]
  } ]
}

Schema

object

string

required

Identifier of this code system

Allowed values: SPECIALTY, APPOINTMENT-CANCELLATION-REASON, CLINIC-TYPE

Example: SPECIALTY

meta

object

required

profile

array

required

string

Allowed values: http://hl7.org/fhir/StructureDefinition/shareablecodesystem, https://fhir.nhs.uk/STU3/StructureDefinition/eRS-Specialty-CodeSystem-1

Example: https://fhir.nhs.uk/STU3/StructureDefinition/eRS-Specialty-CodeSystem-1

resourceType

string

required

Allowed values: CodeSystem

Example: CodeSystem

url

string

required

Example: _baseUrl_/STU3/v1/CodeSystem/SPECIALTY

name

string

required

Description of the code system

Allowed values: e-RS Appointment Cancellation Reason, e-RS Specialty, e-RS Clinic Type

Example: e-RS Specialty

status

string

required

Allowed values: active

Example: active

date

string date-time

required

publisher

string

Allowed values: e-Referral Service

Example: e-Referral Service

description

string

required

Example: e-RS Specialty

copyright

string

content

string

required

Allowed values: complete

Example: complete

property

array

required

Code System Properties

Some properties are only returned for certain code systems

Property	Code System
EffectiveFrom	All Code Systems
EffectiveTo	All Code Systems
Specialty	CLINIC-TYPE
AppointmentBookingCancellationReasonType	APPOINTMENT-CANCELLATION-REASON
WillCancelWholeRequest	APPOINTMENT-CANCELLATION-REASON
CommentIsMandatory	APPOINTMENT-CANCELLATION-REASON

anyOf

object

Effective from date

code

string

required

Allowed values: effectiveFrom

Example: effectiveFrom

uri

string

required

Allowed values: https://fhir.nhs.uk/STU3/CodeSystem/eRS-Concept-Properties-1#effectiveFrom

Example: https://fhir.nhs.uk/STU3/CodeSystem/eRS-Concept-Properties-1#effectiveFrom

type

string

required

Allowed values: dateTime

Example: dateTime

object

Effective to date

code

string

required

Allowed values: effectiveTo

Example: effectiveTo

uri

string

required

Allowed values: https://fhir.nhs.uk/STU3/CodeSystem/eRS-Concept-Properties-1#effectiveTo

Example: https://fhir.nhs.uk/STU3/CodeSystem/eRS-Concept-Properties-1#effectiveTo

type

string

required

Allowed values: dateTime

Example: dateTime

object

Specialty

This will only be returned when codeSystemType is CLINIC-TYPE

code

string

required

Allowed values: specialty

Example: specialty

uri

string

required

Allowed values: https://fhir.nhs.uk/STU3/CodeSystem/eRS-Concept-Properties-1#specialty

Example: https://fhir.nhs.uk/STU3/CodeSystem/eRS-Concept-Properties-1#specialty

type

string

required

Allowed values: Coding

Example: Coding

object

Appointment Booking Cancellation Reason Type

This will only be returned when codeSystemType is APPOINTMENT-CANCELLATION-REASON

code

string

required

Allowed values: appointmentBookingCancellationReasonType

Example: appointmentBookingCancellationReasonType

uri

string

required

Allowed values: https://fhir.nhs.uk/STU3/CodeSystem/eRS-Concept-Properties-1#appointmentBookingCancellationReasonType

Example: https://fhir.nhs.uk/STU3/CodeSystem/eRS-Concept-Properties-1#appointmentBookingCancellationReasonType

type

string

required

Allowed values: Coding

Example: Coding

object

Will Cancel Whole Request

This will only be returned when codeSystemType is APPOINTMENT-CANCELLATION-REASON

code

string

required

Allowed values: willCancelWholeRequest

Example: willCancelWholeRequest

uri

string

required

Allowed values: https://fhir.nhs.uk/STU3/CodeSystem/eRS-Concept-Properties-1#willCancelWholeRequest

Example: https://fhir.nhs.uk/STU3/CodeSystem/eRS-Concept-Properties-1#willCancelWholeRequest

type

string

required

Allowed values: boolean

Example: boolean

object

Comment Is Mandatory

This will only be returned when codeSystemType is APPOINTMENT-CANCELLATION-REASON

code

string

required

Allowed values: commentIsMandatory

Example: commentIsMandatory

uri

string

required

Allowed values: https://fhir.nhs.uk/STU3/CodeSystem/eRS-Concept-Properties-1#commentIsMandatory

Example: https://fhir.nhs.uk/STU3/CodeSystem/eRS-Concept-Properties-1#commentIsMandatory

type

string

required

Allowed values: boolean

Example: boolean

concept

array

required

Details of the code system

object

extension

array

nullable

Effective Date Range Extensions

anyOf

object

Extension-eRS-EffectivefromDate

Extension to supply the effective From Date, this will only be returned for specialty

url

string

required

Allowed values: https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-EffectivefromDate-1

Example: https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-EffectivefromDate-1

valueDate

string date

required

object

Extension-eRS-EffectivetoDate

Extension to supply the effective To Date, this will only be returned for specialty

url

string

required

Allowed values: https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-EffectivetoDate-1

Example: https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-EffectivetoDate-1

valueDate

string date

required

code

string

required

Value of the code system

Code System	Example Value
Specialty	UROLOGY
Clinic Type	GENERAL_UROLOGY
Appointment Cancellation Reason	SERVICE_INAPPROPRIATE

display

string

required

Display value of the code system

Code System	Example Display Value
Specialty	Urology
Clinic Type	General Urology
Appointment Cancellation Reason	Inappropriate service

property

array

nullable

required

Some properties are only returned for certain code systems

Property	Code System
EffectiveFrom	All Code Systems
EffectiveTo	All Code Systems
Specialty	CLINIC-TYPE
AppointmentBookingCancellationReasonType	APPOINTMENT-CANCELLATION-REASON
WillCancelWholeRequest	APPOINTMENT-CANCELLATION-REASON
CommentIsMandatory	APPOINTMENT-CANCELLATION-REASON

anyOf

object

Comment is mandatory value

This will only be returned when codeSystemType is APPOINTMENT-CANCELLATION-REASON

code

string

required

Allowed values: commentIsMandatory

valueBoolean

boolean

required

object

Will cancel whole request value

This will only be returned when codeSystemType is APPOINTMENT-CANCELLATION-REASON

code

string

required

Allowed values: willCancelWholeRequest

valueBoolean

boolean

required

object

Effective from date

code

string

required

Allowed values: effectiveFrom

valueDateTime

string date-time

required

object

Effective to date

code

string

required

Allowed values: effectiveTo

valueDateTime

string date-time

required

object

Specialty value

This will only be returned when codeSystemType is CLINIC-TYPE

code

string

required

Allowed values: specialty

valueCoding

object

required

system

string

required

Example: _baseUrl_/STU3/v1/CodeSystem/SPECIALTY

code

string

required

Example: CARDIOLOGY

object

Appointment cancellation reason type

This will only be returned when codeSystemType is APPOINTMENT-CANCELLATION-REASON

code

string

required

Allowed values: appointmentBookingCancellationReasonType

valueCoding

object

required

system

string

required

Allowed values: https://fhir.nhs.uk/STU3/CodeSystem/eRS-AppointmentBookingCancellationReasonType-1

Example: https://fhir.nhs.uk/STU3/CodeSystem/eRS-AppointmentBookingCancellationReasonType-1

code

string

required

Example: PROVIDER_REJECT

HTTP status: 400

Bad Request

HTTP status: 401

Unauthorized

HTTP status: 403

Forbidden

HTTP status: 404

Not Found

HTTP status: 429

You have exceeded your application's rate limit.

HTTP status: 500

Internal Server Error

A005 Retrieve Referral Request

get

/STU3/v1/ReferralRequest/{ubrn}

Overview

Use this endpoint to retrieve details of a referral. This includes references to clinical attachments, related referrals and other important data.

Pre-requisites

In order to use this endpoint you must be an authenticated e-RS user and use one of the following e-RS roles:

REFERRING_CLINICIAN
REFERRING_CLINICIAN_ADMIN
SERVICE_PROVIDER_CLINICIAN

You need to use the Unique Booking Reference Number (UBRN) of a referral request in order to retrieve details of a referral.

Use case

As an authenticated user

I want to read details of a referral

So that I can decide what further action may be needed.

Related endpoints

You can retrieve attachments that are associated with the referral using A006 - Retrieve attachment

You can retrieve a clinical information summary for the referral using A007 - Retrieve clinical information

You can search for services appropriate to a referral to form a shortlist using A010 - Patient service search

If bookable services are on the shortlist of the referral, you can retrieve appointment slots for a service on the shortlist for a referral using A015 - Retrieve appointment slots

You can retrieve the patient letter appropriate to the referral using A019 - Generate patient letter

Sandbox test scenarios

You can test the following scenarios in our sandbox environment

Scenario	Request
Unbooked `ReferralRequest`	`ubrn`=`000000070000`
`ReferralRequest` booked to directly-bookable service	`ubrn`=`000000070001`
`ReferralRequest` booked to indirectly-bookable service	`ubrn`=`000000070002`
`ReferralRequest` deferred to service provider for booking	`ubrn`=`000000070003`
`ReferralRequest` that was converted from an Advice and Guidance Request	`ubrn`=`000000070004`
`ReferralRequest` with related `ReferralRequest`	`ubrn`=`000000070005`

Request

Path parameters

Name Description

Name	Description
`ubrn`	String The unique booking reference number of the referral request Example: 000000070000 Required

ubrn

String

The unique booking reference number of the referral request

Example: 000000070000

Required

Headers

Name	Description
`Authorization`	String (^Bearer\ [[:ascii:]]+$) An OAuth 2.0 bearer token. Required in all environments except sandbox. Example: Bearer g1112R_ccQ1Ebbb4gtHBP1aaaNM Required
`nhsd-ers-ods-code`	String The ODS code of the caller's Organisation Example: R69 Required
`nhsd-ers-business-function`	String The e-RS Business Function of the caller Allowed values: REFERRING_CLINICIAN, REFERRING_CLINICIAN_ADMIN, REFERRING_ADMIN, BMS_HCP_PROXY, BMS_ADMIN, COMMISSIONER, SERVICE_DEFINER, ERS_ADMIN, SERVICE_PROVIDER_CLINICIAN, SERVICE_PROVIDER_ADMIN, INFORMATION_ANALYST, BOOKING_MANAGER, ADDITIONAL_REQUIREMENTS_MANAGER, REFERRER_RIGHTS_MANAGER Example: REFERRING_CLINICIAN Required
`X-Correlation-Id`	String Arbitrary string value provided by API Consumer Tends to be unique, but does not have to be Returned, unchanged, in the response Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA

Response

HTTP status: 200

e-RS Referral Request

Headers

Name Description

Name	Description
`x-correlation-id`	String The X-Correlation-ID from the request header, if supplied, mirrored back. Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA
`x-request-id`	String The e-RS transaction id Example: 58621d65-d5ad-4c3a-959f-0438e355990e-1
`ETag`	String Record version identifier enclosed in quotes and preceded by 'W/'. For example, `W/"2"`. This Weak ETag corresponds to `meta.versionId` attribute in the resource body. Pattern: /^W\/"[0-9]+"$/ Example: W/"2"

x-correlation-id

String

The X-Correlation-ID from the request header, if supplied, mirrored back.

Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA

x-request-id

String

The e-RS transaction id

Example: 58621d65-d5ad-4c3a-959f-0438e355990e-1

ETag

String

Record version identifier enclosed in quotes and preceded by 'W/'. For example, W/"2".

This Weak ETag corresponds to meta.versionId attribute in the resource body.

Pattern: /^W\/"[0-9]+"$/

Example: W/"2"

Body

Content type: application/fhir+json

Examples

Unbooked `ReferralRequest`

{
  "id" : "000000070000",
  "meta" : {
    "versionId" : "5",
    "profile" : [ "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-ReferralRequest-1" ]
  },
  "resourceType" : "ReferralRequest",
  "extension" : [ {
    "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-ClinicalInfoFirstSubmitted-1",
    "valueDateTime" : "2021-06-11T12:09:08.667000+00:00"
  }, {
    "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-ReferralPriority-1",
    "valueCodeableConcept" : {
      "coding" : [ {
        "system" : "https://fhir.nhs.uk/STU3/CodeSystem/eRS-Priority-1",
        "code" : "ROUTINE",
        "display" : "Routine"
      } ]
    }
  }, {
    "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-ReferralShortlist-1",
    "valueReference" : {
      "reference" : "#shortlist"
    }
  }, {
    "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-Commissioning-Rule-Org-1",
    "valueIdentifier" : {
      "system" : "https://fhir.nhs.uk/Id/ods-organization-code",
      "value" : "R69"
    }
  } ],
  "contained" : [ {
    "id" : "serviceSearchCriteria",
    "meta" : {
      "profile" : [ "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-ServiceSearchCriteria-Parameters-1" ]
    },
    "resourceType" : "Parameters",
    "parameter" : [ {
      "name" : "priority",
      "valueCoding" : {
        "system" : "https://fhir.nhs.uk/STU3/CodeSystem/eRS-Priority-1",
        "code" : "ROUTINE"
      }
    }, {
      "name" : "specialty",
      "valueCoding" : {
        "system" : "_baseUrl_/STU3/v1/CodeSystem/SPECIALTY",
        "code" : "CARDIOLOGY"
      }
    }, {
      "name" : "clinicType",
      "valueCoding" : {
        "system" : "https://fhir.nhs.uk/STU3/CodeSystem/eRS-ClinicType-1",
        "code" : "HEART_FAILURE"
      }
    }, {
      "name" : "organisation",
      "valueIdentifier" : {
        "system" : "https://directory.spineservices.nhs.uk/STU3/Organization",
        "value" : "TEST-ORG-GP1"
      }
    }, {
      "name" : "postcode",
      "valueString" : "LS1 2TW"
    }, {
      "name" : "distanceLimit",
      "valueUnsignedInt" : 123
    }, {
      "name" : "ageAndGenderAppropriate",
      "valueBoolean" : true
    } ]
  }, {
    "id" : "shortlist",
    "meta" : {
      "profile" : [ "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-Shortlist-List-1" ]
    },
    "resourceType" : "List",
    "extension" : [ {
      "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-Shortlist-SearchCriteria-1",
      "valueReference" : {
        "reference" : "#serviceSearchCriteria"
      }
    } ],
    "status" : "current",
    "mode" : "snapshot",
    "entry" : [ {
      "item" : {
        "identifier" : {
          "system" : "http://fhir.nhs.net/Id/ers-service",
          "value" : "11002"
        },
        "display" : "Good Cardiology Business Service"
      }
    } ]
  }, {
    "id" : "DocumentReference-80000",
    "meta" : {
      "profile" : [ "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-DocumentReference-1" ]
    },
    "resourceType" : "DocumentReference",
    "type" : {
      "coding" : [ {
        "system" : "https://fhir.nhs.uk/STU3/CodeSystem/eRS-AttachmentType-1",
        "code" : "REFERRER",
        "display" : "Referrer"
      } ]
    },
    "status" : "current",
    "indexed" : "2021-06-11T12:09:09.459000+00:00",
    "description" : "referralletter pdf",
    "content" : [ {
      "attachment" : {
        "id" : "80000",
        "extension" : [ {
          "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-AttachedBy-1",
          "valueReference" : {
            "identifier" : {
              "system" : "http://fhir.nhs.net/Id/sds-user-id",
              "value" : "021600556514"
            }
          }
        } ],
        "contentType" : "application/pdf",
        "url" : "Binary/att-70000-80000",
        "size" : 6,
        "title" : "referralletter.pdf",
        "creation" : "2021-06-11"
      }
    } ]
  } ],
  "status" : "active",
  "subject" : {
    "identifier" : {
      "system" : "http://fhir.nhs.net/Id/nhs-number",
      "value" : "9912003888"
    }
  },
  "supportingInfo" : [ {
    "reference" : "#DocumentReference-80000"
  } ],
  "intent" : "plan"
}

`ReferralRequest` booked to directly-bookable service

{
  "id" : "000000070001",
  "meta" : {
    "versionId" : "5",
    "profile" : [ "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-ReferralRequest-1" ]
  },
  "resourceType" : "ReferralRequest",
  "extension" : [ {
    "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-Appointment-1",
    "valueReference" : {
      "reference" : "#appointment"
    }
  }, {
    "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-ClinicalInfoFirstSubmitted-1",
    "valueDateTime" : "2021-06-11T12:33:23.167000+00:00"
  }, {
    "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-ReferralPriority-1",
    "valueCodeableConcept" : {
      "coding" : [ {
        "system" : "https://fhir.nhs.uk/STU3/CodeSystem/eRS-Priority-1",
        "code" : "ROUTINE",
        "display" : "Routine"
      } ]
    }
  }, {
    "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-ReferralShortlist-1",
    "valueReference" : {
      "reference" : "#shortlist"
    }
  }, {
    "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-Commissioning-Rule-Org-1",
    "valueIdentifier" : {
      "system" : "https://fhir.nhs.uk/Id/ods-organization-code",
      "value" : "R69"
    }
  } ],
  "contained" : [ {
    "id" : "serviceSearchCriteria",
    "meta" : {
      "profile" : [ "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-ServiceSearchCriteria-Parameters-1" ]
    },
    "resourceType" : "Parameters",
    "parameter" : [ {
      "name" : "priority",
      "valueCoding" : {
        "system" : "https://fhir.nhs.uk/STU3/CodeSystem/eRS-Priority-1",
        "code" : "ROUTINE"
      }
    }, {
      "name" : "specialty",
      "valueCoding" : {
        "system" : "_baseUrl_/STU3/v1/CodeSystem/SPECIALTY",
        "code" : "CARDIOLOGY"
      }
    }, {
      "name" : "clinicType",
      "valueCoding" : {
        "system" : "https://fhir.nhs.uk/STU3/CodeSystem/eRS-ClinicType-1",
        "code" : "HEART_FAILURE"
      }
    }, {
      "name" : "organisation",
      "valueIdentifier" : {
        "system" : "https://directory.spineservices.nhs.uk/STU3/Organization",
        "value" : "TEST-ORG-GP1"
      }
    }, {
      "name" : "postcode",
      "valueString" : "LS1 2TW"
    }, {
      "name" : "distanceLimit",
      "valueUnsignedInt" : 123
    }, {
      "name" : "ageAndGenderAppropriate",
      "valueBoolean" : true
    } ]
  }, {
    "id" : "shortlist",
    "meta" : {
      "profile" : [ "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-Shortlist-List-1" ]
    },
    "resourceType" : "List",
    "extension" : [ {
      "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-Shortlist-SearchCriteria-1",
      "valueReference" : {
        "reference" : "#serviceSearchCriteria"
      }
    } ],
    "status" : "current",
    "mode" : "snapshot",
    "entry" : [ {
      "item" : {
        "identifier" : {
          "system" : "http://fhir.nhs.net/Id/ers-service",
          "value" : "11002"
        },
        "display" : "Good Cardiology Business Service"
      }
    } ]
  }, {
    "id" : "appointment",
    "meta" : {
      "versionId" : "0",
      "profile" : [ "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-Appointment-1", "https://fhir.hl7.org.uk/STU3/StructureDefinition/CareConnect-Appointment-1" ]
    },
    "language" : "en",
    "resourceType" : "Appointment",
    "status" : "booked",
    "description" : "e-Referral Appointment",
    "start" : "2021-06-13T12:30:00+00:00",
    "end" : "2021-06-13T12:45:00+00:00",
    "slot" : [ {
      "reference" : "Slot/11002001"
    } ],
    "created" : "2021-06-11T12:33:25.664000+00:00",
    "incomingReferral" : [ {
      "reference" : "ReferralRequest/000000070001/_history/5"
    } ],
    "participant" : [ {
      "actor" : {
        "identifier" : {
          "system" : "http://fhir.nhs.net/Id/ers-service",
          "value" : "11002"
        },
        "display" : "Good Cardiology Business Service"
      },
      "status" : "accepted"
    }, {
      "actor" : {
        "identifier" : {
          "system" : "http://fhir.nhs.net/Id/nhs-number",
          "value" : "9912003888"
        }
      },
      "status" : "accepted"
    }, {
      "type" : {
        "coding" : [ {
          "system" : "http://hl7.org/fhir/ValueSet/encounter-participant-type",
          "code" : "CON"
        } ]
      },
      "actor" : {
        "identifier" : {
          "system" : "http://fhir.nhs.net/Id/sds-user-id",
          "value" : "021600556514"
        }
      },
      "status" : "accepted"
    } ]
  }, {
    "id" : "DocumentReference-80000",
    "meta" : {
      "profile" : [ "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-DocumentReference-1" ]
    },
    "resourceType" : "DocumentReference",
    "type" : {
      "coding" : [ {
        "system" : "https://fhir.nhs.uk/STU3/CodeSystem/eRS-AttachmentType-1",
        "code" : "REFERRER",
        "display" : "Referrer"
      } ]
    },
    "status" : "current",
    "indexed" : "2021-06-11T12:09:09.459000+00:00",
    "description" : "referralletter pdf",
    "content" : [ {
      "attachment" : {
        "id" : "80000",
        "extension" : [ {
          "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-AttachedBy-1",
          "valueReference" : {
            "identifier" : {
              "system" : "http://fhir.nhs.net/Id/sds-user-id",
              "value" : "021600556514"
            }
          }
        } ],
        "contentType" : "application/pdf",
        "url" : "Binary/att-70001-80000",
        "size" : 6,
        "title" : "referralletter.pdf",
        "creation" : "2021-06-11"
      }
    } ]
  } ],
  "status" : "active",
  "specialty" : {
    "coding" : [ {
      "system" : "_baseUrl_/STU3/v1/CodeSystem/SPECIALTY",
      "code" : "CARDIOLOGY",
      "display" : "Cardiology"
    } ]
  },
  "subject" : {
    "identifier" : {
      "system" : "http://fhir.nhs.net/Id/nhs-number",
      "value" : "9912003888"
    }
  },
  "supportingInfo" : [ {
    "reference" : "#DocumentReference-80000"
  } ],
  "intent" : "plan"
}

`ReferralRequest` booked to indirectly-bookable service

{
  "id" : "000000070002",
  "meta" : {
    "versionId" : "5",
    "profile" : [ "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-ReferralRequest-1" ]
  },
  "resourceType" : "ReferralRequest",
  "extension" : [ {
    "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-Appointment-1",
    "valueReference" : {
      "reference" : "#appointment"
    }
  }, {
    "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-ClinicalInfoFirstSubmitted-1",
    "valueDateTime" : "2021-06-11T13:43:33.338000+00:00"
  }, {
    "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-ReferralPriority-1",
    "valueCodeableConcept" : {
      "coding" : [ {
        "system" : "https://fhir.nhs.uk/STU3/CodeSystem/eRS-Priority-1",
        "code" : "ROUTINE",
        "display" : "Routine"
      } ]
    }
  }, {
    "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-ReferralShortlist-1",
    "valueReference" : {
      "reference" : "#shortlist"
    }
  }, {
    "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-Commissioning-Rule-Org-1",
    "valueIdentifier" : {
      "system" : "https://fhir.nhs.uk/Id/ods-organization-code",
      "value" : "R69"
    }
  } ],
  "contained" : [ {
    "id" : "serviceSearchCriteria",
    "meta" : {
      "profile" : [ "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-ServiceSearchCriteria-Parameters-1" ]
    },
    "resourceType" : "Parameters",
    "parameter" : [ {
      "name" : "priority",
      "valueCoding" : {
        "system" : "https://fhir.nhs.uk/STU3/CodeSystem/eRS-Priority-1",
        "code" : "ROUTINE"
      }
    }, {
      "name" : "specialty",
      "valueCoding" : {
        "system" : "_baseUrl_/STU3/v1/CodeSystem/SPECIALTY",
        "code" : "CARDIOLOGY"
      }
    }, {
      "name" : "clinicType",
      "valueCoding" : {
        "system" : "https://fhir.nhs.uk/STU3/CodeSystem/eRS-ClinicType-1",
        "code" : "HEART_FAILURE"
      }
    }, {
      "name" : "organisation",
      "valueIdentifier" : {
        "system" : "https://directory.spineservices.nhs.uk/STU3/Organization",
        "value" : "TEST-ORG-GP1"
      }
    }, {
      "name" : "postcode",
      "valueString" : "LS1 2TW"
    }, {
      "name" : "distanceLimit",
      "valueUnsignedInt" : 123
    }, {
      "name" : "ageAndGenderAppropriate",
      "valueBoolean" : true
    } ]
  }, {
    "id" : "shortlist",
    "meta" : {
      "profile" : [ "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-Shortlist-List-1" ]
    },
    "resourceType" : "List",
    "extension" : [ {
      "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-Shortlist-SearchCriteria-1",
      "valueReference" : {
        "reference" : "#serviceSearchCriteria"
      }
    } ],
    "status" : "current",
    "mode" : "snapshot",
    "entry" : [ {
      "item" : {
        "identifier" : {
          "system" : "http://fhir.nhs.net/Id/ers-service",
          "value" : "11016"
        },
        "display" : "Triage-Related Indirect Business Service"
      }
    }, {
      "item" : {
        "identifier" : {
          "system" : "http://fhir.nhs.net/Id/ers-service",
          "value" : "11017"
        },
        "display" : "Triage-Related Indirect Business Service 2"
      }
    } ]
  }, {
    "id" : "appointment",
    "meta" : {
      "versionId" : "0",
      "profile" : [ "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-Appointment-1", "https://fhir.hl7.org.uk/STU3/StructureDefinition/CareConnect-Appointment-1" ]
    },
    "language" : "en",
    "resourceType" : "Appointment",
    "status" : "booked",
    "description" : "e-Referral Appointment",
    "start" : "2021-07-05T10:00:00+00:00",
    "end" : "2021-07-05T10:00:00+00:00",
    "created" : "2021-06-11T13:43:34.424000+00:00",
    "incomingReferral" : [ {
      "reference" : "ReferralRequest/000000070002/_history/5"
    } ],
    "participant" : [ {
      "actor" : {
        "identifier" : {
          "system" : "http://fhir.nhs.net/Id/ers-service",
          "value" : "11016"
        },
        "display" : "Triage-Related Indirect Business Service"
      },
      "status" : "accepted"
    }, {
      "actor" : {
        "identifier" : {
          "system" : "http://fhir.nhs.net/Id/nhs-number",
          "value" : "9912003888"
        }
      },
      "status" : "accepted"
    } ]
  }, {
    "id" : "DocumentReference-80000",
    "meta" : {
      "profile" : [ "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-DocumentReference-1" ]
    },
    "resourceType" : "DocumentReference",
    "type" : {
      "coding" : [ {
        "system" : "https://fhir.nhs.uk/STU3/CodeSystem/eRS-AttachmentType-1",
        "code" : "REFERRER",
        "display" : "Referrer"
      } ]
    },
    "status" : "current",
    "indexed" : "2021-06-11T12:09:09.459000+00:00",
    "description" : "referralletter pdf",
    "content" : [ {
      "attachment" : {
        "id" : "80000",
        "extension" : [ {
          "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-AttachedBy-1",
          "valueReference" : {
            "identifier" : {
              "system" : "http://fhir.nhs.net/Id/sds-user-id",
              "value" : "021600556514"
            }
          }
        } ],
        "contentType" : "application/pdf",
        "url" : "Binary/att-70002-80000",
        "size" : 6,
        "title" : "referralletter.pdf",
        "creation" : "2021-06-11"
      }
    } ]
  } ],
  "status" : "active",
  "specialty" : {
    "coding" : [ {
      "system" : "_baseUrl_/STU3/v1/CodeSystem/SPECIALTY",
      "code" : "CARDIOLOGY",
      "display" : "Cardiology"
    } ]
  },
  "subject" : {
    "identifier" : {
      "system" : "http://fhir.nhs.net/Id/nhs-number",
      "value" : "9912003888"
    }
  },
  "supportingInfo" : [ {
    "reference" : "#DocumentReference-80000"
  } ],
  "intent" : "plan"
}

`ReferralRequest` deferred to service provider for booking

{
  "id" : "000000070003",
  "meta" : {
    "versionId" : "5",
    "profile" : [ "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-ReferralRequest-1" ]
  },
  "resourceType" : "ReferralRequest",
  "extension" : [ {
    "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-Appointment-1",
    "valueReference" : {
      "reference" : "#appointment"
    }
  }, {
    "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-ClinicalInfoFirstSubmitted-1",
    "valueDateTime" : "2021-06-11T13:55:32.927000+00:00"
  }, {
    "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-ReferralPriority-1",
    "valueCodeableConcept" : {
      "coding" : [ {
        "system" : "https://fhir.nhs.uk/STU3/CodeSystem/eRS-Priority-1",
        "code" : "URGENT",
        "display" : "Urgent"
      } ]
    }
  }, {
    "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-ReferralShortlist-1",
    "valueReference" : {
      "reference" : "#shortlist"
    }
  }, {
    "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-Commissioning-Rule-Org-1",
    "valueIdentifier" : {
      "system" : "https://fhir.nhs.uk/Id/ods-organization-code",
      "value" : "R69"
    }
  } ],
  "contained" : [ {
    "id" : "serviceSearchCriteria",
    "meta" : {
      "profile" : [ "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-ServiceSearchCriteria-Parameters-1" ]
    },
    "resourceType" : "Parameters",
    "parameter" : [ {
      "name" : "priority",
      "valueCoding" : {
        "system" : "https://fhir.nhs.uk/STU3/CodeSystem/eRS-Priority-1",
        "code" : "URGENT"
      }
    }, {
      "name" : "specialty",
      "valueCoding" : {
        "system" : "_baseUrl_/STU3/v1/CodeSystem/SPECIALTY",
        "code" : "CARDIOLOGY"
      }
    }, {
      "name" : "clinicType",
      "valueCoding" : {
        "system" : "https://fhir.nhs.uk/STU3/CodeSystem/eRS-ClinicType-1",
        "code" : "HEART_FAILURE"
      }
    }, {
      "name" : "organisation",
      "valueIdentifier" : {
        "system" : "https://directory.spineservices.nhs.uk/STU3/Organization",
        "value" : "TEST-ORG-GP1"
      }
    }, {
      "name" : "postcode",
      "valueString" : "LS1 2TW"
    }, {
      "name" : "distanceLimit",
      "valueUnsignedInt" : 123
    }, {
      "name" : "ageAndGenderAppropriate",
      "valueBoolean" : true
    } ]
  }, {
    "id" : "shortlist",
    "meta" : {
      "profile" : [ "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-Shortlist-List-1" ]
    },
    "resourceType" : "List",
    "extension" : [ {
      "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-Shortlist-SearchCriteria-1",
      "valueReference" : {
        "reference" : "#serviceSearchCriteria"
      }
    } ],
    "status" : "current",
    "mode" : "snapshot",
    "entry" : [ {
      "item" : {
        "identifier" : {
          "system" : "http://fhir.nhs.net/Id/ers-service",
          "value" : "11010"
        },
        "display" : "Excellent Cardiology Business Service"
      }
    } ]
  }, {
    "id" : "appointment",
    "meta" : {
      "versionId" : "1",
      "profile" : [ "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-Appointment-1", "https://fhir.hl7.org.uk/STU3/StructureDefinition/CareConnect-Appointment-1" ]
    },
    "language" : "en",
    "resourceType" : "Appointment",
    "status" : "proposed",
    "reason" : [ {
      "coding" : [ {
        "system" : "https://fhir.nhs.uk/STU3/CodeSystem/eRS-ReviewReason-1",
        "code" : "NO_SLOTS_AT_SERVICE"
      } ]
    } ],
    "description" : "e-Referral Appointment",
    "created" : "2021-06-11T13:55:36.392000+00:00",
    "comment" : "Yes!",
    "incomingReferral" : [ {
      "reference" : "ReferralRequest/000000070003/_history/5"
    } ],
    "participant" : [ {
      "actor" : {
        "identifier" : {
          "system" : "http://fhir.nhs.net/Id/ers-service",
          "value" : "11010"
        },
        "display" : "Excellent Cardiology Business Service"
      },
      "status" : "accepted"
    }, {
      "actor" : {
        "identifier" : {
          "system" : "http://fhir.nhs.net/Id/nhs-number",
          "value" : "9912003888"
        }
      },
      "status" : "accepted"
    } ]
  }, {
    "id" : "DocumentReference-80000",
    "meta" : {
      "profile" : [ "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-DocumentReference-1" ]
    },
    "resourceType" : "DocumentReference",
    "type" : {
      "coding" : [ {
        "system" : "https://fhir.nhs.uk/STU3/CodeSystem/eRS-AttachmentType-1",
        "code" : "REFERRER",
        "display" : "Referrer"
      } ]
    },
    "status" : "current",
    "indexed" : "2021-06-11T12:09:09.459000+00:00",
    "description" : "referralletter pdf",
    "content" : [ {
      "attachment" : {
        "id" : "80000",
        "extension" : [ {
          "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-AttachedBy-1",
          "valueReference" : {
            "identifier" : {
              "system" : "http://fhir.nhs.net/Id/sds-user-id",
              "value" : "021600556514"
            }
          }
        } ],
        "contentType" : "application/pdf",
        "url" : "Binary/att-70003-80000",
        "size" : 6,
        "title" : "referralletter.pdf",
        "creation" : "2021-06-11"
      }
    } ]
  } ],
  "status" : "active",
  "specialty" : {
    "coding" : [ {
      "system" : "_baseUrl_/STU3/v1/CodeSystem/SPECIALTY",
      "code" : "CARDIOLOGY",
      "display" : "Cardiology"
    } ]
  },
  "subject" : {
    "identifier" : {
      "system" : "http://fhir.nhs.net/Id/nhs-number",
      "value" : "9912003888"
    }
  },
  "supportingInfo" : [ {
    "reference" : "#DocumentReference-80000"
  } ],
  "intent" : "plan"
}

`ReferralRequest` that was converted from an Advice and Guidance Request

{
  "id" : "000000070004",
  "meta" : {
    "versionId" : "5",
    "profile" : [ "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-ReferralRequest-1" ]
  },
  "resourceType" : "ReferralRequest",
  "extension" : [ {
    "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-Appointment-1",
    "valueReference" : {
      "reference" : "#appointment"
    }
  }, {
    "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-ClinicalInfoFirstSubmitted-1",
    "valueDateTime" : "2021-06-11T14:04:48.172000+00:00"
  }, {
    "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-ReferralPriority-1",
    "valueCodeableConcept" : {
      "coding" : [ {
        "system" : "https://fhir.nhs.uk/STU3/CodeSystem/eRS-Priority-1",
        "code" : "TWO_WEEK_WAIT",
        "display" : "2 Week Wait"
      } ]
    }
  }, {
    "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-ReferralShortlist-1",
    "valueReference" : {
      "reference" : "#shortlist"
    }
  }, {
    "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-Commissioning-Rule-Org-1",
    "valueIdentifier" : {
      "system" : "https://fhir.nhs.uk/Id/ods-organization-code",
      "value" : "R69"
    }
  } ],
  "contained" : [ {
    "id" : "serviceSearchCriteria",
    "meta" : {
      "profile" : [ "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-ServiceSearchCriteria-Parameters-1" ]
    },
    "resourceType" : "Parameters",
    "parameter" : [ {
      "name" : "priority",
      "valueCoding" : {
        "system" : "https://fhir.nhs.uk/STU3/CodeSystem/eRS-Priority-1",
        "code" : "TWO_WEEK_WAIT"
      }
    }, {
      "name" : "specialty",
      "valueCoding" : {
        "system" : "_baseUrl_/STU3/v1/CodeSystem/SPECIALTY",
        "code" : "CARDIOLOGY"
      }
    }, {
      "name" : "clinicType",
      "valueCoding" : {
        "system" : "https://fhir.nhs.uk/STU3/CodeSystem/eRS-ClinicType-1",
        "code" : "HEART_FAILURE"
      }
    }, {
      "name" : "organisation",
      "valueIdentifier" : {
        "system" : "https://directory.spineservices.nhs.uk/STU3/Organization",
        "value" : "TEST-ORG-GP1"
      }
    }, {
      "name" : "postcode",
      "valueString" : "LS1 2TW"
    }, {
      "name" : "distanceLimit",
      "valueUnsignedInt" : 123
    }, {
      "name" : "ageAndGenderAppropriate",
      "valueBoolean" : true
    } ]
  }, {
    "id" : "shortlist",
    "meta" : {
      "profile" : [ "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-Shortlist-List-1" ]
    },
    "resourceType" : "List",
    "extension" : [ {
      "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-Shortlist-SearchCriteria-1",
      "valueReference" : {
        "reference" : "#serviceSearchCriteria"
      }
    } ],
    "status" : "current",
    "mode" : "snapshot",
    "entry" : [ {
      "item" : {
        "identifier" : {
          "system" : "http://fhir.nhs.net/Id/ers-service",
          "value" : "11014"
        },
        "display" : "Advice Only"
      }
    } ]
  }, {
    "id" : "DocumentReference-80002",
    "meta" : {
      "profile" : [ "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-DocumentReference-1" ]
    },
    "resourceType" : "DocumentReference",
    "type" : {
      "coding" : [ {
        "system" : "https://fhir.nhs.uk/STU3/CodeSystem/eRS-AttachmentType-1",
        "code" : "PROVIDER",
        "display" : "Provider"
      } ]
    },
    "status" : "current",
    "indexed" : "2021-06-11T14:04:48.987000+00:00",
    "description" : "triage png",
    "content" : [ {
      "attachment" : {
        "id" : "80002",
        "extension" : [ {
          "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-AttachedBy-1",
          "valueReference" : {
            "identifier" : {
              "system" : "http://fhir.nhs.net/Id/sds-user-id",
              "value" : "021600556514"
            }
          }
        } ],
        "contentType" : "image/png",
        "url" : "Binary/att-70004-80002",
        "size" : 6,
        "title" : "triage.png",
        "creation" : "2021-06-11"
      }
    } ]
  }, {
    "id" : "DocumentReference-80003",
    "meta" : {
      "profile" : [ "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-DocumentReference-1" ]
    },
    "resourceType" : "DocumentReference",
    "type" : {
      "coding" : [ {
        "system" : "https://fhir.nhs.uk/STU3/CodeSystem/eRS-AttachmentType-1",
        "code" : "REFERRER",
        "display" : "Referrer"
      } ]
    },
    "status" : "current",
    "indexed" : "2021-06-11T14:04:48.987000+00:00",
    "content" : [ {
      "attachment" : {
        "id" : "80003",
        "extension" : [ {
          "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-AttachedBy-1",
          "valueReference" : {
            "identifier" : {
              "system" : "http://fhir.nhs.net/Id/sds-user-id",
              "value" : "021600556514"
            }
          }
        } ],
        "contentType" : "application/pdf",
        "url" : "Binary/att-70004-80003",
        "size" : 3807,
        "title" : "Advice and guidance conversation - 000000070004.pdf",
        "creation" : "2021-06-11"
      }
    } ]
  }, {
    "id" : "appointment",
    "meta" : {
      "versionId" : "1",
      "profile" : [ "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-Appointment-1", "https://fhir.hl7.org.uk/STU3/StructureDefinition/CareConnect-Appointment-1" ]
    },
    "language" : "en",
    "resourceType" : "Appointment",
    "status" : "proposed",
    "reason" : [ {
      "coding" : [ {
        "system" : "https://fhir.nhs.uk/STU3/CodeSystem/eRS-ReviewOutcome-1",
        "code" : "PROVIDER_CONVERTED_ADVICE_AND_GUIDANCE_ADMIN_TO_REFER",
        "display" : "Provider Converted Advice and Guidance, Admin to Refer"
      } ]
    } ],
    "description" : "e-Referral Appointment",
    "created" : "2021-06-11T14:04:48.217000+00:00",
    "comment" : "Actually I'd rather not",
    "incomingReferral" : [ {
      "reference" : "ReferralRequest/000000070004/_history/5"
    } ],
    "participant" : [ {
      "actor" : {
        "identifier" : {
          "system" : "http://fhir.nhs.net/Id/ers-service",
          "value" : "11014"
        },
        "display" : "Advice Only"
      },
      "status" : "accepted"
    }, {
      "actor" : {
        "identifier" : {
          "system" : "http://fhir.nhs.net/Id/nhs-number",
          "value" : "9912003888"
        }
      },
      "status" : "accepted"
    } ]
  }, {
    "id" : "DocumentReference-80000",
    "meta" : {
      "profile" : [ "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-DocumentReference-1" ]
    },
    "resourceType" : "DocumentReference",
    "type" : {
      "coding" : [ {
        "system" : "https://fhir.nhs.uk/STU3/CodeSystem/eRS-AttachmentType-1",
        "code" : "ADVICE_REQUEST",
        "display" : "Advice Request"
      } ]
    },
    "status" : "current",
    "indexed" : "2021-06-11T14:04:48.987000+00:00",
    "description" : "advice png",
    "content" : [ {
      "attachment" : {
        "id" : "80000",
        "extension" : [ {
          "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-AttachedBy-1",
          "valueReference" : {
            "identifier" : {
              "system" : "http://fhir.nhs.net/Id/sds-user-id",
              "value" : "921600556514"
            }
          }
        } ],
        "contentType" : "image/png",
        "url" : "Binary/att-70004-80000",
        "size" : 6,
        "title" : "advice.png",
        "creation" : "2021-06-11"
      }
    } ]
  }, {
    "id" : "DocumentReference-80001",
    "meta" : {
      "profile" : [ "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-DocumentReference-1" ]
    },
    "resourceType" : "DocumentReference",
    "type" : {
      "coding" : [ {
        "system" : "https://fhir.nhs.uk/STU3/CodeSystem/eRS-AttachmentType-1",
        "code" : "GUIDANCE_RESPONSE",
        "display" : "Guidance Response"
      } ]
    },
    "status" : "current",
    "indexed" : "2021-06-11T14:04:48.987000+00:00",
    "description" : "provider png",
    "content" : [ {
      "attachment" : {
        "id" : "80001",
        "extension" : [ {
          "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-AttachedBy-1",
          "valueReference" : {
            "identifier" : {
              "system" : "http://fhir.nhs.net/Id/sds-user-id",
              "value" : "021600556514"
            }
          }
        } ],
        "contentType" : "image/png",
        "url" : "Binary/att-70004-80001",
        "size" : 6,
        "title" : "provider.png",
        "creation" : "2021-06-11"
      }
    } ]
  } ],
  "status" : "active",
  "specialty" : {
    "coding" : [ {
      "system" : "_baseUrl_/STU3/v1/CodeSystem/SPECIALTY",
      "code" : "CARDIOLOGY",
      "display" : "Cardiology"
    } ]
  },
  "subject" : {
    "identifier" : {
      "system" : "http://fhir.nhs.net/Id/nhs-number",
      "value" : "9912003888"
    }
  },
  "supportingInfo" : [ {
    "reference" : "#DocumentReference-80003"
  }, {
    "reference" : "#DocumentReference-80000"
  }, {
    "reference" : "#DocumentReference-80001"
  }, {
    "reference" : "#DocumentReference-80002"
  }, {
    "reference" : "CommunicationRequest/000000070004"
  } ],
  "intent" : "plan"
}

`ReferralRequest` with related ReferralRequest

{
  "id" : "000000070005",
  "meta" : {
    "versionId" : "5",
    "profile" : [ "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-ReferralRequest-1" ]
  },
  "resourceType" : "ReferralRequest",
  "extension" : [ {
    "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-Appointment-1",
    "valueReference" : {
      "reference" : "#appointment"
    }
  }, {
    "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-ReferralPriority-1",
    "valueCodeableConcept" : {
      "coding" : [ {
        "system" : "https://fhir.nhs.uk/STU3/CodeSystem/eRS-Priority-1",
        "code" : "TWO_WEEK_WAIT",
        "display" : "2 Week Wait"
      } ]
    }
  }, {
    "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-ReferralShortlist-1",
    "valueReference" : {
      "reference" : "#shortlist"
    }
  }, {
    "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-Commissioning-Rule-Org-1",
    "valueIdentifier" : {
      "system" : "https://fhir.nhs.uk/Id/ods-organization-code",
      "value" : "R69"
    }
  } ],
  "contained" : [ {
    "id" : "serviceSearchCriteria",
    "meta" : {
      "profile" : [ "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-ServiceSearchCriteria-Parameters-1" ]
    },
    "resourceType" : "Parameters",
    "parameter" : [ {
      "name" : "priority",
      "valueCoding" : {
        "system" : "https://fhir.nhs.uk/STU3/CodeSystem/eRS-Priority-1",
        "code" : "TWO_WEEK_WAIT"
      }
    }, {
      "name" : "specialty",
      "valueCoding" : {
        "system" : "_baseUrl_/STU3/v1/CodeSystem/SPECIALTY",
        "code" : "CARDIOLOGY"
      }
    }, {
      "name" : "clinicType",
      "valueCoding" : {
        "system" : "https://fhir.nhs.uk/STU3/CodeSystem/eRS-ClinicType-1",
        "code" : "HEART_FAILURE"
      }
    }, {
      "name" : "organisation",
      "valueIdentifier" : {
        "system" : "https://directory.spineservices.nhs.uk/STU3/Organization",
        "value" : "TEST-ORG-GP1"
      }
    }, {
      "name" : "postcode",
      "valueString" : "LS1 2TW"
    }, {
      "name" : "distanceLimit",
      "valueUnsignedInt" : 123
    }, {
      "name" : "ageAndGenderAppropriate",
      "valueBoolean" : true
    } ]
  }, {
    "id" : "shortlist",
    "meta" : {
      "profile" : [ "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-Shortlist-List-1" ]
    },
    "resourceType" : "List",
    "extension" : [ {
      "url" : "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-Shortlist-SearchCriteria-1",
      "valueReference" : {
        "reference" : "#serviceSearchCriteria"
      }
    } ],
    "status" : "current",
    "mode" : "snapshot",
    "entry" : [ {
      "item" : {
        "identifier" : {
          "system" : "http://fhir.nhs.net/Id/ers-service",
          "value" : "11002"
        },
        "display" : "Good Cardiology Business Service"
      }
    } ]
  }, {
    "id" : "appointment",
    "meta" : {
      "versionId" : "0",
      "profile" : [ "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-Appointment-1", "https://fhir.hl7.org.uk/STU3/StructureDefinition/CareConnect-Appointment-1" ]
    },
    "language" : "en",
    "resourceType" : "Appointment",
    "status" : "booked",
    "description" : "e-Referral Appointment",
    "start" : "2021-06-14T00:13:46.106000+00:00",
    "end" : "2021-06-14T01:13:46.106000+00:00",
    "slot" : [ {
      "reference" : "Slot/11002011"
    } ],
    "created" : "2021-06-11T14:13:56.291000+00:00",
    "incomingReferral" : [ {
      "reference" : "ReferralRequest/000000070005/_history/5"
    } ],
    "participant" : [ {
      "actor" : {
        "identifier" : {
          "system" : "http://fhir.nhs.net/Id/ers-service",
          "value" : "11002"
        },
        "display" : "Good Cardiology Business Service"
      },
      "status" : "accepted"
    }, {
      "actor" : {
        "identifier" : {
          "system" : "http://fhir.nhs.net/Id/nhs-number",
          "value" : "9912003888"
        }
      },
      "status" : "accepted"
    }, {
      "type" : {
        "coding" : [ {
          "system" : "http://hl7.org/fhir/ValueSet/encounter-participant-type",
          "code" : "CON"
        } ]
      },
      "actor" : {
        "identifier" : {
          "system" : "http://fhir.nhs.net/Id/sds-user-id",
          "value" : "021600556514"
        }
      },
      "status" : "accepted"
    } ]
  } ],
  "status" : "active",
  "specialty" : {
    "coding" : [ {
      "system" : "_baseUrl_/STU3/v1/CodeSystem/SPECIALTY",
      "code" : "CARDIOLOGY",
      "display" : "Cardiology"
    } ]
  },
  "subject" : {
    "identifier" : {
      "system" : "http://fhir.nhs.net/Id/nhs-number",
      "value" : "9912003888"
    }
  },
  "supportingInfo" : [ {
    "reference" : "ReferralRequest/000000070004"
  } ],
  "intent" : "plan"
}

Schema

Name Description

object

eRS-ReferralRequest

string

required

Example: 000000070000

meta

object

required

profile

array

required

string

Allowed values: https://fhir.nhs.uk/STU3/StructureDefinition/eRS-ReferralRequest-1

Example: https://fhir.nhs.uk/STU3/StructureDefinition/eRS-ReferralRequest-1

versionId

string

required

Example: 3

resourceType

string

required

Allowed values: ReferralRequest

Example: ReferralRequest

contained

array

nullable

required

Field	Cardinality	Notes
`eRS-Shortlist-List`	`1..1`
`eRS-ServiceSearchCriteria-Parameters`	`1..1`
`eRS-Appointment`	`0..1`
`DocumentReference`	`0..*`

anyOf

object

eRS-Shortlist-List

A list of services representing the services available to the patient to have treatment at

meta

object

required

profile

array

required

string

Allowed values: https://fhir.nhs.uk/STU3/StructureDefinition/eRS-Shortlist-List-1

Example: https://fhir.nhs.uk/STU3/StructureDefinition/eRS-Shortlist-List-1

contained

array

object

eRS-ServiceSearchCriteria-Parameters

The criteria used to search for services

string

required

Example: ServiceSearchCriteria-1

meta

object

required

profile

array

required

string

Allowed values: https://fhir.nhs.uk/STU3/StructureDefinition/eRS-ServiceSearchCriteria-Parameters-1

Example: https://fhir.nhs.uk/STU3/StructureDefinition/eRS-ServiceSearchCriteria-Parameters-1

resourceType

string

required

Allowed values: Parameters

Example: Parameters

parameter

array

required

Field	Cardinality	Notes
`Priority`	`1..1`
`Specialty`	`0..1`
`ClinicType`	`0..1`
`IndicativeAppointmentWaitTimeLimit`	`0..1`
`Postcode`	`0..1`
`DistanceLimit`	`0..1`
`ClinicalTerm`	`0..1`
`NamedClinician`	`0..1`
`AgeAndGenderAppropriate`	`1..1`
`CommissioningProvisioning`	`1..1`
`Organisation`	`0..1`
`Place`	`0..1`	Only supported in read mode, search by `place` is not possible currently.

anyOf

object

Priority

Details the priority parameter

name

string

required

Allowed values: priority

Example: priority

valueCoding

object

required

system

string

required

Allowed values: https://fhir.nhs.uk/STU3/CodeSystem/eRS-Priority-1

Example: https://fhir.nhs.uk/STU3/CodeSystem/eRS-Priority-1

code

string

required

Allowed values: ROUTINE, URGENT, TWO_WEEK_WAIT

Example: URGENT

object

Specialty

Details the specialty parameter

name

string

required

Allowed values: specialty

Example: specialty

valueCoding

object

required

system

string

required

Example: _baseUrl_/STU3/v1/CodeSystem/SPECIALTY

code

string

required

Example: CARDIOLOGY

object

ClinicType

Details the clinic type that was specified in a search criteria

name

string

required

Allowed values: clinicType

Example: clinicType

valueCoding

object

required

system

string

required

Allowed values: https://fhir.nhs.uk/STU3/CodeSystem/eRS-ClinicType-1

Example: https://fhir.nhs.uk/STU3/CodeSystem/eRS-ClinicType-1

code

string

required

Example: HEART_FAILURE

object

IndicativeAppointmentWaitTimeLimit

Details the indicative appointment wait time limit value specified in a search criteria

name

string

required

Allowed values: indicativeAppointmentWaitTimeLimit

Example: indicativeAppointmentWaitTimeLimit

valueUnsignedInt

integer int32

required

Minimum: 0 (inclusive)

Example: 50

object

Postcode

Details the postcode value specified in a search criteria

name

string

required

Allowed values: postcode

Example: postcode

valueString

string

required

Example: LS1 2UT

object

DistanceLimit

Details the distance limit value specified in a search criteria

name

string

required

Allowed values: distanceLimit

Example: distanceLimit

valueUnsignedInt

integer int32

required

Minimum: 0 (inclusive)

Example: 123

object

ClinicalTerm

Details the clinical term that was specified in a search criteria

name

string

required

Allowed values: clinicalTerm

Example: clinicalTerm

valueCoding

object

required

system

string

required

Allowed values: http://snomed.info/sct

Example: http://snomed.info/sct

code

string

required

Example: 1003

object

NamedClinician

Details the named clinician that was specified in a search criteria

name

string

required

Allowed values: namedClinician

Example: namedClinician

valueIdentifier

object

required

system

string

required

Allowed values: http://fhir.nhs.net/Id/sds-user-id

Example: http://fhir.nhs.net/Id/sds-user-id

value

string

required

Example: 021600556514

object

AgeAndGenderAppropriate

Details the age and gender appropriate flag detailed in a search criteria

name

string

required

Allowed values: ageAndGenderAppropriate

Example: ageAndGenderAppropriate

valueBoolean

boolean

required

Example: true

object

CommissioningProvisioning

Details the commissioning provisioning flag detailed in a search criteria

name

string

required

Allowed values: commissioningProvisioning

Example: commissioningProvisioning

valueCoding

object

required

system

string

required

Allowed values: https://fhir.nhs.uk/STU3/CodeSystem/eRS-CommissioningProvisioning-1

Example: https://fhir.nhs.uk/STU3/CodeSystem/eRS-CommissioningProvisioning-1

code

string

required

Allowed values: ALL_AVAILABLE_FOR_BOOKING, ALL_SERVICES, LOCALLY_COMMISSIONABLE, NATIONALLY_AVAILABLE

Example: LOCALLY_COMMISSIONABLE

object

Organisation

Details the organisation that was specified in a search criteria

name

string

required

Allowed values: organisation

Example: organisation

valueIdentifier

object

required

system

string

required

Allowed values: https://directory.spineservices.nhs.uk/STU3/Organization

Example: https://directory.spineservices.nhs.uk/STU3/Organization

value

string

required

Example: R69

object

Place

Details the place that was specified in a search criteria

name

string

required

Allowed values: place

Example: place

valueString

string

required

Example: Leeds

resourceType

string

required

Allowed values: List

Example: List

entry

array

required

Max items: 20

Min items: 1

object

Singular entry with service details

item

object

required

identifier

object

required

system

string

required

Allowed values: http://fhir.nhs.net/Id/ers-service

Example: http://fhir.nhs.net/Id/ers-service

value

string

required

Example: 11002

display

string

Example: Good Cardiology Business Service

object

eRS-ServiceSearchCriteria-Parameters

The criteria used to search for services

string

required

Example: ServiceSearchCriteria-1

meta

object

required

profile

array

required

string

Allowed values: https://fhir.nhs.uk/STU3/StructureDefinition/eRS-ServiceSearchCriteria-Parameters-1

Example: https://fhir.nhs.uk/STU3/StructureDefinition/eRS-ServiceSearchCriteria-Parameters-1

resourceType

string

required

Allowed values: Parameters

Example: Parameters

parameter

array

required

Field	Cardinality	Notes
`Priority`	`1..1`
`Specialty`	`0..1`
`ClinicType`	`0..1`
`IndicativeAppointmentWaitTimeLimit`	`0..1`
`Postcode`	`0..1`
`DistanceLimit`	`0..1`
`ClinicalTerm`	`0..1`
`NamedClinician`	`0..1`
`AgeAndGenderAppropriate`	`1..1`
`CommissioningProvisioning`	`1..1`
`Organisation`	`0..1`
`Place`	`0..1`	Only supported in read mode, search by `place` is not possible currently.

anyOf

object

Priority

Details the priority parameter

name

string

required

Allowed values: priority

Example: priority

valueCoding

object

required

system

string

required

Allowed values: https://fhir.nhs.uk/STU3/CodeSystem/eRS-Priority-1

Example: https://fhir.nhs.uk/STU3/CodeSystem/eRS-Priority-1

code

string

required

Allowed values: ROUTINE, URGENT, TWO_WEEK_WAIT

Example: URGENT

object

Specialty

Details the specialty parameter

name

string

required

Allowed values: specialty

Example: specialty

valueCoding

object

required

system

string

required

Example: _baseUrl_/STU3/v1/CodeSystem/SPECIALTY

code

string

required

Example: CARDIOLOGY

object

ClinicType

Details the clinic type that was specified in a search criteria

name

string

required

Allowed values: clinicType

Example: clinicType

valueCoding

object

required

system

string

required

Allowed values: https://fhir.nhs.uk/STU3/CodeSystem/eRS-ClinicType-1

Example: https://fhir.nhs.uk/STU3/CodeSystem/eRS-ClinicType-1

code

string

required

Example: HEART_FAILURE

object

IndicativeAppointmentWaitTimeLimit

Details the indicative appointment wait time limit value specified in a search criteria

name

string

required

Allowed values: indicativeAppointmentWaitTimeLimit

Example: indicativeAppointmentWaitTimeLimit

valueUnsignedInt

integer int32

required

Minimum: 0 (inclusive)

Example: 50

object

Postcode

Details the postcode value specified in a search criteria

name

string

required

Allowed values: postcode

Example: postcode

valueString

string

required

Example: LS1 2UT

object

DistanceLimit

Details the distance limit value specified in a search criteria

name

string

required

Allowed values: distanceLimit

Example: distanceLimit

valueUnsignedInt

integer int32

required

Minimum: 0 (inclusive)

Example: 123

object

ClinicalTerm

Details the clinical term that was specified in a search criteria

name

string

required

Allowed values: clinicalTerm

Example: clinicalTerm

valueCoding

object

required

system

string

required

Allowed values: http://snomed.info/sct

Example: http://snomed.info/sct

code

string

required

Example: 1003

object

NamedClinician

Details the named clinician that was specified in a search criteria

name

string

required

Allowed values: namedClinician

Example: namedClinician

valueIdentifier

object

required

system

string

required

Allowed values: http://fhir.nhs.net/Id/sds-user-id

Example: http://fhir.nhs.net/Id/sds-user-id

value

string

required

Example: 021600556514

object

AgeAndGenderAppropriate

Details the age and gender appropriate flag detailed in a search criteria

name

string

required

Allowed values: ageAndGenderAppropriate

Example: ageAndGenderAppropriate

valueBoolean

boolean

required

Example: true

object

CommissioningProvisioning

Details the commissioning provisioning flag detailed in a search criteria

name

string

required

Allowed values: commissioningProvisioning

Example: commissioningProvisioning

valueCoding

object

required

system

string

required

Allowed values: https://fhir.nhs.uk/STU3/CodeSystem/eRS-CommissioningProvisioning-1

Example: https://fhir.nhs.uk/STU3/CodeSystem/eRS-CommissioningProvisioning-1

code

string

required

Allowed values: ALL_AVAILABLE_FOR_BOOKING, ALL_SERVICES, LOCALLY_COMMISSIONABLE, NATIONALLY_AVAILABLE

Example: LOCALLY_COMMISSIONABLE

object

Organisation

Details the organisation that was specified in a search criteria

name

string

required

Allowed values: organisation

Example: organisation

valueIdentifier

object

required

system

string

required

Allowed values: https://directory.spineservices.nhs.uk/STU3/Organization

Example: https://directory.spineservices.nhs.uk/STU3/Organization

value

string

required

Example: R69

object

Place

Details the place that was specified in a search criteria

name

string

required

Allowed values: place

Example: place

valueString

string

required

Example: Leeds

object

eRS-Appointment

A booking of a healthcare event among patient(s), practitioner(s), related person(s) and/or device(s) for a specific date/time. This may result in one or more Encounter(s) (https://fhir.hl7.org.uk/STU3/StructureDefinition/CareConnect-Appointment-1)

string

required

Example: appointment

meta

object

required

profile

array

required

string

Allowed values: https://fhir.nhs.uk/STU3/StructureDefinition/eRS-Appointment-1, https://fhir.hl7.org.uk/STU3/StructureDefinition/CareConnect-Appointment-1

Example: https://fhir.nhs.uk/STU3/StructureDefinition/eRS-Appointment-1

language

string

Example: en

resourceType

string

required

Allowed values: Appointment

Example: Appointment

status

string

required

Allowed values: proposed, pending, booked, arrived, fulfilled, cancelled, noshow

Example: proposed

reason

array

nullable

Max items: 1

Min items: 1

object

coding

array

required

Max items: 1

Min items: 1

anyOf

object

eRS-ReviewReason

system

string

required

Allowed values: https://fhir.nhs.uk/STU3/CodeSystem/eRS-ReviewReason-1

Example: https://fhir.nhs.uk/STU3/CodeSystem/eRS-ReviewReason-1

code

string

required

Allowed values: NO_SLOTS_AT_SERVICE, SLOT_NOT_AVAILABLE, BOOKING_ATTEMPT_PROBLEM

Example: NO_SLOTS_AT_SERVICE

object

eRS-ReviewOutcome

system

string

required

Allowed values: https://fhir.nhs.uk/STU3/CodeSystem/eRS-ReviewOutcome-1

Example: https://fhir.nhs.uk/STU3/CodeSystem/eRS-ReviewOutcome-1

code

string

required

Allowed values: PROVIDER_CONVERTED_ADVICE_AND_GUIDANCE_ADMIN_TO_REFER, CANCEL_APPOINTMENT_ACTION_LATER, RETURN_TO_REFERRER_WITH_ADVICE, ACCEPT_REFER_BOOK_LATER

Example: PROVIDER_CONVERTED_ADVICE_AND_GUIDANCE_ADMIN_TO_REFER

display

string

nullable

Example: Provider Converted Advice and Guidance, Admin to Refer

description

string

required

Allowed values: e-Referral Appointment

Example: e-Referral Appointment

start

string date-time

nullable

Example: 2021-04-22T08:30Z

end

string date-time

nullable

Example: 2021-04-22T10:00Z

slot

array

nullable

Max items: 1

Min items: 0

object

reference

string

required

Example: Slot/11002001

created

string date-time

nullable

Example: 2021-04-20T12:17:35.128Z

comment

string

nullable

incomingReferral

array

nullable

required

Max items: 1

Min items: 0

object

reference

string

required

Example: ReferralRequest/000000070000/_history/14

participant

array

required

Field	Cardinality	Notes
`Patient`	`1..1`
`Service`	`1..1`
`AllocatedClinician`	`0..1`

Max items: 3

Min items: 2

anyOf

object

Patient

actor

object

identifier

object

required

system

string

required

Allowed values: http://fhir.nhs.net/Id/nhs-number

Example: http://fhir.nhs.net/Id/nhs-number

value

string

required

Example: 9912003888

status

string

Allowed values: accepted

Example: accepted

object

Service

actor

object

identifier

object

required

system

string

required

Allowed values: http://fhir.nhs.net/Id/ers-service

Example: http://fhir.nhs.net/Id/ers-service

value

string

required

Example: 11002

display

string

nullable

Example: Cardiology Triage Business Service

status

string

Allowed values: accepted

Example: accepted

object

AllocatedClinician

type

object

required

coding

array

required

Max items: 1

Min items: 1

object

system

string

required

Allowed values: http://hl7.org/fhir/ValueSet/encounter-participant-type

Example: http://hl7.org/fhir/ValueSet/encounter-participant-type

code

string

required

Allowed values: CON

Example: CON

actor

object

required

identifier

object

required

system

string

required

Allowed values: http://fhir.nhs.net/Id/sds-user-id

Example: http://fhir.nhs.net/Id/sds-user-id

value

string

required

Example: 021600556514

status

string

required

Allowed values: accepted

Example: accepted

object

DocumentReference

A reference to a document

meta

object

required

profile

array

required

string

Allowed values: https://fhir.nhs.uk/STU3/StructureDefinition/eRS-DocumentReference-1

Example: https://fhir.nhs.uk/STU3/StructureDefinition/eRS-DocumentReference-1

resourceType

string

required

Allowed values: DocumentReference

Example: DocumentReference

type

object

required

coding

array

object

system

string

required

Allowed values: https://fhir.nhs.uk/STU3/CodeSystem/eRS-AttachmentType-1

Example: https://fhir.nhs.uk/STU3/CodeSystem/eRS-AttachmentType-1

code

string

required

Allowed values: REFERRER, PROVIDER, ADVICE_REQUEST, GUIDANCE_RESPONSE

Example: REFERRER

display

string

required

Allowed values: Referrer, Provider, Advice Request, Guidance Response

Example: Referrer

status

string

required

Allowed values: current

Example: current

indexed

string date-time

required

Example: 2021-04-22T10:00Z

description

string

nullable

Example: upload png

content

array

required

Min items: 1

object

attachment

object

required

A reference to an already created Attachment (http://hl7.org/fhir/stu3/datatypes.html#Attachment)

contentType

string

required

e-Referral Service - FHIR API

Overview

Access modes

Users within the Health and Social Care Network (HSCN) who have smartcards

Users without access to the Health and Social Care Network (HSCN), or without access to smartcards

Who can use this API

Related APIs

API status and roadmap

Technology

Network access

Security and authorisation

Environments and testing

Sandbox testing

Integration testing

Onboarding

Endpoints

A004 - Retrieve reference data

Overview

Pre-requisites

Use case

Related endpoints

Sandbox test scenarios

Request

Path parameters

Headers

Response

HTTP status: 200

Headers

Body

Schema

HTTP status: 400

HTTP status: 401

HTTP status: 403

HTTP status: 404

HTTP status: 429

HTTP status: 500

A005 Retrieve Referral Request

Overview

Pre-requisites

Use case

Related endpoints

Sandbox test scenarios

Request

Path parameters

Headers

Response

HTTP status: 200

Headers

Body

Schema