Companies House APIs are hosted in our live environment where actual company data is made available and real users can file for their companies. A sandbox environment has also been created, running the same API versions as live to allow software developers to test their integration with Companies House APIs in a safe place.
The live environment runs every API listed in the
Developer's API suite apart from the
sandbox test data generator api service which only
runs in the sandbox environment.
The sandbox environment runs most APIs listed in the Developer's API suite including the test data generator service. Some APIs such as streaming and document APIs do not run in the sandbox while others like the search API respond with data from live due to processing limitations detailed below. The sandbox environment does not run the Companies House website for browser-based access to sandbox data.
The sandbox environment is maintained for developers to test their software's integration with OAuth and filing APIs which should not be tested in live due to the requirement for company authentication codes and the fact that successful API filing tests would update actual company data on the public register.
Data in the sandbox cannot be maintained or updated like live data due to
manual processing steps required in certain cases when processing filings. This internal processing
has been substituted for a mock processing service in the sandbox. Mock internal processing simply
responds to filing API submissions with a
status update sent back to the transaction
data, it does not update the test company data itself. More details around this process are
Sandbox environment URLs
When testing in the sandbox, your application must substitute the live environment URLs for the sandbox URLs:
- API URL:
- Identity service URL:
- Test data generator URL:
API keys and OAuth client details must also be substituted for test versions when using the sandbox.
Testing public data APIs
Public data APIs such as company data output,
search and the streaming API only allow the reading of existing data.
These APIs only support
GET requests using
API or stream key authorization. Due to the read only nature of these APIs,
testing can be done against the live or sandbox environments.
Testing filing APIs
Filing APIs such as the transactions and registered
office address (ROA) data change APIs allow data to be created or changed
as well as read. These APIs support a combination of http request methods
PATCH and require
bearer OAuth access token authorization. Due to the nature of
these APIs, testing should only be done against the sandbox environment.
How developers can test filing APIs in the sandbox
- Create a test company using the test data generator API.
- Store or take note of the company number and authentication code in the response.
- Read the company profile data from the sandbox API.
- Integrate with the OAuth service to get an access token ready for filing APIs. This will require a sandbox user to be registered and the test company authentication code to be provided.
- Create a filing using the access token as authorisation against the transaction's API and other filing APIs.
- Submit the transaction.
- Periodically check the transaction for mock
statusupdates and handle
Once a test company has been created using the test data generator, it can either be deleted by calling a different endpoint in the test data generator service or it can be reused for further testing. If you plan to reuse the company, you must make sure to store the authentication code as this cannot be recovered or reset later.
Once a user account has been registered in the sandbox, this can also be reused for further testing.