API testing

Environments

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.

Live

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.

Sandbox

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 documented below.

Sandbox environment URLs

When testing in the sandbox, your application must substitute the live environment URLs for the sandbox URLs:

  • API URL: https://api-sandbox.company-information.service.gov.uk
  • Identity service URL: https://identity-sandbox.company-information.service.gov.uk
  • Test data generator URL: https://test-data-sandbox.company-information.service.gov.uk (sandbox only)

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 basic 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 like POST, PUT and 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 status updates and handle accepted and rejected responses accordingly.

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.