Documentation
/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 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
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 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": "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.
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