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 follow a defined lifecycle to ensure only active applications are retained. You will receive an email before your application is deleted.
- Sandbox applications are automatically deleted if they do not make an API call within 30 days of creation.
- Applications that have previously made API calls but then remain inactive for 6 months will also 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.