Companies House API Filing service allows 3rd party software to file certain forms and change certain company data with Companies House.
API Filing initially exposes four API services:
Transactions API. This API provides the generic model that encapsulates all other API Filing services. A transaction is best thought of as an envelope for one or more data changes or forms.Registered Office Address (ROA) API. This API provides the specific ROA data change functionality. An ROA data change can be added to a transaction before the transaction is submitted to Companies House.Insolvency API. This API provides the specific insolvency data change functionality - for example to open an insolvency case and appoint an insolvency practitioner (equivalent to the paper '600' form). An insolvency data change can be added to a transaction before the transaction is submitted to Companies House.Registered Email Address (REA) API. This API provides the specific REA data change functionality. A registered email address data change can be added to a transaction before the transaction is submitted to Companies House. Also note that this service is to update the registered email address, it cannot be used to provide an initial registered email address.API Filing requires software to integrate with Companies House OAuth 2.0 Service and cannot be done with a simple API key using Basic authentication.
For a detailed guide on this integration see Authenticating Web Server Apps with OAuth 2.0
Certain APIs may have additional security. At present this is limited to:
All API Filing software will need to sign their users in to Companies House with one or more scopes.
https://identity.company-information.service.gov.uk/user/profile.read is required for API Filing and grants permission to read the users profile data.Depending on the filing functionality the list of scopes may change.
| Service/API | Required scope(s) | Additional information |
|---|---|---|
| Transactions (pre-requisite for all other APIs) | https://identity.company-information.service.gov.uk/user/profile.read |
|
| Registered Office Address (ROA) | https://api.company-information.service.gov.uk/company/{company_number}/registered-office-address.update |
Note that the {company_number} placeholder must be filled in with an actual company number e.g. for company 00000001 this scope would be https://api.company-information.service.gov.uk/company/00000001/registered-office-address.update. |
| Insolvency | https://api.company-information.service.gov.uk/company/*/insolvency.write-full |
Due to the sensitivity of insolvency endpoints, this scope can only be granted to a client (i.e. your software) if your client_id is registered with Companies House as a recognised insolvency software - regardless of whether or not the user granting the scope is a registered insolvency practitioner. |
| Registered Email Address (REA) | https://api.company-information.service.gov.uk/company/{company_number}/registered-email-address.update |
Note that the {company_number} placeholder must be filled in with an actual company number e.g. for company 00000001 this scope would be https://api.company-information.service.gov.uk/company/00000001/registered-email-address.update. |
Combining multiple scopes is done by space separating them as one string so the requested scope for API Filing an ROA data change for company 00000001 should request the scope:
https://identity.company-information.service.gov.uk/user/profile.read https://api.company-information.service.gov.uk/company/00000001/registered-office-address.updateThe first step in any API Filing submission will be to create a transaction. This is done with a POST request to /transactions.
This request takes an optional company_number parameter. The company number provided must match the company number used in the requested scope when signing the user in to Companies House OAuth 2.0 Service. If it does not, then the request will be unauthorized.
The company_number parameter is optional for future use cases where the company number may not be applicable (e.g. for filing an incorporation). However, if the data change relates to an existing company this field must be provided.
Once a transaction has been created, your software will have a transaction_id to use for creating data changes or form resources such as the ROA data change resource.
To create an ROA data change resource using the ROA API, your software will need to use the transaction_id to construct the URI.
/transactions/{transaction_id}/registered-office-address
Making a valid POST request to this URI will add the ROA data change resource to the transaction.
This URL can be used to make changes to the ROA data change resource with a PUT request to make further changes, before moving on to the next step to close the transaction.
Once a transaction has one or more data changes or form resources added to it, it must be closed to submit these data changes and forms to Companies House.
A transaction can be closed by making a PUT request to /transactions/{transaction_id} where the request body sets the status field to closed e.g.
PUT https://api.company-information.service.gov.uk/transactions/000000000000000001 with a request body
{
"status": "closed"
}
Once a transaction has been closed, it can no longer be modified by the end user or any third party software. The data change or filing resources can no longer be changed either.
Note: The end user will receive an email from Companies House confirming their submission.
After a transaction has been closed and submitted to Companies House, the data changes and forms it contains may be accepted or rejected.
Your software can check for accept/reject updates by making a GET request to /transactions/{transaction_id} and checking the data inside the read only filings object.
Note: The end user will receive an email from Companies House confirming the status when it has been processed.
Each endpoint is documented with examples within the developer site.
Companies House have written an example application - Third Party Test Harness - that demonstrates how a web server application may integrate with the Companies House OAuth 2.0 service and then file an ROA change using these APIs. The README of this GitHub repository details how to configure and run the test harness.
When testing any software that integrates with the Companies House API Filing services, you will be able to test using our Sandbox environment.
https://api-sandbox.company-information.service.gov.ukhttps://identity-sandbox.company-information.service.gov.ukhttps://test-data-sandbox.company-information.service.gov.ukThe services above allow all API Filing functions and related Public Data APIs functions (such as GET /company/{company_number}) for test companies.
The Sandbox environment does not allow use of Live API clients that have been created in the Companies House Developer Hub.
In order to use the sandbox environment, you will need to create Test API clients and configure your software to use those instead.
This may include a test web client and test API key if your software uses both. For instance, a web client to integrate with the OAuth service and API key to call public data functions.
The Sandbox test data api allows test companies to be generated on demand for use in the sandbox environment. This service is not available in the Live environment.
The Sandbox environment will automatically respond to all test filing submissions and update the filing status to either accepted or, in specific cases documented below, rejected with specific reject reasons.
For ROA data change submissions made using the Transactions and ROA APIs, the following scenarios:
For Insolvency data change submissions made using the Transactions and Insolvency APIs, the following scenarios:
For REA data change submissions made using the Transactions and REA APIs, the following scenarios:
All other submissions will receive a mock response status of accepted.
Once your software has passed testing and you are ready to move to Live, there are a few things that will need to change in your software. Ideally, these items will be configurable with properties files, environment variables, database lookups or some other mechanism that does not require code changes:
In the Live environment, responses will not be mocked. This means that all submissions will be sent to Companies House for review and if valid will be accepted on to the public register.
Some submissions may require manual inspection which will add a delay to processing. Your software may want to check for accept/reject status by polling the status of the filing using GET /transactions/{transaction_id}. While this is perfectly fine and expected, please be sure to obey our rate limiting rules when polling APIs for responses.