Documentation
/api/financials
This API endpoint returns the available financials data for a company using its Companies House registration number.
Request
https://convert-ixbrl.co.uk/api/financials?companynumber=012345678&apiVersion=1
Rate limit
This endpoint is rate limited to 1 request per 2 seconds while the service is in early preview with requests exceeding this limit served with HTTP 429 code
Authentication
This endpoint requires the authentication header to be supplied. See the authentication section.
Request Parameters
| companyNumber | Type | Optional | Description |
|---|---|---|---|
apiVersion |
string | No | API Version, currently on "1" |
companyNumber |
string | No | Companies House registration number |
HTTP Response codes
| Status Code | Description |
|---|---|
200 |
Successful requests with results |
204 |
Successful requests with no results |
400 |
Validation errors |
401 |
Authorisation error for when the secret key header is missing or is invalid |
429 |
Request throttled for exceeding rate limits |
Response JSON (Sample, extracted from a real result)
{
"status": "Ok",
"result": {
"company_financial_list": [
{
"end_date": "6/29/2021",
"profit_loss": {
"turnover": "89566019.0",
"consolidated_accounts": null,
"cost_of_sales": "78531652.0",
"export": null,
"gross_profit": "11034367.0",
"directors_emoluments": null,
"operating_profits": "3642221.0",
"depreciation": null,
"audit_fees": null,
"interest_payments": null,
"pre_tax": null,
"tax_on_profit": "574525.0",
"profit_loss": "2849447.0",
"post_tax": null,
"dividends_payable": null,
"retained_profits": "20590718.0",
"salaries": null
},
"balance_sheet": {
"intangible_assets": "3000.0",
"tangible_assets": "1315963.0",
"fixed_assets": "1449501.0",
"current_assets": "31491683.0",
"stock": "15003821.0",
"debtors_amounts_falling_due_within_one_year": "12144967.0",
"debtors_amounts_falling_due_after_one_year": null,
"creditors_amounts_falling_due_within_one_year": "11889105.0",
"creditors_amounts_falling_due_after_more_than_one_year": null,
"cash": "4342895.0",
"net_current_assets_liabilities": "19602578.0",
"total_assets": null,
"total_assets_less_current_liabilities": "21052079.0",
"total_current_liabilities": null,
"liabilities": null,
"net_assets": "20595293.0",
"working_capital": null,
"shareholders_equity": "20595293.0",
"calledup_share_capital": "1902.0",
"retained_earnings_accumulated_losses": "20590718.0"
},
"cash_flow": {
"cash_generated_from_operations": "-63280.0",
"net_interest_paid_received_classified_as_operating_activities": "-218249.0",
"income_taxes_paid_refund_classified_as_operating_activities": "-600000.0",
"net_cash_flows_from_used_in_operating_activities": "754969.0",
"purchase_property_plant_equipment": "-552471.0",
"proceeds_from_sales_property_plant_equipment": "-76715.0",
"proceeds_from_sales_other_longterm_assets_classified_as_investing_activities": "7000.0",
"net_cash_flows_from_used_in_investing_activities": "482756.0",
"increase_decrease_in_cash_cash_equivalents_before_foreign_exchange_differences_changes_in_consolidation": "1237725.0",
"cash_cash_equivalents_cash_flow_value": "4342895.0"
},
"allAvailableXBRLConceptsAndValues": [
{
"periodEnd": "29/06/2021",
"description": "Other debtors",
"value": "6662863.0",
"xbrlConcept": "OtherDebtors",
"xbrlConceptPrefix": "core",
"taxonomy": "secr-char-2019-01-01",
"dimensionsData": [
{
"dimension": "FinancialInstrumentCurrentNon-current",
"xbrlConcept": "CurrentFinancialInstruments",
"description": "Current financial instruments"
}
]
},
{... allAvailableXBRLConceptsAndValues will contain the full list of extracted xbrl tags and values submitted as part of each IXBRL accounts file}
]
}
],
"title":"Company Name Limited"
},
"errorMessage": null
}
Response Properties
| Name | Type | Nullable | Description |
|---|---|---|---|
status |
string | no |
Contains Ok if the request was successful, Error if there was an error.
|
result[] |
array | yes |
Contains the company_financial_list array. Each item in this array would contain a single financial year's data
|
company_financial_list[].end_date |
string | no | Contains the financial year end date string in "dd/MM/yyyy" format. For example, for December 10,2023, this would contain 10/12/2023 |
company_financial_list[].profit_loss |
object | yes |
If the company has submitted P&L as part of the IXBRL accounts, this will contain the fields shown against the profit_loss object in the sample above.
Properties that were note included in the P&L will be null. All available properties in this section are positive or negative numbers with decimal points.
See the allAvailableXBRLConceptsAndValues array if the value you are looking for isn't available in this section.
|
company_financial_list[].balance_sheet |
object | yes |
Balance sheet properties, if available, for the given year, shown in the sample above.
Properties that were not included in the IXBRL will be null. All available properties in this section are positive or negative numbers with decimal points.
See the allAvailableXBRLConceptsAndValues array if the value you are looking for isn't available in this section.
|
company_financial_list[].allAvailableXBRLConceptsAndValues |
array | yes |
An array of objects containing all IXBRL tags and values for the given year, including the properties already included in the profit_loss and balance_sheet elements.
|
company_financial_list[].allAvailableXBRLConceptsAndValues.periodEnd |
string | no |
See company_financial_list[].end_date above
|
company_financial_list[].allAvailableXBRLConceptsAndValues.description |
string | no |
Contains the description of the XBRL tag, such as equity as shown above. The description would be from the taxonomy used to create the IXBRL file.
Depending on the tag, the description on its own may not be enough to classify the type of tag which requires the dimensionData values.
See the dimensionsData for an example and more details.
|
company_financial_list[].value |
string | no | The value of the XBRL tag, for example the monetary value of an Equity tag |
company_financial_list[].xbrlConcept |
string | no | The name of the tag from the taxonomy in use, for example "Equity" |
company_financial_list[].xbrlConceptPrefix |
string | no | The prefix for the tag, from the taxonomy in use. |
company_financial_list[].taxonomy |
string | no | Name (which includes the version) of the taxonomy used for the given financial year. |
company_financial_list[].dimensionsData |
array | yes |
The xbrlConcept isn't always sufficient to determine which tag is being used. For example, the XBRL concept "Equity" might fall under one of the several classifications, two such examples being "Capital redemption reserve" or "Retained earnings (Accumulated losses)".
In such cases, dimensionData contains the additional information to determine the exact nature of a tag.
Additionally,The dimensionsData values , are sometimes also used to specify time periods. For example, the XBRL concept "OtherDebtors" might have a corresponding
dimensionsData object with the XBRL Concept value of "CurrentFinancialInstruments" and description "Current financial instruments".
|
company_financial_list[].dimensionsData.dimension |
string | no | The dimension of a particular XBRL concept from the taxonomy. An example of this might be "FinancialInstrumentCurrentNon-current". |
company_financial_list[].dimensionsData.xbrlConcept |
string | no |
The XBRLConcept for the dimension property from the taxonomy being used. An example of this might be "CurrentFinancialInstruments".
|
company_financial_list[].dimensionsData.description |
string | no |
This is the description for company_financial_list[].dimensionsData.value XBRL concept property, from the taxonomy being used. An example of this might be "Current financial instruments"
|
title |
string | no | Name of the company as it appears on Companies House register |
errorMessage |
string | yes | Error message text, if available |
THIS WEBSITE USES COOKIES