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

Documentation

Try the API in browser

/api/financialsmetadata

This API endpoint returns the available financials meta data for a company using its Companies House registration number. This end point is free to call and can be used to determine which financial data fields are available for a given company before making a call to the financials end point to get the actual results.

Request

https://convert-ixbrl.co.uk/api/financialsMetaData?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

Name	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": "29/06/2021",
        "profit_loss": {
          "turnover": "available",
          "consolidated_accounts": null,
          "cost_of_sales": "available",
          "export": null,
          "gross_profit": "available",
          "directors_emoluments": null,
          "operating_profits": "available",
          "depreciation": null,
          "audit_fees": null,
          "interest_payments": null,
          "pre_tax": null,
          "tax_on_profit": "available",
          "profit_loss": "available",
          "post_tax": null,
          "dividends_payable": null,
          "retained_profits": "available",
          "salaries": null
        },
        "balance_sheet": {
          "intangible_assets": "available",
          "tangible_assets": "available",
          "fixed_assets": "available",
          "current_assets": "available",
          "stock": "available",
          "debtors_amounts_falling_due_within_one_year": "available",
          "debtors_amounts_falling_due_after_one_year": null,
          "creditors_amounts_falling_due_within_one_year": "available",
          "creditors_amounts_falling_due_after_more_than_one_year": null,
          "cash": "available",
          "net_current_assets_liabilities": "available",
          "total_assets": null,
          "total_assets_less_current_liabilities": "available",
          "total_current_liabilities": null,
          "liabilities": null,
          "net_assets": "available",
          "working_capital": null,
          "shareholders_equity": "available",
          "calledup_share_capital": "available",
          "retained_earnings_accumulated_losses": "available"
        },
        "cash_flow": {
          "cash_generated_from_operations": "available",
          "net_interest_paid_received_classified_as_operating_activities": "available",
          "income_taxes_paid_refund_classified_as_operating_activities": "available",
          "net_cash_flows_from_used_in_operating_activities": "available",
          "purchase_property_plant_equipment": "available",
          "proceeds_from_sales_property_plant_equipment": "available",
          "proceeds_from_sales_other_longterm_assets_classified_as_investing_activities": "available",
          "net_cash_flows_from_used_in_investing_activities": "available",
          "increase_decrease_in_cash_cash_equivalents_before_foreign_exchange_differences_changes_in_consolidation": "available",
          "cash_cash_equivalents_cash_flow_value": "available"
        },
        "allAvailableXBRLConceptsAndValues": [
          {
            "periodEnd": "29/06/2021",
            "description": "Turnover / revenue",
            "value": "available",
            "xbrlConcept": "TurnoverRevenue",
            "xbrlConceptPrefix": "core",
            "taxonomy": "secr-char-2019-01-01",
            "dimensionsData": null
          },
          {
            "periodEnd": "29/06/2021",
            "description": "Cost of sales",
            "value": "available",
            "xbrlConcept": "CostSales",
            "xbrlConceptPrefix": "core",
            "taxonomy": "secr-char-2019-01-01",
            "dimensionsData": null
          },
                    {... allAvailableXBRLConceptsAndValues will contain the full list of extracted xbrl tags. 

                        Numeric values for each tag will be replaced with "available" if the data was submitted as part of the IXBRL accounts and to null otherwise.}
                ]
            }
        ],
        "title":"Company Name Limited"
    },
    "errorMessage": null
}

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	This will contain available if the data is available and null if it isn't.
company_financial_list[].balance_sheet	object	yes	This will contain available if the data is available and null if it isn't.
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	This will contain available if the data is available and null if it isn't. The value of the XBRL tag, for example the monetary value of an Equity tag value refers to 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