Testing in the sandbox
Getting started
Use our sandbox environment to test your application against our RESTful APIs before going live. This environment does not support our XML APIs which must be tested as explained in the Basic guide for software developers.
1. Add an application
Add a sandbox application to use for testing.
Sandbox applications that have not made an API call for 12 months will be deleted.
2. Subscribe to APIs
You must subscribe to APIs before your application can access them. Subscribe on the manage API subscriptions page.
3. Get sandbox credentials
Get these from the manage credentials page. They are only valid for the sandbox environment.
4. Configure your application for sandbox
Configure your application to make authorisation and API calls to sandbox endpoints using your sandbox credentials and the base URL https://test-api.service.hmrc.gov.uk.
5. Create test users and other test data
To test user-restricted endpoints, you need to create test users and potentially other test data.
6. Test the authorisation process
If you’re testing user-restricted endpoints, trigger the authorisation process from your application:
- Sign in with the credentials for the test user you created. Note that sandbox doesn’t include 2-step verification or identity checks.
- Complete the journey by granting authority to your application.
- We will return control back to your application, which should then obtain an OAuth token for use in subsequent API calls.
Remember to test failure cases by selecting “Do not grant authority” after signing in.
7. Test API calls
Use your application to make calls to our sandbox APIs.
Remember to test the error scenarios mentioned in the API documentation.