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:
- the create test user service to create individuals or organisations with a default set of enrolments
- the Create Test User API to create a wider variety of test users including agents or if you use automated testing
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.