Configuring Companies House

Companies House is a data provider you can use to run these checks:

  • Company filing retrieval
  • Company registry check

Company filings retrieval

How it works

This is the default behaviour for a variant of the Company filings retrieval check with Companies House as the data provider.

The check is performed by searching the company’s country of incorporation and registration number in the Companies House registry.

The check passes when any documents are found in the registry.

When the check passes:

  • The names of the documents are displayed in the check results.
  • If the following information is available, it’s also displayed in the check results: filing date, filing type, description, and source.
  • All documents are imported so you can see them.

If the company’s country of incorporation is anything other than the UK, an error is displayed.

Configuration options

There are no additional configuration options for the Company filings retrieval check variant with Companies House.

What we’ll need

Let us know that you’d like to add a variant of the Company filings retrieval check with Companies House and we’ll set it up.

If you want to use your own Companies House API key, you can get one for free by following these steps:

  1. Register with Companies House at https://developer.companieshouse.gov.uk/api/docs
  2. Complete the application at https://developer.companieshouse.gov.uk/developer/applications

Once you’ve got your API key, send it to us and we’ll add it to your configuration.

If you don’t want to use your own Companies House API key, that’s fine too - just let us know and we’ll configure the check variant that way.

Testing your configuration

Once the check variant is configured, follow these steps in your demo environment to test whether it's working as expected.

  • Are company filings returned from Companies House? Create a profile for a company incorporated in the UK and run the check variant. If the check passes and real filings from Companies House are displayed in the check results, the check variant is working as expected.
In the live environment, an error is displayed when the check variant is run on a profile with a country of address that isn't the UK. This error is not displayed in the demo environment.
The data displayed in the check results is real data from Companies House, even in the demo environment.

These are the company’s profile details searched in Companies House:

Field name

Description

Notes

Portal: Country of incorporation

API:metadata.country_of_incorporation

The country in which the company is incorporated.

Required

Portal: Company number

API:metadata.number

The company’s registration number.

Required

Company registry check

How it works

This is the default behaviour for a variant of the Company registry check with Companies House as the data provider.

The check is performed by searching the company’s country of incorporation and registration number in the Companies House registry.

The check passes when all of the following are true:

  1. The company name is found in the registry.
  2. The company status in the registry is active.
  3. The company number from the company’s profile match the data found in the registry.

When the check passes, the basic company information (e.g. name, company number, incorporation date) as well as a list of all the company officers found in the registry is displayed in the check results.

If the company name is found, but any of the other data is missing or does not match, the check returns a Partial match.

If the company name cannot be found, the check fails.

If the company’s country of incorporation is anything other than the UK, an error is displayed.

Configuration options

There are no additional configuration options for the Company registry check variant with Companies House.

However, this check is used on the Identify officers task, which includes configuration options to control how the officers returned by Companies House are verified. Learn about task configuration options.

What we’ll need

Let us know that you’d like to add a variant of the Company registry check with Companies House and we’ll set it up.

If you’d like to use any of the configuration options for the Identify officers task, please let us know which ones you’d like to use.

If you want to use your own Companies House API key, you can get one for free by following these steps:

  1. Register with Companies House at https://developer.companieshouse.gov.uk/api/docs
  2. Complete the application at https://developer.companieshouse.gov.uk/developer/applications

Once you’ve got your API key, send it to us and we’ll add it to your configuration.

If you don’t want to use your own Companies House API key, that’s fine too - just let us know and we’ll configure the check variant that way.

Testing your configuration

Once the check variant is configured, follow these steps in your demo environment to test whether it's working as expected.

  • Are company officers returned from Companies House? Create any company profile and run the check variant. If the check passes and data for company officers is displayed in the check results, the check variant is working as expected.
In the live environment, an error is displayed when the check variant is run on a profile with a country of address that isn't the UK. This error is not displayed in the demo environment.
The data displayed in the check results is real data from Companies House, even in the demo environment.

These are the profile details searched in the Companies House registry:

Field name

Description

Notes

Portal: Country of incorporation

API:metadata.country_of_incorporation

The country in which the company is incorporated.

Required

Portal: Company number

API:metadata.number

The company’s registration number.

Required


How did we do?