Testing in the sandbox

Test users, test data and stateful behaviour

Test users

To test user-restricted endpoints, you must create a test user. You can use:

Each test user is unique, with its own user ID, password and tax identifiers (for example SA UTR and NINO for an individual). We generate the test user details automatically - you cannot choose them.

Use the test user’s user ID and password to sign in during the authorisation process.

Use the same test user’s tax identifiers when testing calls to our APIs. You should also test failure cases by using different tax identifiers.

You can create as many test users as you like. Each new test user provides a clean test environment.

You can share test users across applications and between test team members.

Other test data

Some APIs on the sandbox are stateless - they return hard-coded happy path responses. You don’t need to set up any other test data for these APIs.

Some APIs on the sandbox are stateful - they let you send test data through create (POST) or update (PUT) requests and then read back that same data through retrieval (GET) requests.

Some stateful APIs have an accompanying test support API for setting up test data, which you can find on our API documentation page. For example, the Individual Tax API only supports retrieval (GET) requests so the accompanying Individual PAYE Test Support API can create (POST) test data for it.

For stateful APIs where there is no way to clear down test data, the best way to start anew is to create a new test user.