Documentation

Common Response Structures


These structures are returned by more than one method.

Common Response Structure <address>


The address structure is returned by the address_search method.

Element Description
line_1 Address line 1.
line_2 Address line 2.
line_3 Address line 3.
place The place. If the address is in a named area within a large town, this will be that area, otherwise it will be the town. place is never empty if town is set.
town The town; only used if the address is in a named area within that town.
postcode The UK postal code, formatted to include the space.
addr_single_line The address, formatted as a single line. Commas are inserted between the major elements, and the postcode is included, if available.
street This is the "raw" element returned which is known as the thoroughfare. The cleaned elements line_1, line_2 and line_3 include this element.
street2

This is the "raw" element returned which is known as the dependent thoroughfare. The cleaned elements line_1, line_2 and line_3 include this element.

In a formatted address, this would appear before the thoroughfare, for example, street2 (the dependent thoroughfare) is the former:-

Pudding Row
Heslingbottom Road

premises This is the "raw" building number. The cleaned elements line_1, line_2 and line_3 include this element.
building This is the "raw" building name. The cleaned elements line_1, line_2 and line_3 include this element.
organisation This is the "raw" organisation name. The cleaned elements line_1, line_2 and line_3 include this element.

Common Response Structure <business>


Element Description
name Business name
telephone_number Telephone number
line_1 Address line 1
line_2 Address line 2
line_3 Address line 3
place The place. If the address is in a named area within a large town, this will be that area, otherwise it will be the town. place is never empty if town is set.
town The town; only used if the address is in a named area within that town.
postcode The UK postal code, formatted to include the space.
addr_single_line The address, formatted as a single line. Commas are inserted between the major elements, and the postcode is included, if available.
email_address Contact email address for this business.
web Business website address.
fax_number Business fax number.
classification Business classification.
company_number Limited company number or non-limited company ID for use with the company_details method.

Common Response Structure <company_short>


This structure is a brief summary of a company name and other details.

Note that the company_number value is used in order to access the main company information methods.

Element Description
name The company name.
company_number The unique Companies House company number.
data_set

The data set to which this record belongs. These are:-

  • Live
  • Dissolved
  • Former
  • Proposed
company_index_status

Effective: Proposed Name accepted for processing.

Rejected: Proposed Name Rejected.

Removed: Removed from register (Converted or Closed).

CngOfName Change of name.

Dissolved: Inliq: In Liquidation.

StatusR For a Scottish company, this will indicate that the company is in receivership. For English/Welsh companies, the "receivership" flag may mean that one or more of the company's properties has gone into receivership.

company_date The date on which the action / event took place.

Common Response Structure <director>


This structure is returned by the director_details and company_details methods. All elements may be empty unless stated.

Element Description
title The person's title, such as Mr, Mrs, Ms etc.
forename Only supplied where applicable - May be more than one occurrence.
surname The person's surname.
honours The person's honours. Note that this is only present when this instance is returned from the director_details method.
nationality The nationality. Note that this is only present when this instance is returned from the director_details method.
corporate_indicator Used to distinguish corporate appointments from natural person appointments. Will be set to "Y" or "1" if the officer is a corporate body. Otherwise set to space. Note that this is only present when the instance is returned from the director_details method or company_details method.
country_state_of_residence The 'Country/State of Residence' applies to officers who are indicated as Natural Person Directors. Data captured within this field will return for filings under the 2006 Act for these officer types only; Where there is no data captured the field will remain blank.
name_single_line

The name on a single line, comprising title, forename, middle initial and surname; for example:-

Mr Alan Fiction
Jean A Dreamer

director_id An ID to be used in the director_details method, to obtain full information on the individual. Note that the ID consists only of alphanumeric characters plus the underscore _ and dash - characters.
line_1 Address line 1. Note that this is only present when the instance is returned from the director_details method or company_details method.
line_2 Address line 2. Note that this is only present when the instance is returned from the director_details method or company_details method.
line_3 Address line 3. Note that this is only present when the instance is returned from the director_details method or company_details method.
place The place.
postcode The postcode.
addr_single_line The address, formatted as a single line. Commas are inserted between the major elements, and the postcode is included, if available.
dob The date of birth in the format YYYY-MM-DD (e.g. 1963-05-16).
num_appt Total number of appointments of all kinds held by an individual.
num_current_appt Number of current appointments.
num_dissoloved_appt Number of dissolved appointments.
num_resigned_appt Number of resigned appointments.
director_appt_list List of director_appt records, this is only returned when the search was for current company officers.
director_disq_list List of director_disq records for a disqualified director. This is only returned when the search was for disqualified company officers.

Common Response Structure <director_appt>


This structure is only used in conjunction with the above director structure, and only during the method director_details. This shows the appointments relating to this company officer.

Element Description
company_name The company name.
company_number The companies house number.
company_status

The current status. The defined values include:-

  • active
  • dissolved
  • liquidation
  • receivership
status

The appointment status. The values include:-

  • current
  • resigned
type The appointment type. See the Company Officer Types appendix.
appointment_date In the format YYYY-MM-DD
resignation_date In the format YYYY-MM-DD
occupation The occupation of the individual.
date_prefix

Only supplied where applicable, will be supplied if the appointee was appointed prior to the original data capture by Companies House and the appointment date was taken from the last Annual Return.

An example is:-

PRE-

Common Response Structure <director_disq>


This structure is only used in conjunction with the above director structure, and only during the method director_details. This structure contains the information on the companies from which the individual is disqualified.

Element Description
company_name The company name.
company_number number The companies house number.
reason

Reason for disqualification. An example is:

CDDA 1986 S7.

See the appendix for an explanation.

The above example means that the person was disqualified under the Company Directors Disqualification Act 1986 section 7.

start_date In the format YYYY-MM-DD
end_date In the format YYYY-MM-DD
exemptions Only supplied where applicable. This is a nested list (with no further children) of director_disq records. The record in the exemptions list do not have their reason and exemptions fields set.

Common Response Structure <geo_data>


The address structure is returned by the geo_code and geo_code_telephone methods; not all elements are returned by both methods.

Element Description
north Northing value, if the data is in the UK. See Co-ordinate Systems.
east Easting value, if the data is in the UK. See Co-ordinate Systems.
latitude WGS 84 (GPS) latitude value.
longitude WGS 84 (GPS) longitude value.
country_code ISO 3166-1 two character country code.
country_name The country name.
description Description of the item.
postcode A full UK postcode; in the case of geo_code_telephone this is a sample postcode in the area indicated.
city The nearest city; this is only set by ip_location.

Common Response Structure <person>


The person structure is returned by the person_search method.

Element Description
title The person's title, such as Mr, Mrs, Ms etc.
forename The person's first name.
middle_initial The second initial.
surname The person's surname.
name_single_line

The name on a single line, comprising title, forename, middle initial and surname; for example:-

Mr Alan Fiction
Jean A Dreamer

line_1 Address line 1.
line_2 Address line 2.
line_3 Address line 3.
place The place. If the address is in a named area within a large town, this will be that area, otherwise it will be the town. place is never empty if town is set.
town The town; only used if the address is in a named area within that town.
postcode The UK postal code, formatted to include the space.
addr_single_line The address, formatted as a single line. Commas are inserted between the major elements, and the postcode is included, if available.
years_list

A list of years, in which the electoral roll record for this person has been found.

Please note that the XML returns an array of Strings; each year is a single String.

<years_list>
  <string>2008</string>
  <string>2009</string>
  <string>2010</string>
  <string>2011</string>
</years_list>					
				

The JSON returns an array of years thus:-

"years_list":["2009","2010","2011"],
telephone_number The person's landline telephone number.
mobile The person's mobile telephone number.
email_address The person's email address.
dob The person's date of birth in YYYY-MM-DD format.
director_id A director ID, where available. To be used in conjunction with the director_details method.

Common Response Structure <place>


The place structure is used in place lists returned by the person_search and business_search methods; not all elements are returned by each method.

Element Description
name The place name as a single line of text. For example:- Weymouth, Dorset

Common Response Structure <premises>


An array of records is returned from an address-only person_search - the end user should select the premises at which to view the occupants. Use the name value to replace the premises input parameter value.

You must use the entire name value, including the postal code, when replacing the premises value.

Element Description
name The name of a premises, for example:- 27 Imagination Gardens (YO10 5NP)

Common Response Structure <street>


This structure is returned by the person_search method. An array of records is returned from an address-only search - the end user should select the street on which to view the occupants. Use the name value to replace the street input parameter value.

Element Description
name The street name, for example:- Imagination Gardens, Magic Street (YO10)

Common Response Structure <date_details>


Element Description
y Year in YYYY format e.g. 2011
m Month (1-12)
d Day (1-31)
en Date in 'D Mon YYYY' e.g. 1 Jun 2017

Common Response Structure <date_time>


Element Description
year Year in YYYY format e.g. 2011
month Month (1-12)
day Day (1-31)
hour Hour (0-23)
min Minutes (0-59)
sec Seconds (0-59)

Response Structure <company_shareholder>


This structure is returned by company_credit_report and company_details methods. This is a single shareholder within the <company_shareholder_list> of a credit report.

Element Description
name Shareholder's name
currency Full description of the shares
shares Full description of the shares
share_count The shares amount
share_type The shares type
nominal_value The nominal value of the share
percentage The percentage held by this shareholder

Response Structure <company_financial>


This structure is returned by company_credit_report and company_details methods. This is a single financial item (covering a described period) within the financial list. Note that there are sub-elements for profit and loss, balance sheet, capital reserve and ratio; the names of those elements are listed separately.

Element Description
start_date The start date YYYY-MM-DD
end_date The end date YYYY-MM-DD
currency Currency e.g. GBP
period_months The period covered, in months
profit_loss Company Profit and Loss information
balance_sheet Company Balance Sheet information
capital_reserve Company Capital Reserve information
ratio Company Ratio information
net_cash_flow_from_operations Financial Information
net_cash_flow_before_financing Financial Information
net_cash_flow_from_financing Financial Information
contingent_liability Financial InformationFinancial Information
capital_employed Financial Information
employees Number of employees
auditors The name of the auditors
audit_qualification Comments from the auditors
bankers Bankers
bank_branch_code The Sort code e.g. 60-60-05

Company Profit and Loss


These are the elements within the profit_loss section.

Element
turnover
consolidated_accounts
cost_of_sales
gross_profit
export
directors_emoluments
operating_profits
depreciation
audit_fees
interest_payments
pre_tax
taxation
post_tax
dividends_payable
retained_profits
salaries

Company Balance Sheet


These are the elements within the balance_sheet section.

Element
tangible_assets
intangible_assets
fixed_assets
current_assets
trade_debtors
stock
cash
other_current_assets
increase_in_cash
misc_current_assets
total_assets
total_current_liabilities
trade_creditors
overdraft
other_short_term_finance
misc_current_liabilities
other_long_term_finance
long_term_liabilities
overdraft_long_term_liabilities
liabilities
net_assets
working_capital

Company Capital Reserve


These are the elements within the capital_reserve section.

Element
paid_up_equity
profit_loss_reserve
sundry_reserve
revaluation_reserve
net_worth
reserves
shareholder_funds

Company Ratio


These are the elements within the ratio section.

Element
pre_tax_margin
net_working_capital
gearing_ratio
equity
creditor_days
debtor_days
liquidity
return_on_capital_employed
current_ratio
total_debt_ratio
stock_turnover_ratio
return_on_assets_employed
return_on_net_assets_employed
current_debt_ratio

Next: ISO 3166-1 Country Codes