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.

Page content

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

This API has two access modes:

Access mode Authentication via Functions Availability
Application-restricted, unattended access Signed JWT A004, A005, A006 and A007 Alpha
Healthcare worker, user-restricted access CIS2 All Endpoints Beta
Application-restricted, unattended access

This access mode has been introduced to allow a Partner application which has been registered with us and authenticated via signed JWT to interact with a subset of e-RS FHIR API endpoints in an unattended and read-only fashion. Application-restricted, unattended access should only be used when authenticating a human user (for example via smartcard) is not possible.

Writing changes (such as Create Referral) are not supported via this access mode.

Healthcare worker, user-restricted access

This access mode allows Partner applications to access e-RS FHIR API endpoints by authenticating users with NHS Care Identity Service 2 (CIS2).

This access mode must be used for writing changes (such as Create Referral).

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

HL7 V3 API - this API allows you to manage appointment slots for a Patient Administration System (PAS).

API status and roadmap

Application-restricted, unattended access

This access mode is in alpha, meaning:

  • it is available for testing in the Alpha environment only
  • we might make breaking changes

Healthcare worker, user-restricted access

The e-RS FHIR STU3 API is in beta when accessed 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.

Service level

This API is a gold service, meaning it is operational and supported 24 x 7 x 365.

For more details, see service levels.

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

Application-restricted, unattended access

This access mode is application-restricted, meaning we authenticate the calling application but not the end user.

You can only use this access mode when authenticating a human user (for example via smartcard) is not possible.

To use this access mode, use the following security pattern:

Healthcare worker, user-restricted access

This access mode is user-restricted, meaning an end user must be present, authenticated and authorised.

The end user must be:

To use this access mode, use one of the following security patterns:

Role and Organisation Validation

For most e-RS endpoints requests are made in the context of a specific authorised e-RS Role at a specific Organisation for the authenticated user.

The e-RS Role is supplied to the endpoint via the nhsd-ers-business-function request header.

The Organisation is supplied to the endpoint via the NHSD-End-User-Organisation-ODS request header.

Suitable values for these request headers can be obtained from the Practitioner Role Bundle returned by A030 - Retrieve e-RS business functions.

On Behalf Of User

If the SERVICE_PROVIDER_CLINICIAN_ADMIN role is used then the User ID of the Service Provider Clinician that the Admin is acting on behalf of must be supplied via the NHSD-eRS-On-Behalf-Of-User-ID header.

"On behalf of" is only supported for a Service Provider Clinician Admin (SPCA) acting on behalf of a Service Provider Clinician (SPC).

Environments and testing

Environment Base URL
Sandbox https://sandbox.api.service.nhs.uk/referrals/FHIR
Alpha See Alpha testing section below
Integration test https://int.api.service.nhs.uk/referrals/FHIR
Production https://api.service.nhs.uk/referrals/FHIR

Sandbox testing

Our sandbox environment:

  • is for developer education and early 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.

Alpha testing

Our alpha environment:

  • is available for early developer testing of future functionality
  • may experience breaking changes or downtime without advance notice, but only if we cannot avoid it
  • can be accessed by contacting nhserspartners@nhs.net

Integration testing

Our integration test environment:

  • is where the majority of your integration efforts will take place
  • is where we 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. We call this process onboarding.

Onboarding essentially involves connecting to the Path-to-Live (PTL) environments, assuring your solution and going live, in accordance with the Supplier Conformance Assessment List (SCAL) process.

In order to pass through the onboarding process as efficiently as possible, it is worth planning ahead.

When following the general SCAL process, please note:

In step 1: to use this API, you need to register with nhserspartners@nhs.net using Partner Registration and discuss your use case with us. You must also register with the API Management team via https://digital.nhs.uk/developer/getting-started to register your application.

In step 2: to request a SCAL, please ensure you have discussed your solution with the Partners service via nhserspartners@nhs.net, who will put you in touch with ersapi.assurance@nhs.net who are responsible for assurance of solutions that integrate with the e-RS FHIR API.

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

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

In step 12: to obtain a Connection Agreement, please liaise with interop.mgmt@nhs.net. You will need to have successfully passed witness testing with ersapi.assurance@nhs.net and obtained a Technical Conformance Certificate (TCC).

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, send your completed SCAL and TCC to interop.mgmt@nhs.net. To activate your application in production please contact us.

Endpoints

A004 - Retrieve reference data

get /STU3/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.

Supported security patterns

  • Application-restricted, unattended access
  • Healthcare worker, user-restricted access

Pre-requisites

Application-restricted access

In order to use this endpoint you must be an authenticated e-RS calling application.

Healthcare worker, user-restricted access

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

Use case

As an authenticated user or application

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 can use the Priority reference data to calculate when a patient can expect to be contacted by the service.

This is important because when a patient's appointment is deferred to a service to book, the patient may be informed of the date by which they can expect to be contacted. Similarly, in the case of a triage service, a letter may inform the patient of the date by which they can expect to be contacted.

You can calculate this date by:

  1. Obtaining the current priority of the referral (via A005 - Retrieve referral request) and its associated "deferToProviderContactDays" (for deferred-to services) or "triageContactDays" (for triage services). These represent the number of "working days" and do not include weekends
  2. Obtaining the datetime of the appointment resource, e.g. "created" : "2021-05-06T11:21:45.652Z"
  3. Adding the "working days" to the datetime of the appointment resource

For example:

  1. Given a referral with a priority of TWO_WEEK_WAIT and a "deferToProviderContactDays" of "2" for priority TWO_WEEK_WAIT
  2. If the appointment was created on Monday 03/01/2022 for a deferred-to service
  3. The calculated date when a patient can expect to be contacted by the service would be on or before 05/01/2022

Note that the "deferToProviderContactDays" and "triageContactDays" values are dynamic, and may change independently from one another, so the above calculation is for illustration purposes only.

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 and A038 - Retrieve appointment.

Documentation for other endpoints will reference this endpoint, where specific reference data is required.

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
Retrieve referral cancellation reason reference data codeSystemType=REFERRAL-CANCELLATION-REASON ReferralRequest reason type details
Retrieve appointment non-attendance reason reference data codeSystemType=APPOINTMENT-NON-ATTENDANCE-REASON Appointment non-attendance reason details
Retrieve priority reference data codeSystemType=PRIORITY Priority details

Request

Path parameters
Name Description
codeSystemType

String

The requested code system

Allowed values: SPECIALTY, APPOINTMENT-CANCELLATION-REASON, CLINIC-TYPE, REFERRAL-CANCELLATION-REASON, APPOINTMENT-NON-ATTENDANCE-REASON, PRIORITY

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-End-User-Organisation-ODS

String

The ODS code of the caller's Organisation.

Not allowed for application-restricted access.

Required for user-restricted access.

Example: R69

nhsd-ers-business-function

String

The e-RS Business Function of the caller.

Not allowed for application-restricted access.

Required for user-restricted access.

Allowed values: REFERRING_CLINICIAN, REFERRING_CLINICIAN_ADMIN, REFERRING_ADMIN, COMMISSIONER, SERVICE_PROVIDER_CLINICIAN_ADMIN, SERVICE_PROVIDER_CLINICIAN, SERVICE_PROVIDER_ADMIN, INFORMATION_ANALYST, BOOKING_MANAGER, ADDITIONAL_REQUIREMENTS_MANAGER

NHSD-eRS-On-Behalf-Of-User-ID

String

The (SDS) user ID of the user that the authenticating user wishes to act on behalf of (OBO).

"On behalf of" is only supported for a Service Provider Clinician Admin (SPCA) acting on behalf of a Service Provider Clinician (SPC).

Where an OBO User ID is supplied the authenticating user must be an SPCA and the OBO User ID must be that of an appropriate SPC.

Not allowed for application-restricted access.

Required for user-restricted access where the Service Provider Clinician Admin Business Function is used for authentication.

Example: 021600556514

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

Content-Type

String

Indicates the media type of the associated resource.

Allowed values: application/fhir+json

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 Cancellation Reason Reference Data

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

ReferralRequest Cancellation Reason Reference Data

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

Appointment Non-attendance Reason Reference Data

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

Priority 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, REFERRAL-CANCELLATION-REASON, APPOINTMENT-NON-ATTENDANCE-REASON, PRIORITY
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
resourceType
string
required
Allowed values: CodeSystem
url
string
required
Example: _baseUrl_/STU3/CodeSystem/SPECIALTY
name
string
required
Description of the code system
Allowed values: e-RS Appointment Cancellation Reason, e-RS Specialty, e-RS Clinic Type, e-RS ReferralRequest Cancellation Reason, e-RS Appointment Non-attendance Reason, e-RS Priority
status
string
required
Allowed values: active
date
string date-time
required
publisher
string
Allowed values: e-Referral Service
description
string
required
Example: e-RS Specialty
copyright
string
Example: Copyright © 2016 HL7 UK
content
string
required
Allowed values: 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
Usage APPOINTMENT-CANCELLATION-REASON
CommentIsMandatory APPOINTMENT-CANCELLATION-REASON / REFERRAL-CANCELLATION-REASON
BusinessFunction APPOINTMENT-CANCELLATION-REASON / REFERRAL-CANCELLATION-REASON
CanCancelAppointment REFERRAL-CANCELLATION-REASON
ReferrerUsage REFERRAL-CANCELLATION-REASON
DeferToProviderContactDays PRIORITY
TriageContactDays PRIORITY
anyOf
object
Effective from date
code
string
required
Allowed values: effectiveFrom
uri
string
required
Allowed values: https://fhir.nhs.uk/STU3/CodeSystem/eRS-Concept-Properties-1#effectiveFrom
type
string
required
Allowed values: dateTime
object
Effective to date
code
string
required
Allowed values: effectiveTo
uri
string
required
Allowed values: https://fhir.nhs.uk/STU3/CodeSystem/eRS-Concept-Properties-1#effectiveTo
type
string
required
Allowed values: dateTime
object
Specialty

This will only be returned when codeSystemType is CLINIC-TYPE
code
string
required
Allowed values: specialty
uri
string
required
Allowed values: https://fhir.nhs.uk/STU3/CodeSystem/eRS-Concept-Properties-1#specialty
type
string
required
Allowed values: Coding
object
Appointment Booking Cancellation Reason Type

This will only be returned when codeSystemType is APPOINTMENT-CANCELLATION-REASON
code
string
required
Allowed values: appointmentBookingCancellationReasonType
uri
string
required
Allowed values: https://fhir.nhs.uk/STU3/CodeSystem/eRS-Concept-Properties-1#appointmentBookingCancellationReasonType
type
string
required
Allowed values: Coding
object
deprecated
Will Cancel Whole Request

This will only be returned when codeSystemType is APPOINTMENT-CANCELLATION-REASON
code
string
required
Allowed values: willCancelWholeRequest
uri
string
required
Allowed values: https://fhir.nhs.uk/STU3/CodeSystem/eRS-Concept-Properties-1#willCancelWholeRequest
type
string
required
Allowed values: boolean
object
Usage

Details how the current code system should be used
code
string
required
Allowed values: usage
uri
string
required
Allowed values: https://fhir.nhs.uk/STU3/CodeSystem/eRS-Concept-Properties-1#usage
type
string
required
Allowed values: Coding
object
Comment Is Mandatory

This will only be returned when codeSystemType is APPOINTMENT-CANCELLATION-REASON or REFERRAL-CANCELLATION-REASON
code
string
required
Allowed values: commentIsMandatory
uri
string
required
Allowed values: https://fhir.nhs.uk/STU3/CodeSystem/eRS-Concept-Properties-1#commentIsMandatory
type
string
required
Allowed values: boolean
object
BusinessFunction

Details which Business functions are able to use the current code system
code
string
required
Allowed values: businessFunction
uri
string
required
Allowed values: https://fhir.nhs.uk/STU3/CodeSystem/eRS-Concept-Properties-1#businessFunction
type
string
required
Allowed values: Coding
object
CanCancelAppointment

This will only be returned when codeSystemType is REFERRAL-CANCELLATION-REASON
code
string
required
Allowed values: canCancelAppointment
uri
string
required
Allowed values: https://fhir.nhs.uk/STU3/CodeSystem/eRS-Concept-Properties-1#canCancelAppointment
type
string
required
Allowed values: boolean
object
ReferrerUsage

This will only be returned when codeSystemType is REFERRAL-CANCELLATION-REASON
code
string
required
Allowed values: referrerUsage
uri
string
required
Allowed values: https://fhir.nhs.uk/STU3/CodeSystem/eRS-Concept-Properties-1#referrerUsage
type
string
required
Allowed values: Coding
object
Defer to Provider Contact Days

This will only be returned when codeSystemType is PRIORITY
code
string
required
Allowed values: deferToProviderContactDays
uri
string
required
Allowed values: https://fhir.nhs.uk/STU3/CodeSystem/eRS-Concept-Properties-1#deferToProviderContactDays
type
string
required
Allowed values: integer
object
Triage Contact Days

This will only be returned when codeSystemType is PRIORITY
code
string
required
Allowed values: triageContactDays
uri
string
required
Allowed values: https://fhir.nhs.uk/STU3/CodeSystem/eRS-Concept-Properties-1#triageContactDays
type
string
required
Allowed values: integer
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
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
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
Referral Cancellation Reason INTEND_PRIVATE
Appointment Non-attendance Reason PATIENT_ILL
Priority ROUTINE
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
Referral Cancellation Reason Intend to go private
Appointment Non-attendance Reason Patient ill
Priority Routine
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
Usage APPOINTMENT-CANCELLATION-REASON
CommentIsMandatory APPOINTMENT-CANCELLATION-REASON/REFERRAL-CANCELLATION-REASON
businessFunction APPOINTMENT-CANCELLATION-REASON/REFERRAL-CANCELLATION-REASON
CanCancelAppointment REFERRAL-CANCELLATION-REASON
RequestCancellationReferrerUsage REFERRAL-CANCELLATION-REASON
DeferToProviderContactDays PRIORITY
TriageContactDays PRIORITY
anyOf
object
deprecated
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/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
code
string
required
Example: PROVIDER_REJECT
object
AppointmentCancellationUsage

This will only be returned when codeSystemType is APPOINTMENT-CANCELLATION-REASON
code
string
required
Allowed values: usage
valueCoding
object
required
system
string
required
Allowed values: https://fhir.nhs.uk/STU3/CodeSystem/eRS-AppointmentCancellationReasonUsage-1
code
string
required
Allowed values: REJECT, CANCEL
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
BusinessFunction

This will only be returned when codeSystemType is APPOINTMENT-CANCELLATION-REASON or REFERRAL-CANCELLATION-REASON
code
string
required
Allowed values: businessFunction
valueCoding
object
required
system
string
required
Allowed values: https://fhir.nhs.uk/STU3/CodeSystem/eRS-BusinessFunction-1
code
string
required
Example: REFERRING_CLINICIAN
object
CanCancelAppointment

This will only be returned when codeSystemType is REFERRAL-CANCELLATION-REASON
code
string
required
Allowed values: canCancelAppointment
valueBoolean
boolean
required
object
RequestCancellationReferrerUsage

This will only be returned when codeSystemType is REFERRAL-CANCELLATION-REASON
code
string
required
Allowed values: referrerUsage
valueCoding
object
required
system
string
required
Allowed values: https://fhir.nhs.uk/STU3/CodeSystem/eRS-ReferralRequestCancellationReasonUsage-1
code
string
required
Allowed values: CANCEL_REFERRAL
object
Defer to provider contact days

This will only be returned when codeSystemType is PRIORITY
code
string
required
Allowed values: deferToProviderContactDays
valueInteger
integer
required
Example: 10
object
Triage contact days

This will only be returned when codeSystemType is PRIORITY
code
string
required
Allowed values: triageContactDays
valueInteger
integer
required
Example: 10
HTTP status: 401

Unauthorized

HTTP status: 403

Forbidden

HTTP status: 404

Not Found

HTTP status: 406

Not Acceptable

Headers
Name Description
Content-Type

String

Indicates the media type of the associated resource.

Allowed values: text/plain;charset=utf-8

Body

Content type: text/plain;charset=utf-8

Schema

Name Description
string
HTTP status: 429

The e-Referral service APIs limit the number of transactions you can make per unit of time. This protects our service against excessive use and denial-of-service (DoS) attacks, and is also to encourage you to use our APIs efficiently.

Our standard rate limit for the production environment is 10 requests per second per application. APIs associated with the "Binary" resource are further restricted to 2 requests per second per application. If you go over the rate limit you'll receive a response with an HTTP status of 429 (Too Many Requests).

Our path-to-live environments have very low rate limits. They are for functional testing only - you should not use them for performance testing.

If you have problems with rate limits, contact us to discuss your application design and volumetrics, and to see whether it's appropriate to raise your rate limit.

If a 429 response is received, indicating a request has been rate limited, then you must back off and retry with exponentially increasing periods between requests. Once a request is successful again, then you may continue to send requests inline with the documented rate limits.

Example:

  • Receive a 429 response
  • Wait 1s and resend, but still receive a 429
  • Wait 2s and resend, but still receive a 429
  • Wait 4s, request is successful
  • Return to normal request cadence
HTTP status: 500

Internal Server Error

A005 - Retrieve referral request

get /STU3/ReferralRequest/{ubrn}

Overview

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

During the lifecycle of a referral, the state of the referral may change multiple times. To help with understanding the state of a referral, we provide an "at a glance" summary of the referral as detailed below:

Code returned via https://fhir.nhs.uk/STU3/CodeSystem/eRS-ReferralState-1 Description
APPT_CANCELLED_BY_PATIENT The referral's most recent appointment was cancelled at the request of, or directly by, a patient
APPT_CANCELLED_BY_PROVIDER The referral's most recent appointment was cancelled by the service provider
ASSESSMENT_RESULT A service provider has reviewed and drafted, or submitted a clinical assessment for the referral
AWAITING_TRIAGE The triage referral is currently pending review with a service provider
BOOKED This referral's appointment indicates a date and time with a service
CANCELLED_REFERRAL The referral has been cancelled and cannot be progressed any further
DEFERRED_TO_PROVIDER The service provider will arrange the patient’s appointment
DID_NOT_ATTEND The patient did not attend their last appointment
NOT_BOOKED The referral is currently not booked, there is currently no planned patient encounter
REJECTED The referral was rejected by a provider at their service
TRIAGE_RESPONSE A service has passed the referral back to the referrer, with advice
TRIAGED_PROVIDER_TO_ACTION The service provider has recorded a review decision, with the intention of processing this referral

Some referral states may also have a reason and some reasons may also have a comment. These are described below:

Reason

  • The reason is always connected to the current state. This means the reason is likely to change each time the state changes. You cannot currently retrieve previous versions of a referral.
  • This reason may have been selected by a clinician or automatically applied by the e-RS system at the time the state was persisted.
  • A reason can be dynamic reference data, from any of the following sets of reference data: APPOINTMENT-CANCELLATION-REASON, REFERRAL-CANCELLATION-REASON, APPOINTMENT-NON-ATTENDANCE-REASON. These are retrievable from A004 - Retrieve reference data.
  • A reason may be static reference data.

Comments

  • The comment is always connected to the current reason, and state. This means the comment is likely to change as the state changes.

Supported security patterns

  • Application-restricted access
  • Healthcare worker, user-restricted access

Pre-requisites

Application-restricted access

In order to use this endpoint you must be an authenticated e-RS calling application.

Healthcare worker, user-restricted access

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

  • REFERRING_CLINICIAN
  • REFERRING_CLINICIAN_ADMIN
  • SERVICE_PROVIDER_CLINICIAN
  • SERVICE_PROVIDER_CLINICIAN_ADMIN

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

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

You can retrieve reference data used in viewing a referral using A004 - Retrieve reference data

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-End-User-Organisation-ODS

String

The ODS code of the caller's Organisation.

Not allowed for application-restricted access.

Required for user-restricted access.

Example: R69

nhsd-ers-business-function

String

The e-RS Business Function of the caller.

Not allowed for application-restricted access.

Required for user-restricted access.

Allowed values: REFERRING_CLINICIAN, REFERRING_CLINICIAN_ADMIN, REFERRING_ADMIN, COMMISSIONER, SERVICE_PROVIDER_CLINICIAN_ADMIN, SERVICE_PROVIDER_CLINICIAN, SERVICE_PROVIDER_ADMIN, INFORMATION_ANALYST, BOOKING_MANAGER, ADDITIONAL_REQUIREMENTS_MANAGER

NHSD-eRS-On-Behalf-Of-User-ID

String

The (SDS) user ID of the user that the authenticating user wishes to act on behalf of (OBO).

"On behalf of" is only supported for a Service Provider Clinician Admin (SPCA) acting on behalf of a Service Provider Clinician (SPC).

Where an OBO User ID is supplied the authenticating user must be an SPCA and the OBO User ID must be that of an appropriate SPC.

Not allowed for application-restricted access.

Required for user-restricted access where the Service Provider Clinician Admin Business Function is used for authentication.

Example: 021600556514

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"

Content-Type

String

Indicates the media type of the associated resource.

Allowed values: application/fhir+json

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
versionId
string
required
Example: 3
resourceType
string
required
Allowed values: 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
id
string
Example: shortlist
status
string
required
Allowed values: current
mode
string
required
Allowed values: snapshot
meta
object
required
profile
array
required
string
Allowed values: 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
meta
object
required
profile
array
required
string
Allowed values: https://fhir.nhs.uk/STU3/StructureDefinition/eRS-ServiceSearchCriteria-Parameters-1
resourceType
string
required
Allowed values: 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 This parameter is not included in the response when retrieving the service search criteria.
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
valueCoding
object
required
system
string
required
Allowed values: https://fhir.nhs.uk/STU3/CodeSystem/eRS-Priority-1
code
string
required
Allowed values: ROUTINE, URGENT, TWO_WEEK_WAIT
display
string
nullable

display value is returned in response from the server

Example: Urgent
object
Specialty

Details the specialty parameter
name
string
required
Allowed values: specialty
valueCoding
object
required
system
string
required
Example: _baseUrl_/STU3/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
valueCoding
object
required
system
string
required
Allowed values: 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
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
valueString
string
required
Example: LS1 2UT
object
DistanceLimit

Details the distance limit value specified in a search criteria
name
string
required
Allowed values: 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
valueCoding
object
required
system
string
required
Allowed values: 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
valueIdentifier
object
required
system
string
required
Allowed values: 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
valueBoolean
boolean
required
Example: true
object
CommissioningProvisioning

Details the commissioning provisioning flag detailed in a search criteria
name
string
required
Allowed values: commissioningProvisioning
valueCoding
object
required
system
string
required
Allowed values: https://fhir.nhs.uk/STU3/CodeSystem/eRS-CommissioningProvisioning-1
code
string
required
Allowed values: ALL_AVAILABLE_FOR_BOOKING, ALL_SERVICES, LOCALLY_COMMISSIONABLE, NATIONALLY_AVAILABLE
object
Organisation

Details the organisation that was specified in a search criteria
name
string
required
Allowed values: organisation
valueIdentifier
object
required
system
string
required
Allowed values: 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
valueString
string
required
Example: Leeds
extension
array
nullable
Field Cardinality Notes
Extension-eRS-Shortlist-SearchCriteria 1..1 The SearchCriteria used to retrieve the services included in the Shortlist
Max items: 1
Min items: 1
anyOf
object
Extension-eRS-Shortlist-SearchCriteria

Extension to detail the SearchCriteria associated with a Shortlist
url
string
required
Allowed values: https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-Shortlist-SearchCriteria-1
valueReference
object
required
reference
string
required
Example: #serviceSearchCriteria
resourceType
string
required
Allowed values: 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
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
meta
object
required
profile
array
required
string
Allowed values: https://fhir.nhs.uk/STU3/StructureDefinition/eRS-ServiceSearchCriteria-Parameters-1
resourceType
string
required
Allowed values: 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 This parameter is not included in the response when retrieving the service search criteria.
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
valueCoding
object
required
system
string
required
Allowed values: https://fhir.nhs.uk/STU3/CodeSystem/eRS-Priority-1
code
string
required
Allowed values: ROUTINE, URGENT, TWO_WEEK_WAIT
display
string
nullable

display value is returned in response from the server

Example: Urgent
object
Specialty

Details the specialty parameter
name
string
required
Allowed values: specialty
valueCoding
object
required
system
string
required
Example: _baseUrl_/STU3/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
valueCoding
object
required
system
string
required
Allowed values: 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
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
valueString
string
required
Example: LS1 2UT
object
DistanceLimit

Details the distance limit value specified in a search criteria
name
string
required
Allowed values: 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
valueCoding
object
required
system
string
required
Allowed values: 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
valueIdentifier
object
required
system
string
required
Allowed values: 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
valueBoolean
boolean
required
Example: true
object
CommissioningProvisioning

Details the commissioning provisioning flag detailed in a search criteria
name
string
required
Allowed values: commissioningProvisioning
valueCoding
object
required
system
string
required
Allowed values: https://fhir.nhs.uk/STU3/CodeSystem/eRS-CommissioningProvisioning-1
code
string
required
Allowed values: ALL_AVAILABLE_FOR_BOOKING, ALL_SERVICES, LOCALLY_COMMISSIONABLE, NATIONALLY_AVAILABLE
object
Organisation

Details the organisation that was specified in a search criteria
name
string
required
Allowed values: organisation
valueIdentifier
object
required
system
string