Skip to main content

Electronic Prescription Service - FHIR API

Access the Electronic Prescription Service (EPS) - the national service used to send electronic prescriptions from secondary care (outpatient) prescribers to dispensers such as pharmacies. You can prepare a prescription for signing, create a prescription or cancel a prescription.

Page content

Overview

Use this API to access the Electronic Prescription Service (EPS) - the national service used to send electronic prescription messages between prescribers and community dispensers.

As a prescriber

You can:

  • create a primary care prescription
  • cancel a primary care prescription
  • create a secondary care (outpatient) prescription
  • cancel a secondary care (outpatient) prescription
  • create a secondary care (homecare) prescription
  • cancel a secondary care (homecare) prescription
  • view a prescription's summary information

You cannot currently use this API to:

  • create a tertiary care (homecare) prescription
  • cancel a tertiary care (homecare) prescription

As a dispenser

You can:

  • download an individual prescription from EPS
  • download a batch of prescriptions from EPS
  • verify a prescription's signature
  • return a prescription to EPS
  • submit a dispense notification to EPS
  • withdraw a dispense notification from EPS
  • submit a dispense claim
  • view a prescription's summary information

You cannot currently use this API to:

  • view a prescription's detailed dispense history

Who can use this API

This API can only be used where there is a legal basis to do so. Make sure you have a valid use case before you go too far with your development. You must do this before you can go live (see ‘Onboarding’ below).

Related APIs

The following APIs also give access to the Electronic Prescription Service:

The following APIs may be required when accessing the Electronic Prescription Service:

API status and roadmap

The immediate priority of EPS development is to support the rollout of the next-gen FHIR APIs for primary care and secondary care prescribing and dispensing. Alongside this we will be working on integrating a new FHIR-compliant prescription tracker into the next gen APIs.

Prescribing API

This API supports two types of prescribing medication workflows

Primary care medication workflow

In a primary care medication workflow, the prescription is sent from a primary care service, such as a GP practice to a pharmacy. For this workflow, the API is in beta, meaning:

  • it is available in integration and production
  • we might make breaking changes, but only if we cannot avoid it, and we will give advance notice

Secondary care medication workflow

In a secondary care medication workflow, the prescription is sent from a secondary care service, such as an NHS hospital to a pharmacy. For this workflow, the API is in beta, meaning:

  • it is available in integration and production
  • we might make breaking changes, but only if we cannot avoid it, and we will give advance notice

Dispensing API

This API supports two types of dispensing medication workflows

Community pharmacy workflow

In a community pharmacy workflow, prescriptions can be released (downloaded) from Spine, updated, dispensed, and then claimed by the pharmacy. For this workflow, the API is in alpha, meaning:

  • it is available for testing in the integration environment, but not for production use
  • we might make breaking changes, but only if we cannot avoid it, and we will give advance notice

Homecare dispenser workflow

In a homecare dispenser workflow, prescriptions can be released (downloaded) from Spine, updated, and dispensed by the dispenser. For this workflow, the API is in alpha, meaning:

  • it is available for testing in the integration environment, but not for production use
  • we might make breaking changes, but only if we cannot avoid it, and we will give advance notice

Roadmap

To see our roadmap, or to suggest, comment or vote on features for this API, see our interactive product backlog.

If you have any other queries, please contact us.

Service level

This API is a bronze service, meaning it is operational and supported only during business hours (8am to 6pm), Monday to Friday excluding bank holidays.

For more details, see service levels.

Technology

This API conforms to the FHIR global standard for health care data exchange. Specifically, it is aligned with FHIR UK Core, which is built on FHIR Release 4.

You do not need to know much about FHIR to use this API - FHIR APIs are just RESTful APIs that follow specific rules. In particular:

  • resource names are capitalised and singular, for example /Patient not /patients
  • array names are singular, for example line not lines for address lines
  • data items that are country-specific and thus not included in the FHIR global base resources are usually wrapped in an extension object

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

User-restricted access

The EPS APIs are mostly user-restricted, meaning we authenticate the end user.

EPS only supports CIS2 combined authentication and authorisation, do not use separate authentication and authorisation or try to authenticate using NHS Login.

The only interaction that is not user-restricted is bulk releasing nominated prescriptions.

Application-restricted access

You can use this access mode whilst bulk releasing nominated prescriptions whilst dispensing. To use this access mode, use the Application-restricted RESTful API - signed JWT authentication security pattern.

Environment and testing

Environment Base URL
Sandbox https://sandbox.api.service.nhs.uk/electronic-prescriptions
Integration test https://int.api.service.nhs.uk/electronic-prescriptions
Production https://api.service.nhs.uk/electronic-prescriptions

Sandbox testing

Our sandbox environment:

  • is for early developer testing
  • only covers a limited set of scenarios
  • is stateless, so it does not actually persist any updates
  • is open access, so does not allow you to test authorisation

For details of sandbox testing, or to try out the sandbox using our "Try this API" feature, see the documentation for each endpoint.

Integration testing

Our integration test environment:

  • is for formal integration testing
  • is stateful, so persists updates
  • includes authorisation, with smartcard and non-smartcard options

For more details see integration testing with our RESTful APIs.

Onboarding

You need to get your software approved by us before it can go live with this API. We call this onboarding. We are hoping to make the onboarding process as lightweight and as self-service as possible. The onboarding process can sometimes be quite long, so it’s worth planning well ahead.

To begin the onboarding process please download and complete the EPS use case form and email it to us at epsonboarding@nhs.net.

Resources

Use the Digital Medicines Implementation Guide to assist with your integration. This is the FHIR specification for Digital Medicines starting with the assets required for an electronic prescription sent to the EPS.

For further guidance on prescribing, see EPS prescribing developer guide.

Errors

API wide errors

HTTP Status Error Code Description
400 MISSING_FIELD A required field is missing within the request, see display field in response.
400 INVALID_VALUE Invalid value in message.
400 INCORRECT_RESOURCETYPE FHIR resource has an incorrect resourceType.
404 NOT_FOUND Route not found.

Platform wide errors

HTTP Status Error Code Description
401 ACCESS_DENIED User does not have permission for a particular request.
403 FORBIDDEN Insufficient authorization.
404 NOT_FOUND Resource not found.

For further details on common HTTP status codes, see 5xx status codes

Endpoints

Encode prescription data

post /FHIR/R4/$prepare

Overview

Use this endpoint to convert a FHIR prescription-order message into HL7 V3 signature fragments which can then be signed by the prescriber.

Request

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

String

The user role ID (URID) for the current session. Also known as a user role profile ID (URPID).

If you are using User-restricted RESTful APIs - NHS login separate authentication and authorisation, see determine the user's role for guidance.

This field is optional.

Pattern: /^[0-9]+$/

Example: 555254240100

X-Request-ID

String

A globally unique identifier (GUID) for the request, which we use to de-duplicate repeated requests and to trace the request if you contact our helpdesk.

Must be a universally unique identifier (UUID) (ideally version 4).

Mirrored back in a response header.

If you re-send a failed request, use the same value in this header.

Required in all environments except sandbox.

Pattern: /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/

Example: 60E0B220-8136-4CA5-AE46-1D97EF59D068

Required
X-Correlation-ID

String

An optional ID which you can use to track transactions across multiple systems. It can have any value, but we recommend avoiding . characters.

Mirrored back in a response header.

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

Body
Required

Content type: application/fhir+json

Example

A valid secondary care prepare request. More examples of this message can be found here.

Schema

Name Description
object

Response

HTTP status: 200

Successful conversion.

Body

Content type: application/fhir+json

Example

A successful response to a prepare request.

Schema

Name Description
object

A response from the /$prepare endpoint.
resourceType
string
Allowed values: Parameters
parameter
array
oneOf
object
name
string
Allowed values: digest
valueString
string

The Prescription Information that requires signing.

Example: PFNpZ25lZEluZm8geG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvMDkveG1sZHNpZyMiPjxDYW5vbmljYWxpemF0aW9uTWV0aG9kIEFsZ29yaXRobT0iaHR0cDovL3d3dy53My5vcmcvMjAwMS8xMC94bWwtZXhjLWMxNG4jIj48L0Nhbm9uaWNhbGl6YXRpb25NZXRob2Q+PFNpZ25hdHVyZU1ldGhvZCBBbGdvcml0aG09Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvMDkveG1sZHNpZyNyc2Etc2hhMSI+PC9TaWduYXR1cmVNZXRob2Q+PFJlZmVyZW5jZT48VHJhbnNmb3Jtcz48VHJhbnNmb3JtIEFsZ29yaXRobT0iaHR0cDovL3d3dy53My5vcmcvMjAwMS8xMC94bWwtZXhjLWMxNG4jIj48L1RyYW5zZm9ybT48L1RyYW5zZm9ybXM+PERpZ2VzdE1ldGhvZCBBbGdv
object
name
string
Allowed values: timestamp
valueString
string date-time
Example: 2021-05-07T14:47:47Z
object
name
string
Allowed values: algorithm
valueString
string
Allowed values: RS1
HTTP status: 4XX

Invalid request.

Body

Content type: application/fhir+json

Example

An error response to a prepare request.

Schema

Name Description
object

Outcome of an operation that does not result in a resource or bundle being returned (for example, error, async/batch submission).
resourceType
string

FHIR Resource Type.

Allowed values: OperationOutcome
issue
array

List of issues that have occurred.

Min items: 1
object
severity
string
required

Severity of the error.

Allowed values: fatal, error, warning, information
code
string
required

FHIR error code.

Allowed values: invalid, structure, required, value, invariant, security, login, unknown, expired, forbidden, suppressed, processing, not-supported, duplicate, multiple-matches, not-found, deleted, too-long, code-invalid, extension, too-costly, business-rule, conflict, transient, lock-error, no-store, exception, timeout, incomplete, throttled, informational
details
object

Internal error code.
coding
array
object
system
string

URI of the coding system specification.

Example: https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode
version
string

Version of the coding system in use.

Example: 1
code
string

Symbol in syntax defined by the system.

Example: INVALID_VALUE
display
string

Representation defined by the system.

Example: Provided value is invalid
expression
string

FHIRPath of element(s) related to the error.

Example: Patient.name.given

Create a new prescription

post /FHIR/R4/$process-message#prescription-order

Overview

Use this endpoint to send a prescription-order message to EPS.

The effect of calling this endpoint depends on the type of the message, which is determined by the MessageHeader resource. To create a prescription, send a prescription-order message. The message must include a digital signature.

Note that the #prescription-order in the URL has been added to distinguish this from the other operations which can be performed using the $process-message endpoint. It is not required in requests to the API.

Request

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

String

The user role ID (URID) for the current session. Also known as a user role profile ID (URPID).

If you are using User-restricted RESTful APIs - NHS login separate authentication and authorisation, see determine the user's role for guidance.

This field is optional.

Pattern: /^[0-9]+$/

Example: 555254240100

X-Request-ID

String

A globally unique identifier (GUID) for the request, which we use to de-duplicate repeated requests and to trace the request if you contact our helpdesk.

Must be a universally unique identifier (UUID) (ideally version 4).

Mirrored back in a response header.

If you re-send a failed request, use the same value in this header.

Required in all environments except sandbox.

Pattern: /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/

Example: 60E0B220-8136-4CA5-AE46-1D97EF59D068

Required
X-Correlation-ID

String

An optional ID which you can use to track transactions across multiple systems. It can have any value, but we recommend avoiding . characters.

Mirrored back in a response header.

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

Body
Required

Content type: application/fhir+json

Example

A valid secondary care prescription-order message.

Schema

Name Description
object

Response

HTTP status: 200

Successfully submitted.

Body

Content type: application/fhir+json

Example

A successful response to a prescription-order, dispense-notification or dispense-claim request.

Schema

Name Description
object
HTTP status: 4XX

An error occurred as follows:

HTTP status Error code Description
400 BAD_REQUEST Invalid request.
Body

Content type: application/fhir+json

Example

An error response.

Schema

Name Description
object

Download prescriptions

post /FHIR/R4/Task/$release

Overview

Use this endpoint to download prescriptions from Spine that are available for dispensing. You can download a single prescription using the prescription's ID, or download up to 25 prescriptions (per request) nominated to a dispenser using the dispenser's ODS code.

Send a Task-release message to this endpoint to download the prescription.

Request

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

String

The user role ID (URID) for the current session. Also known as a user role profile ID (URPID).

If you are using User-restricted RESTful APIs - NHS login separate authentication and authorisation, see determine the user's role for guidance.

This field is optional.

Pattern: /^[0-9]+$/

Example: 555254240100

X-Request-ID

String

A globally unique identifier (GUID) for the request, which we use to de-duplicate repeated requests and to trace the request if you contact our helpdesk.

Must be a universally unique identifier (UUID) (ideally version 4).

Mirrored back in a response header.

If you re-send a failed request, use the same value in this header.

Required in all environments except sandbox.

Pattern: /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/

Example: 60E0B220-8136-4CA5-AE46-1D97EF59D068

Required
X-Correlation-ID

String

An optional ID which you can use to track transactions across multiple systems. It can have any value, but we recommend avoiding . characters.

Mirrored back in a response header.

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

Body
Required

Content type: application/fhir+json

Example

A valid release request. More examples of this message can be found here.

Schema

Name Description
object

Response

HTTP status: 200

Successfully downloaded a prescription for dispensing.

Body

Content type: application/fhir+json

Example

A successful response to a release request.

Schema

Name Description
object
HTTP status: 4XX

An error occurred as follows:

HTTP status Error code Description
400 BAD_REQUEST Invalid request.
400 PRESCRIPTION_WITH_ANOTHER_DISPENSER Prescription is with another dispenser. See OperationOutcome.issue.diagnostics for more information about owning pharmacy.
Body

Content type: application/fhir+json

Examples

An error response due to requested prescription not being found.

An error response due to the prescription being released by another dispenser.

Schema

Name Description
object

To verify a prescription's signature

post /FHIR/R4/$verify-signature

Overview

Use this endpoint to verify a prescription's signature to ensure that the signature is valid, and that it matches the prescription it is attached to. This endpoint is expected to be used immediately after downloading prescriptions. Send the response message from the release endpoint to this endpoint. The signatures on these prescriptions will be verified.

The endpoint will return a set of (up to 25) verify responses associated with the bundle of prescriptions sent to the endpoint for verification.

Request

Headers
Name Description
Authorization

String (^Bearer\ [[:ascii:]]+$)

An OAuth 2.0 bearer token.

Required in all environments except sandbox.

Example: Bearer g1112R_ccQ1Ebbb4gtHBP1aaaNM

Required
X-Request-ID

String

A globally unique identifier (GUID) for the request, which we use to de-duplicate repeated requests and to trace the request if you contact our helpdesk.

Must be a universally unique identifier (UUID) (ideally version 4).

Mirrored back in a response header.

If you re-send a failed request, use the same value in this header.

Required in all environments except sandbox.

Pattern: /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/

Example: 60E0B220-8136-4CA5-AE46-1D97EF59D068

Required
X-Correlation-ID

String

An optional ID which you can use to track transactions across multiple systems. It can have any value, but we recommend avoiding . characters.

Mirrored back in a response header.

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

Body
Required

Content type: application/fhir+json

Example

A valid signature verification request.

Schema

Name Description
object

Response

HTTP status: 200

Successfully verified the prescription signature, signature may still be invalid.

Body

Content type: application/fhir+json

Example

A successful response to a verify signature request, showing a failure to verify the signature as correct.

Schema

Name Description
object
HTTP status: 4XX

An error occurred as follows:

HTTP status Error code Description
400 BAD_REQUEST Invalid request.
Body

Content type: application/fhir+json

Example

An error response to a verify signature request.

Schema

Name Description
object

Mark a prescription as dispensed

post /FHIR/R4/$process-message#dispense-notification

Overview

Dispense Notification

Use this endpoint to send a dispense-notification message to EPS.

The effect of calling this endpoint depends on the type of the message, which is determined by the MessageHeader resource. To mark a prescription as partially or fully dispensed, send a dispense-notification message.

Note that the #dispense-notification in the URL has been added to distinguish this from the other operations which can be performed using the $process-message endpoint. It is not required in requests to the API.

Amend Dispense Notification

The same endpoint can be used to amend a previous dispense notification. The same message structure is used with the addition of a replacementOf extension in the MessageHeader, referencing the identifier of the previous dispense notifcation to be amended. Only the most recent dispense notification can be amended. To amend other dispense notifications please use the Withdraw endpoint, to withdraw all dispense notifications issued after the amend target, and then amend if necessary.

More information can be found on the fhir documentation.

Request

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

String

The user role ID (URID) for the current session. Also known as a user role profile ID (URPID).

If you are using User-restricted RESTful APIs - NHS login separate authentication and authorisation, see determine the user's role for guidance.

This field is optional.

Pattern: /^[0-9]+$/

Example: 555254240100

X-Request-ID

String

A globally unique identifier (GUID) for the request, which we use to de-duplicate repeated requests and to trace the request if you contact our helpdesk.

Must be a universally unique identifier (UUID) (ideally version 4).

Mirrored back in a response header.

If you re-send a failed request, use the same value in this header.

Required in all environments except sandbox.

Pattern: /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/

Example: 60E0B220-8136-4CA5-AE46-1D97EF59D068

Required
X-Correlation-ID

String

An optional ID which you can use to track transactions across multiple systems. It can have any value, but we recommend avoiding . characters.

Mirrored back in a response header.

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

Body
Required

Content type: application/fhir+json

Example

A valid secondary care dispense-notification message. More examples of this message can be found here.

Schema

Name Description
object

Response

HTTP status: 200

Successfully submitted.

Body

Content type: application/fhir+json

Example

A successful response to a dispense-notification.

Schema

Name Description
object
HTTP status: 4XX

An error occurred as follows:

HTTP status Error code Description
400 BAD_REQUEST Invalid request.
Body

Content type: application/fhir+json

Example

An error response.

Schema

Name Description
object

Claim for a dispensed prescription

post /FHIR/R4/Claim

Overview

Claim

Use this endpoint to submit a claim for reimbursement for a dispensed prescription.

Claim Amend

The same endpoint can be used to amend a previous claim. The same message structure is used with the addition of a replacementOf extension referencing the identifier of the previous claim to be amended. More information can be found on the fhir documentation.

Request

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

String

The user role ID (URID) for the current session. Also known as a user role profile ID (URPID).

If you are using User-restricted RESTful APIs - NHS login separate authentication and authorisation, see determine the user's role for guidance.

This field is optional.

Pattern: /^[0-9]+$/

Example: 555254240100

X-Request-ID

String

A globally unique identifier (GUID) for the request, which we use to de-duplicate repeated requests and to trace the request if you contact our helpdesk.

Must be a universally unique identifier (UUID) (ideally version 4).

Mirrored back in a response header.

If you re-send a failed request, use the same value in this header.

Required in all environments except sandbox.

Pattern: /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/

Example: 60E0B220-8136-4CA5-AE46-1D97EF59D068

Required
X-Correlation-ID

String

An optional ID which you can use to track transactions across multiple systems. It can have any value, but we recommend avoiding . characters.

Mirrored back in a response header.

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

Body
Required

Content type: application/fhir+json

Example

A valid secondary care Claim message. More examples of this message can be found here.

Schema

Name Description
object

Response

HTTP status: 200

Successfully submitted.

Body

Content type: application/fhir+json

Example

A successful response to a dispense-claim request.

Schema

Name Description
object
HTTP status: 4XX

An error occurred as follows:

HTTP status Error code Description
400 BAD_REQUEST Invalid request.
Body

Content type: application/fhir+json

Example

An error response.

Schema

Name Description
object

Cancel a prescription

post /FHIR/R4/$process-message#prescription-order-update

Overview

Use this endpoint to send a prescription-order-update message to EPS.

The effect of calling this endpoint depends on the type of the message, which is determined by the MessageHeader resource. To cancel a prescription, send a prescription-order-update message.

Note that the #prescription-order-update in the URL has been added to distinguish this from the other operations which can be performed using the $process-message endpoint. It is not required in requests to the API.

Request

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

String

The user role ID (URID) for the current session. Also known as a user role profile ID (URPID).

If you are using User-restricted RESTful APIs - NHS login separate authentication and authorisation, see determine the user's role for guidance.

This field is optional.

Pattern: /^[0-9]+$/

Example: 555254240100

X-Request-ID

String

A globally unique identifier (GUID) for the request, which we use to de-duplicate repeated requests and to trace the request if you contact our helpdesk.

Must be a universally unique identifier (UUID) (ideally version 4).

Mirrored back in a response header.

If you re-send a failed request, use the same value in this header.

Required in all environments except sandbox.

Pattern: /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/

Example: 60E0B220-8136-4CA5-AE46-1D97EF59D068

Required
X-Correlation-ID

String

An optional ID which you can use to track transactions across multiple systems. It can have any value, but we recommend avoiding . characters.

Mirrored back in a response header.

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

Body
Required

Content type: application/fhir+json

Example

A valid secondary care prescription-order-update message. More examples of this message can be found here.

Schema

Name Description
object

Response

HTTP status: 200

Successfully submitted.

Body

Content type: application/fhir+json

Example

A successful response to a prescription-order-update request.

Schema

Name Description
object
HTTP status: 4XX

An error occurred as follows:

HTTP status Error code Description FHIR type
400 BAD_REQUEST Invalid request. OperationOutcome
400 BAD_REQUEST Invalid request (with additional details). Bundle
Body

Content type: application/fhir+json

Examples

An error response.

An error response with additional details provided.

Schema

Name Description
object

Return a downloaded prescription

post /FHIR/R4/Task#return

Overview

Use this endpoint to return a downloaded prescription to Spine, so that another dispensing system can download it.

The effect of calling this endpoint depends on the Task status. To return a downloaded prescription to EPS, send a Task with a status of rejected. For more information on how to create these messages, see NHSDigital-Task.

Note that the #return in the URL has been added to distinguish this from the other operations which can be performed using the Task endpoint. It is not required in requests to the API.

Request

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

String

The user role ID (URID) for the current session. Also known as a user role profile ID (URPID).

If you are using User-restricted RESTful APIs - NHS login separate authentication and authorisation, see determine the user's role for guidance.

This field is optional.

Pattern: /^[0-9]+$/

Example: 555254240100

X-Request-ID

String

A globally unique identifier (GUID) for the request, which we use to de-duplicate repeated requests and to trace the request if you contact our helpdesk.

Must be a universally unique identifier (UUID) (ideally version 4).

Mirrored back in a response header.

If you re-send a failed request, use the same value in this header.

Required in all environments except sandbox.

Pattern: /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/

Example: 60E0B220-8136-4CA5-AE46-1D97EF59D068

Required
X-Correlation-ID

String

An optional ID which you can use to track transactions across multiple systems. It can have any value, but we recommend avoiding . characters.

Mirrored back in a response header.

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

Response

HTTP status: 200

Action completed successfully.

Body

Content type: application/fhir+json

Example

A successful response to a return request.

Schema

Name Description

A successful response.
HTTP status: 4XX

An error occurred as follows:

HTTP status Error code Description
400 BAD_REQUEST Invalid request.
Body

Content type: application/fhir+json

Example

An error response to a return request.

Withdraw a dispense notification

post /FHIR/R4/Task#withdraw

Overview

Use this endpoint to withdraw a dispense-notification message, for example in the case that a prescription was marked as dispensed erroneously.

The effect of calling this endpoint depends on the Task status. To withdraw a dispense-notification message from EPS, send a Task with a status of in-progress. For more information on how to create these messages, see NHSDigital-Task.

Note that the #withdraw in the URL has been added to distinguish this from the other operations which can be performed using the Task endpoint. It is not required in requests to the API.

This interaction is only available in the sandbox environment.

Request

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

String

The user role ID (URID) for the current session. Also known as a user role profile ID (URPID).

If you are using User-restricted RESTful APIs - NHS login separate authentication and authorisation, see determine the user's role for guidance.

This field is optional.

Pattern: /^[0-9]+$/

Example: 555254240100

X-Request-ID

String

A globally unique identifier (GUID) for the request, which we use to de-duplicate repeated requests and to trace the request if you contact our helpdesk.

Must be a universally unique identifier (UUID) (ideally version 4).

Mirrored back in a response header.

If you re-send a failed request, use the same value in this header.

Required in all environments except sandbox.

Pattern: /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/

Example: 60E0B220-8136-4CA5-AE46-1D97EF59D068

Required
X-Correlation-ID

String

An optional ID which you can use to track transactions across multiple systems. It can have any value, but we recommend avoiding . characters.

Mirrored back in a response header.

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

Response

HTTP status: 200

Action completed successfully.

Body

Content type: application/fhir+json

Example

A successful response to a withdraw request.

Schema

Name Description

A successful response.
HTTP status: 4XX

An error occurred as follows:

HTTP status Error code Description
400 BAD_REQUEST Invalid request.
Body

Content type: application/fhir+json

Example

An error response to a withdraw request.

Search for summary details about a prescription

get /FHIR/R4/Task

Overview

Use this endpoint to search for summary details about one or more prescriptions.

At least one of the following query parameters must be provided:

  • identifier
  • focus:identifier
  • patient:identifier

You can also search on the following parameters:

  • business-status
  • authored-on

Request

Query parameters
Name Description
identifier

String

The short form identifier of the prescription you are searching for.

Example: D7AC09-A99968-4BA59C

focus:identifier

String

The short form identifier of the prescription you are searching for.
patient:identifier

String

The NHS number of the patient whose prescriptions you are searching for.

Example: 9912003489

business-status

String

The state that a prescription is in. You can find valid business states here.

Example: 0001

authored-on

String

Date the prescription was authored <eq|ge|le>yyyy-mm-dd. To specify a range, use authored-on=geyyyy-mm-dd&authored-on=leyyyy-mm-dd.

Examples

Exact match date

[ "eq2010-10-22" ]

Greater than or equals match, which matches 2010-10-22 or 2010-10-23

[ "ge2010-10-22" ]

Less than or equals match, which matches 2010-10-22 or 2010-10-21

[ "le2010-10-22" ]
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-Session-URID

String

The user role ID (URID) for the current session. Also known as a user role profile ID (URPID).

If you are using User-restricted RESTful APIs - NHS login separate authentication and authorisation, see determine the user's role for guidance.

This field is optional.

Pattern: /^[0-9]+$/

Example: 555254240100

X-Request-ID

String

A globally unique identifier (GUID) for the request, which we use to de-duplicate repeated requests and to trace the request if you contact our helpdesk.

Must be a universally unique identifier (UUID) (ideally version 4).

Mirrored back in a response header.

If you re-send a failed request, use the same value in this header.

Required in all environments except sandbox.

Pattern: /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/

Example: 60E0B220-8136-4CA5-AE46-1D97EF59D068

Required
X-Correlation-ID

String

An optional ID which you can use to track transactions across multiple systems. It can have any value, but we recommend avoiding . characters.

Mirrored back in a response header.

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

Response

HTTP status: 200

Successful query.

Body

Content type: application/fhir+json

Example

A successful response to a prescription summary query. More examples of this message can be found here.

Schema

Name Description
object
HTTP status: 4XX

Invalid query.

Body

Content type: application/fhir+json

Example

An error response to a prescription summary query.

Schema

Name Description
object

Outcome of an operation that does not result in a resource or bundle being returned (for example, error, async/batch submission).
resourceType
string

FHIR Resource Type.

Allowed values: OperationOutcome
issue
array

List of issues that have occurred.

Min items: 1
object
severity
string
required

Severity of the error.

Allowed values: fatal, error, warning, information
code
string
required

FHIR error code.

Allowed values: invalid, structure, required, value, invariant, security, login, unknown, expired, forbidden, suppressed, processing, not-supported, duplicate, multiple-matches, not-found, deleted, too-long, code-invalid, extension, too-costly, business-rule, conflict, transient, lock-error, no-store, exception, timeout, incomplete, throttled, informational
details
object

Internal error code.
coding
array
object
system
string

URI of the coding system specification.

Example: https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode
version
string

Version of the coding system in use.

Example: 1
code
string

Symbol in syntax defined by the system.

Example: INVALID_VALUE
display
string

Representation defined by the system.

Example: Provided value is invalid
expression
string

FHIRPath of element(s) related to the error.

Example: Patient.name.given