Companies House IXBRL Accounts to Excel and JSON for company financials analysis

Documentation

Try the API in browser

/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 with requests exceeding this limit served with HTTP 429 code. Limit increase requests can be sent to support@convert-ixbrl.co.uk.

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`	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",
    "lastDataUpdatedDate": "31/10/2024"
    "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": "Will be added in a later api version",
            "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.
lastDataUpdatedDate	string	no	The date for the current dataset. This data is updated about once every four weeks.
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	Not populated in this API version. Will contain the name (which includes the version) of the taxonomy used for the given financial year, e.g. "secr-char-2019-01-01"
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