# Companies House API

Companies House is the United Kingdom registrar of companies and is an executive agency of the government. This entity is responsible for the Companies House API (opens new window) , which allows you to retrieve information on companies in the United Kingdom.

# Using the service

# Authentication

All requests must be authenticated by means of an OIDC access token, supplied as an Authorization header of type Bearer. For more instructions on how to obtain such a token, please refer to Accessing Signicat REST services. When retrieving the token, the scope client.companieshouse.search.get must be specified.

# API

Environment Base URL
Beta https://beta.signicat.com
Preproduction https://preprod.signicat.com
Production https://id.signicat.com
Path Verb Input Output
/companieshouse/search GET Search Path Parameters Search
/companieshouse/search/companies GET Search Path Parameters CompanySearch
/company/{companynumber}/officers GET Person Search Parameters OfficerList
/company/{companynumber}/persons-with-significant-control GET Person Search Parameters PersonWithSignificantControlList
/company/{companynumber}/filing-history GET Filing History Search Parameters FilingHistoryList

The difference between the methods is that the most generic one (/companieshouse/search) searches across all indexed information (companies, officers and disqualified officers), and the other one searches only in the companies repository.

# Code examples

# Example using cURL

curl -X GET \
-H "Authorization: Bearer <OIDC ACCESS TOKEN>" \
"https://<ENVIRONMENT>.signicat.com/companieshouse/search/companies?q=google&items_per_page=2&start_index=10"

# Search Path Parameters

Name Type Description
q String The search term, e.g. company name, company number, director name, address, etc.
items_per_page optional Integer The number of search results to return per page.
start_index optional Integer The index of the first result item to return.

# Person Search Parameters

company_number String The company number of the list being requested.
items_per_page optional Integer The number of search results to return per page.
register_type optional officers String The register_type determines which officer type is returned for the registers view. Accepted values are:directors``secretaries``llp-membersThe register_type field will only work if registers_view is set to true
register_view optional String Display register specific information. If given register is held at Companies House, registers_view set to true and correct register_type specified, only active officers will be returned. Those will also have full date of birth. Accepted values are:true``falseDefaults to false
start_index optional Integer The index of the first result item to return.
order_by optional officers String The field by which to order the result set. Possible values are:appointed_on``resigned_on``surnameNegating the order_bywill reverse the order. For example, order_by=-surname will give results in descending order of surname
Name Type Description

# Filing History Search Parameters

Name Type Description
company_number String The company number that the filing history is required for.
category optional String One or more comma-separated categories to filter by (inclusive).
items_per_page optional Integer The number of search results to return per page.
start_index optional Integer The index of the first result item to return.

# Messages

Name Type Description
etag optional String The ETag of the resource.
items optional List<Item> The results of the completed search. See items.kind for details of each specific result resource returned.
items_per_page optional Integer The number of search items returned per page.
kind optional String The type of search response returned. Possible values are:search#all
start_index optional Integer The index into the entire result set that this result page starts.
total_results optional Integer The number of further search results available for the current search.

# CompanySearch

Name Type Description
etag optional String The ETag of the resource.
items optional List < Item > The results of the completed search.
items_per_page optional Integer The number of search items returned per page. These items include the values that are relative to the company search.
kind optional String The type of search response returned. Possible values are:search#companies
start_index optional Integer The index into the entire result set that this result page starts.
total_results optional Integer The number of further search results available for the current search.

# Item

address Address The address of the company's registered office.
address_snippet String A single line address. This will be the address that matched within the indexed document, or the primary address otherwise (as returned by the address member).
company_number companies search String The company registration / incorporation number of the company.
company_status companies search Enum The company status. Possible values are:active``dissolved``liquidation``receivership``administration``voluntary-arrangement``converted-closed``insolvency-proceedings
company_type companies search Enum The company type. Possible values are:private-unlimited``ltd``plc``old-public-company``private-limited-guarant-nsc-limited-exemption``limited-partnership``private-limited-guarant-nsc``converted-or-closed``private-unlimited-nsc``private-limited-shares-section-30-exemption``assurance-company``oversea-company``eeig``icvc-securities``icvc-warrant``icvc-umbrella``industrial-and-provident-society``northern-ireland``northern-ireland-other``llp``royal-charter``investment-company-with-variable-capital``unregistered-company``llp``other``european-public-limited-liability-company-se
date_of_cessation optional companies search Date The date the company ended.
date_of_creation optional companies search Date The date the company was created.
description optional String The result description.
description_identifier optional Array An array of Enumeration types that make up the search description. See search_descriptions_raw.yaml in api-Enumerations
kind String The type of search result. Depending on the endpoint used possible values are:searchresult#company``searchresults#officer``searchresults#disqualified-officer
links Object The URL of the search result.
links.self String The URL of the resource being returned by the search item.
matches optional Matches A list of members and arrays of character offset, defining subStrings that matched the search terms.
snippet optional String Summary information for the result, showing additional details that have matched. In the case of companies, this would be previous company names.
title String The title of the search result.
Name Type Description

# Address

Name Type Description
address_line_1 String The first line of the address.
address_line_2 optional String The second line of the address.
care_of optional String The care of name.
country optional String The country.``
locality optional String The locality e.g London.
po_box optional String The post-office box number.
postal_code optional String The postal code e.g CF14 3UZ.
premises optional persons with significant control officers String The property name or number.
region optional String The region e.g Surrey.

# Matches

Name Type Description
address_snippet optional Array An array of character offset into the address_snippet String. These always occur in pairs, and define the start and end of subStrings in the member address_snippet that matched the search terms.
snippet optional Array An array of character offset into the snippet String. These always occur in pairs, and define the start and end of subStrings in the member snippet that matched the search terms. The first character of the String is index 1.
title optional Array An array of character offset into the title String. These always occur in pairs, and define the start and end of subStrings in the member title that matched the search terms. The first character of the String is index 1.

# OfficerList

Name Type Description
active_count Integer The number of active officers in this result set.
etag String The ETag of the resource.
inactive_count Integer The number of officers who have not resigned where the company status is dissolved or converted-closed in this result set.
items List<Officer> The list of officers.
items_per_page Integer The number of officers to return per page.
kind String The type of search response returned. Possible values are:officer-list
links Object Links to other resources associated with this officer list resource.
links.self String Link to this officer list resource.
resigned_count Integer The number of resigned officers in this result set.
start_index Integer The offset into the entire result set that this page starts.
total_results optional Integer The total number of officers in this result set.

# Officer

Name Type Description
address Address The correspondence address of the officer.
appointed_on Date The date on which the officer was appointed.
country_of_residence optional String The officer's country of residence.
date_of_birth optional Date of birth Details of director date of birth.
former_names optional List<Former Name> Former names for the officer.
identification optional Identification Only one from eea or non-eea can be supplied, not both.
links Object Links to other resources associated with this officer list item.
links.officer Object Links to other officer resources associated with this officer list item.
links.officer.appointments String Link to the officer appointment resource that this appointment is associated with.
name String Corporate or natural officer name.
nationality optional String The officer's nationality.
occupation optional String The officer's job title.
officer_role String Possible values are:cic-manager``corporate-director``corporate-llp-designated-member``corporate-llp-member``corporate-manager-of-an-eeig``corporate-member-of-a-management-organ``corporate-member-of-a-supervisory-organ``corporate-member-of-an-administrative-organ``corporate-nominee-director``corporate-nominee-secretary``corporate-secretary``director``general-partner-in-a-limited-partnership``judicial-factor``limited-partner-in-a-limited-partnership``llp-designated-member``llp-member``manager-of-an-eeig``member-of-a-management-organ``member-of-a-supervisory-organ``member-of-an-administrative-organ``nominee-director``nominee-secretary``person-authorised-to-accept``person-authorised-to-represent``person-authorised-to-represent-and-accept``receiver-and-manager``secretary
resigned_on Date The date on which the officer resigned.

# Date of Birth

Name Type Description
day optional Integer The day of the date of birth.
month Integer The month of date of birth.
year Integer The year of date of birth.

# Former Names

Name Type Description
forenames optional String Former forenames of the officer.
surname optional String Former surnames of the officer.

# Identification

Name Type Description
identification_type optional String Possible values are:eea``non-eea
legal_authority optional String The legal authority supervising the company.
legal_form optional String The legal form of the company as defined by its country of registration.
place_registered optional String Place registered.
registration_number optional String Company registration number.

# PersonWithSignificantControlList

Name Type Description
active_count Integer The number of active persons with significant control in this result set.
ceased_count Integer The number of ceased persons with significant control in this result set.
etag String The ETag of the resource.
items List<Person With Significant Control> The list of persons with significant control
items_per_page Integer The number of persons with significant control to return per page.
kind String The type of search response returned. Possible values are:persons-with-significant-control#list
links Object A set of URLs related to the resource, including self.
links.persons_with_significant_control_statements_list optional String The URL of the persons with significant control statements list resource.
links.self String The URL of the resource.
start_index Integer The offset into the entire result set that this page starts.
total_results optional Integer The total number of officers in this result set.

# PersonWithSignificantControl

Name Type Description
address Address The correspondence address of the officer.
ceased_on Date The date that Companies House was notified about the cessation of this person with significant control.
country_of_residence optional String The officer's country of residence.
date_of_birth optional Date of birth Details of director date of birth.
etag String The ETag of the resource.
links Object A set of URLs related to the resource, including self.
links.self Object The URL of the resource.
links.statement optional String The URL of the statement linked to this person with significant control.
name String Name of the person with significant control.
name_elements optional mandatory for an individual person with significant control Name Elements A document encapsulating the seperate elements of a person with significant control's name.
nationality optional String The officer's nationality.
natures_of_control optional Array Indicates the nature of control the person with significant control holds. For enumeration descriptions see descriptionsection in the enumeration mappings (opens new window) file.
notified_on Date The date that Companies House was notified about this person with significant control.

# Name Elements

Name Type Description
forename String The forename of the person with significant control.
other_forenames String Other forenames of the person with significant control.
surname String The surname of the person with significant control.
title String Title of the person with significant control.

# Filing History List

Name Type Description
etag String The ETag of the resource.
filing_history_status optional String The status of this filing history. Possible values are:filing-history-available
items List<Filing History> The filing history items
items_per_page Integer The number of filing history items returned per page.
kind String Indicates this resource is a filing history. Possible values are:filing-history
start_index Integer The index into the entire result set that this result page starts.
total_count Integer The total number of filing history items for this company.

# Filing History

Name Type Description
annotations optional List<Annotation> Annotations for the filing
associated_filings optional List<Associated Filing> Any filings associated with the current item
barcode optional String The barcode of the document.
category optional String The category of the document filed. Possible values are:accounts``address``annual-return``capital``change-of-name``incorporation``liquidation``miscellaneous``mortgage``officers``resolution
date Date The date the filing was processed.
description String A description of the filing. For enumeration descriptions see description section in the enumeration mappings (opens new window).
links optional Object Links to other resources associated with this filing history item.
links.document_metadata optional String Link to the document metadata associated with this filing history item. See the Document API documentation for more details.
links.self optional String Link to this filing history item.
pages optional Integer Number of pages within the PDF document (links.document_metadata)
paper_filed optional Boolean If true, indicates this is a paper filing.
resolutions optional List<Resolution> Resolutions for the filing
subcategory optional String The sub-category of the document filed. Possible values are:resolution
transaction_id String The transaction ID of the filing.
type String The type of filing.
items_per_page Integer The number of filing history items returned per page.
kind String Indicates this resource is a filing history. Possible values are:filing-history
start_index Integer The index into the entire result set that this result page starts.
total_count Integer The total number of filing history items for this company.

# Annotation

Name Type Description
annotation optional String The annotation text.
date Date The date the annotation was added.
description String A description of the annotation. For enumeration descriptions see description section in the enumeration mappings (opens new window).

# Associated Filing

Name Type Description
date Date The date the associated filing was processed.
description String A description of the associated filing. For enumeration descriptions see description section in the enumeration mappings (opens new window).
type String The type of the associated filing.

# Resolution

Name Type Description
category Date The date the associated filing was processed.
description String A description of the associated filing. For enumeration descriptions see description section in the enumeration mappings (opens new window).
document_id optional String The document id of the resolution.
receive_date Date The date the resolution was processed.
subcategory String The sub-category of the document filed. Possible values are:resolution
type String The type of the associated filing.
Last updated: 5/28/2021, 3:00:14 PM