Overview
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 , 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:
The 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:
Defaults 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:
Negating the |
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
Search
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:
|
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:
|
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:
|
company_type companies search |
Enum | The company type. Possible values are:
|
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:
|
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:
|
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:
|
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:
|
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:
|
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 description section in the enumeration mappings 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:
|
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:
|
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:
|
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. |
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:
|
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:
|
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. |
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. |
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. |
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:
|
type | String | The type of the associated filing. |