Digital Onboarding

Companies House API

364 views September 19, 2017 November 24, 2017 1

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.

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-members

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:

  • true
  • false

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:

  • appointed_on
  • resigned_on
  • surname

Negating the order_by will 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 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:

  • 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.
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.

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:

  • resolution
type String The type of the associated filing.

Was this helpful?