Configuring Companies House

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

  • Company data check
  • Company filing retrieval
  • Company registry check

Company data check

How it works

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

The check is performed by sending the company's name, country of incorporation, and company number to Companies House and requesting a report.

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 and country of incorporation from the profile match the data in the registry.

When the check passes, the basic company information is imported into the check results. The information is displayed differently for the Identify officers task and the Verify company details task. See the description of the Company data check for more information.

The Company data check with Companies House does not return results for the Identify shareholders task. Whenever you run a Company data check with Companies House, a message is displayed on the task saying, "No shareholders found in the check result." To get results from Companies House on the Identify shareholders task, set up a Company registry check variant.

The check returns a partial match when the company name is found in the registry but one of the following is true:

  1. Any of the required profile data is missing.
  2. Any of the profile data does not match.
  3. The company status is inactive.
  4. The company status is unknown.
See Required and optional profile fields to learn which profile fields are required.

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

An error is returned if their of the following is true:

  • Companies House discovers more than one company that matches the profile details.
  • The company's country of incorporation is outside the UK.

Configuration options

There are no additional configuration options for the Company data 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 run this 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: 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 your account 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.

  1. Is company information returned from Companies House? Create any company profile and run the check variant. If the check passes and data for PassFort Ltd is displayed in the check results, the check variant is working as expected.
  2. Is a Partial match returned when the company name is found in the Companies House registry but the profile data does not match? Create a company profile with "partial" in the name and run the check variant. If the check returns a partial match and (on the Verify company details task) an incorrect company name for PassFort Ltd is displayed in the results, the check variant is working as expected.
Test words are not case sensitive.

Required and optional profile fields

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

Name

Description

Country of incorporation (metadata.country_of_incorporation)

Required

The country in which the company is incorporated.

Company name (metadata.name)

Required

If not included, a Partial match is returned

The legal name of the company.

Company number (metadata.number)

Required

The company’s registration number.

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.

Required and optional profile fields

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

Name

Description

Country of incorporation (metadata.country_of_incorporation)

Required

The country in which the company is incorporated.

Company number (metadata.number)

Required

The company’s registration number.

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.

Required and optional profile fields

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

Name

Description

Country of incorporation (metadata.country_of_incorporation)

Required

The country in which the company is incorporated.

Company number (metadata.number)

Required

The company’s registration number.


How did we do?


Powered by HelpDocs