Documentation
T2A API 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 |
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:-
|
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 |
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:-
|
status | The appointment status. The values include:-
|
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:
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 |
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 <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
Documentation about common response structures returned from the T2A API.