Skip to main content

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

We tag our APIs with a status as follows:

  • alpha - early prototyping - the API specification 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
  • private beta - the API is available in production but only to a limited number of connecting applications. It is more stable, but might still be subject to minor breaking changes
  • beta (or public beta) - the API is available in production to all comers. It might still be subject to breaking changes
  • stable - there will be no breaking changes - if we need to make breaking changes we'll publish a new version of the API
  • 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

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

Deprecation and retirement policy

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.

Feedback widgets and popups

We use incoming feedback widgets and pop-up polls to collect feedback from you to improve our service, using a product called Hotjar.

Give us feedback by clicking on the blue feedback widget which appears as a tab on the right hand side of many pages. You can rate the page, give specific feedback comments and even select a specific element on the page to leave feedback on. Leave your email address if you're happy for us to contact you about your feedback. If you do not want to leave feedback, click the X to minimize the widget.

Certain pages have pop-up polls with questions about page content. Again, leave your email address if you're happy for us to contact you about your feedback. If you do not want to answer, click the top arrow to minimise the poll.

If you cannot see the feedback widget or pop-up polls

All pages in our developer hub (under the URL should have either a feedback widget or a pop-up poll, but never both.

Some browser privacy settings, or extensions such as pop-up or ad blockers, prevent these tools from appearing or working correctly, so:

  • consider whitelisting our website in your blocker software so that you can leave us feedback
  • check to see if you have "Do Not Track" set in you browser or a blocking cookie installed on your browser as explained on Hotjar's Do Not Track page

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

HTTP status codes

5xx status codes

A 5xx status code means the server has a problem. The most common 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.

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.

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
  • it does apply to our OAuth 2.0 authorisation service -

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.

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

The service levels are as follows:

Characteristic Bronze Silver Gold Platinum
Operational hours 8am to 6pm
Monday to Friday
Bank Holidays*
24x7x365 24x7x365 24x7x365
Supported hours 8am to 6pm
Monday to Friday
Bank Holidays
8am to 6pm
Monday to Friday
Bank Holidays
24x7x365 24x7x365
(in supported hours)
98% 99.50% 99.90% 99.90%
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

*Bronze operational hours are a guaranteed 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.

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: 4 January 2022 4:44 pm