Testing APIs

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 and integration catalogue.

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 and integration catalogue, filtered to show APIs with sandboxes.

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 and integration catalogue.

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:

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

1. Sign in to your developer account (if you don't have an account you can create one).
2. Select 'Environment access'.
3. If you haven't previously done so, register your application by selecting 'Add new application'. Enter the requested details and select 'Create application'.
4. Select your new or existing application.
5. Select 'Edit API keys' and make a note of the API key and secret.
6. Select 'Add APIs', select the API you want to use and select 'Save'.
7. Depending on which security pattern you're using, you might also need to specify your callback URL.

Some of our security patterns require you to generate a private/public key pair and register your public key with us.

For details, see the relevant security pattern:

• Application-restricted RESTful APIs - signed JWT authentication

• User-restricted RESTful APIs - CIS2 separate authentication and authorisation

• User-restricted RESTful APIs - NHS login separate authentication and authorisation

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:

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 guidance on setting up and troubleshooting.

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.

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

• if your test environment is set up for smartcard access, use the smartcard you set up in step 3 above
• if your test environment is set up for simulated sign-in using our second generation service, enter the user ID for the test user you want to use
• if your test environment is set up for simulated sign-in using our first generation service, simply click the 'sign in' button - you don't need any credentials

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.

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.

You are welcome to use our integration environment for automated testing, as long as you keep within the rate limits.

If you are using one of our user-restricted RESTful APIs, we recommend using our mock authorisation service for automated testing.