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.

Testing APIs

Learn about the environments we provide to test your software with our APIs.

Overview

We provide environments to test your software with our APIs. There are different environments depending on which APIs you are using.

For some of our APIs, you must give evidence of your testing before you go live as part of our onboarding process.

This page includes some general information, but to find out about testing a particular API, read its documentation in our API catalogue.


Sandbox testing

Some of our APIs have a sandbox environment you can use for learning, experimentation and early testing.

Sandbox APIs are open-access, don't usually require authorisation and are usually stateless - they return hard-coded responses.

To see which of our APIs have a sandbox, see our API catalogue, filtered to show APIs with sandboxes.


Integration testing

Some of our APIs have integration test environments you can use for more realistic testing.

The different approaches to integration testing are explained below. For details on a particular API, read its documentation in our API catalogue.


Integration testing with our RESTful APIs

Some of our RESTful APIs have test environments you can use for more realistic testing than is possible in a sandbox.

These include:

  • the external development environment (DEV) - for early development testing of a few specific APIs, including authorisation and authentication testing with NHS login, or API-specific testing tools
  • the integration test environment (INT) - for integration testing of most APIs including authorisation, release and assurance testing

Their base URLs are:

Environment Base URL Availability
DEV https://dev.api.service.nhs.uk/ Check the 'Environments and testing' section of your API specification
INT https://int.api.service.nhs.uk/ Available with most APIs

You can access our development and integration test environments as follows:

1. Create an application and activate APIs

  1. If you do not already have one, create a developer account.
  2. Navigate to my developer account and sign in.
  3. Select 'My applications' and 'Manage your applications'.
  4. Select 'New app'.
  5. Enter details for your application and click 'add application' to create it. Best practice is to create one application for each of the test environments you want to access - development or integration. Do not share applications between environments.
  6. Select your application and then 'edit more application details'.
  7. Make a note of the API Key and Secret.
  8. In the list of APIs, find the API you want to use and activate it by clicking 'Enable' and 'save'.
  9. If you are using user-restricted APIs, specify your application's OAuth 2.0 Callback URL.

2. Generate a key pair, if required

If you are using signed JWT authentication, you need to generate a private/public key pair for testing and register your public key with us.

For details, see Application-restricted RESTful APIs - signed JWT authentication.

3. Configure your software for testing

To get your software working with our test environments, configure the following:

  1. Base URL for APIs: development dev.api.service.nhs.uk/ or integration int.api.service.nhs.uk/
  2. OAuth client ID and client secret (if needed): use the API key and secret from the previous step
  3. Base URL path for our authorisation server (if needed) as follows:
Authorisation server base URL Environment Type of testing
dev.api.service.nhs.uk/oauth2 Development

User-restricted API - patient access using NHS login - paired with NHS login Sandpit environment

int.api.service.nhs.uk/oauth2 Integration

Application-restricted API - signed JWT authentication

User-restricted API - healthcare worker access using NHS CIS2 - paired with CIS2 Integration (INT) environment

User-restricted API - patient access using NHS login - paired with NHS login Integration environment

int.api.service.nhs.uk/oauth2-mock Integration User-restricted API - early testing using our mock authorisation service (second generation) 
int.api.service.nhs.uk/oauth2-no-smartcard Integration User-restricted API - early testing using our mock authorisation service (first generation)

4. Set up smartcard access, if required

If your software is using smartcards for user authentication, do the following:

  1. get an ODS code - you’ll need one before you can access the Health and Social Care Network
  2. get access to the Health and Social Care Network
  3. get physical smartcards for testing
  4. download client software, including the Identity Agent (IA) and NHS Credential Management software (previously known as NHS Identity Hub)

You must use a Windows platform with your software, including the .NET framework.

To see which versions of Windows operating systems and browsers are supported, see Supported operating systems and browsers.

To download Identity Agent and NHS Credential Management software over your HSCN connection, see Configurations recommended by Care Identity Authentication.

5. Set up test data, if required

Some of our APIs include standard test data packs.

In some cases you might need to set up your own test data, for example:

  • to test specific cases that the standard test pack doesn't cover
  • to test data updates, for example patient data in PDS

For more details, see setting up test data in our path to live environments.

6. Start testing

During testing, for user-restricted APIs you need to sign in as an end user, as follows:


Integration testing with our HL7 V3 APIs

Our HL7 V3 APIs have a number of Path to Live environments for integration testing, including:

  • Development - early sandbox testing
  • Integration - end-to-end and regression tests
  • Deployment - test in situ and user acceptance tests
  • Proof of concept
  • Non-functional tests

For more details see Path to Live environments.


Performance testing

We do not provide environments for performance testing.

Moreover, the path-to-live environments for our RESTful APIs have low rate limits to protect them against overuse.

Last edited: 14 November 2022 11:19 am