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

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.

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 Configurations recommended by Care Identity Authentication.

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.