Skip to main content

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:

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

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

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.

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

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.

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:

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

Clinic Type Reference Data

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

Appointment Reference Data

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

Schema

Name Description
object
id
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
Example: Copyright © 2016 HL7 UK
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
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
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`

`ReferralRequest` booked to directly-bookable service

`ReferralRequest` booked to indirectly-bookable service

`ReferralRequest` deferred to service provider for booking

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

`ReferralRequest` with related ReferralRequest

Schema

Name Description
object
eRS-ReferralRequest
id
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

id
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

id
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)

id
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