Skip to main content
Creating a new NHS England: NHS England and NHS Digital merged on 1 February 2023. All references to NHS Digital now, or in the future, relate to NHS England. More about the merger.

Reference guide

This is a reference for information on how we build our APIs. You can find other useful information in our Glossary of developer terms.

API status

See Statuses.


Deprecation and retirement policy

APIs

In order to keep our API and service estate manageable, we might deprecate and eventually retire an API if:

  • we have built a new major version of the API
  • we have built a new API that provides equivalent capabilities - such as a FHIR API
  • the API is not fit for purpose, for example because it doesn't include important use cases
  • the API is not being used or has limited usage
  • the API is insecure or a security risk

We appreciate that this might cause inconvenience, but we must use public funds efficiently and cannot afford to maintain replaced or obsolete APIs indefinitely.

If we deprecate an API:

  • we will let you know
  • the API will still be available for use
  • our service levels will still apply
  • we are unlikely to make any updates
  • we will not permit new integrations - with the exception of in-flight integrations
  • we will consult with you on an appropriate date to retire the API

For details on APIs that are currently being considered for deprecation or retirement, see our interactive product backlog.

Standards

In order to keep our API standards estate manageable, we might deprecate and eventually retire an API standard if:

  • the standard is no longer is use
  • the standard is in use but is no longer strategic
  • the standard has been replaced by a newer standard

If we deprecate an API standard:

  • we will tag the standard as deprecated in the NHS Data Standards Directory
  • we will announce the deprecation to everyone with a developer account
  • we will set a retirement date as 12 months from the date of deprecation
  • the API standard will still be available for use

If we retire an API standard:

For details on API standards that are currently being considered for deprecation or retirement, see our interactive product backlog.


Feedback widgets and popups

Until recently, we used incoming feedback widgets and pop-up polls to collect feedback from you to improve our service.
We're currently looking for a replacement for this functionality.

In any case, we'd still like to hear your feedback on our site which you can send by contacting us.


HTTP status codes

We use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:

  • 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action
  • 400 to 499 if it failed because of a client error by your application
  • 500 to 599 if it failed because of an error on our server

For details of specific 2xx and 4xx responses for a specific API, see its API specification.

We do not list specific 5xx responses in API specifications - rather, you should code your application to handle all 5xx responses equally.

4xx status codes

A 4xx status code means there was a problem with the client request to the API. The most common error codes and their meanings are as follows:

HTTP code Error message Meaning
400  INVALID_VALUE Required header parameter is not valid, for example, the access token is invalid. Ensure the header parameter is valid and conforms to your API's endpoint specification.
400  MISSING_VALUE Required header parameter is missing, for example, the access token is missing. Ensure the header parameter is populated and conforms to your API's endpoint specification.
401  ACCESS_DENIED Authorisation credentials are not valid. Make sure you follow the instructions in the appropriate security pattern for your API's access mode.
401  UNAUTHORISED Authorisation credentials are missing. Make sure you follow the instructions in the appropriate security pattern for your API's access mode.
403  ACCESS_DENIED Authorisation credentials do not have permissions to perform the request. Make sure you follow the instructions in the appropriate security pattern for your API's access mode.
403  FORBIDDEN The user is not permitted to perform an action. Make sure you follow the instructions in the appropriate security pattern for your API's access mode.
404  RESOURCE_NOT_FOUND No dataset resources were found.
429  TOO_MANY_REQUESTS You have exceeded your application's rate limit.

5xx status codes

A 5xx status code means there was a problem with the server responding to the API request. The most common error codes and their meanings are as follows:

HTTP code Error message Meaning
500 INTERNAL_SERVER_ERROR The server does not know how to handle the request.
501 NOT_IMPLEMENTED The server does not support the request method, which it cannot handle. (The only methods that servers are required to support are GET and HEAD.)
502 BAD_GATEWAY The server got an invalid response, while working as a gateway or proxy to another server.
503 SERVICE_UNAVAILABLE The server cannot handle the request because it is down for maintenance or overloaded.
504 GATEWAY_TIMEOUT The server did not get a response in time, while working as a gateway or proxy to another server.

Non-NHS Digital APIs

Our API catalogue contains an increasing number of APIs not created by us at NHS Digital but by associated organisations. These include other parts of the NHS and various partner organisations. Use the API catalogue 'owner' filter to see these APIs.


Performance testing

We do not currently have an environment you can use for performance testing your integration.

If you need to performance test your integration, we recommend you build stubs to simulate our APIs.

If you think it would make integration easier if we provided a performance test environment, you can can upvote the feature suggestion on our interactive product backlog.

See also response times.


Rate limits

For some of our APIs, we 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 5 requests per second per application per API:

  • the limit is applied per minute, so you can make up to 300 requests in any given (rolling) minute
  • the limit applies per application, per API
  • it only applies to APIs on our API platform - where the domain is https://api.service.nhs.uk
  • it does apply to our OAuth 2.0 authorisation service - https://api.service.nhs.uk/oauth.

If you go over the rate limit you'll receive a response with an HTTP status of 429 (Too Many Requests).

Some of our APIs also have global rate limits for additional protection. These should not normally affect you, but in extreme cases you might get a 429 response even if you have not gone over your application's rate limit.

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.


Response times

We do not have formal service level agreements (SLAs) for API response times.

That said, we do monitor response times and react where we believe them to be unreasonable.

As a general guide, you can assume that all our APIs respond in under 0.5 seconds for 95% of the time, unless otherwise stated in the API documentation. In other words they are 'fast enough' for a standard use case where an end user is present. Most of our APIs are much, much faster than that.

This applies to the production environment only - response times might be different (faster or slower) in test environments.

If you want to discuss response times for a particular use case - for example if you need to make multiple API calls and want to be sure the end-to-end response time will be acceptable, contact us.


Service levels

Each of our APIs has a service level which defines how available it is and how quickly we fix issues.

The service level does not cover API response times.

The service level applies to the production environment only, not to our test environments. APIs with an API status of alpha or retired are not available in production and thus do not have a service level defined.

Whilst we expect to meet these service levels, they are not guaranteed, and we will not be liable to you if we do not meet them.

The service levels are as follows:

Characteristic Bronze

Silver /
Silver Plus*

Gold Platinum /
Platinum Plus
Operational hours 8am to 6pm
Monday to Friday
excluding
Bank Holidays**
24x7x365 24x7x365 24x7x365
Supported hours 8am to 6pm
Monday to Friday
excluding
Bank Holidays
8am to 6pm
Monday to Friday
excluding
Bank Holidays
24x7x365 24x7x365
Availability
(in supported hours)
98% 99.50% 99.90%

99.90% (Platinum)

99.99% (Platinum Plus)

Incident resolution times (in supported hours)
Severity 1 8 hours 4 hours 4 hours 2 hours
Severity 2 16 hours 8 hours 8 hours 4 hours
Severity 3 40 hours 20 hours 10 hours 8 hours
Severity 4 120 hours 80 hours 50 hours 30 hours
Severity 5 240 hours 200 hours 140 hours 100 hours

* Silver Plus we respond to severity 1 and severity 2 incidents outside of business hours (8am to 6pm Monday to Friday excluding Bank Holidays).

** Bronze operational hours are an expected minimum, with many APIs being available outside of business hours.

To find out the service level for a given API, see the API specification in our API catalogue.


Statuses

APIs, message integrations and publish-subscribe events

We tag our APIs, message integrations and publish-subscribe events with a status as follows:

  • In development - early prototyping - the API is available, and might be available for testing via a sandbox service or an integration environment - but we expect to make breaking changes based on developer feedback
  • Beta - the API is available in production - it might still be subject to breaking changes - and its service level can be anything from bronze to platinum
  • In production - once out of beta, there will be no breaking changes - if we need to make breaking changes, we'll publish a new version of the API
  • Internal - the API is not currently available for integration by external third parties - if you still want to use it, contact us
  • Under review for deprecation - the API is under review and we're considering deprecating it - if you have any concerns, contact us
  • Deprecated - the API is still available and service levels still apply, but we plan to retire it at some point - we are unlikely to make any updates and new integrations are not permitted - once deprecated, we will consult with developers before deciding on a retirement date
  • Retired - the API is no longer available for use

API standards

We tag our API standards with a status as follows:

  • Draft - is still being developed or waiting for assurance or endorsement by qualified bodies
  • Active - is stable, maintained and has been assured or endorsed for use by qualified bodies
  • Under review for deprecation - is under review and we're considering deprecating it - if you have any concerns, contact us
  • Deprecated - is an older version of a standard which is being phased out
  • Retired - is not being maintained and should not be used

For more details on deprecation and retirement, see our deprecation and retirement policy.

We align these API standard statuses with those found in the NHS Data Standards Directory.


Version control

All of our RESTful APIs have only a single version, and you do not need to specify the version number when you call the API.

Once an API is stable (meaning it has exited beta) we avoid making any breaking changes. That means we might add new data fields or add new valid values to code sets, but we won't remove any mandatory fields or change the semantic meaning of any existing fields or code sets.

If we ever do need to make breaking changes to a stable API, we will use HTTP headers to allow you to specify the API version you want to call. We'll do this in a backwards-compatible way.

Last edited: 9 January 2023 10:30 am