/api/financialsmetadata

This API endpoint returns available financials metadata for a company using its Companies House registration number. It is free to call and can be used to determine which financial data fields are available for a given company before making a request to financials endpoint to retrieve actual values.

Free Metadata Version 2

Version and Endpoint

Version 2 (current) Version 1

Request

https://convert-ixbrl.co.uk/api/financialsMetaData?companyNumber=012345678&apiVersion=2

All fields in response will be populated with either 'available' or null, depending on data availability.

Method Type

HTTP GET

Authentication

This endpoint requires the authentication header to be supplied. See the authentication section.

Request Parameters

HTTP GET

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

Name	Type	Optional	Description
apiVersion	string	No	API Version
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 Example (Only one year's data shown for brevity)

{
  "status": "Ok",
  "result": {
    "company_financial_list": [
            {
          "end_date": "31/03/2022",
          "profit_loss": {
            "turnover": "available",
            "cost_of_sales": "available",
            "administrative_expenses": "available",
            "distribution_costs": "available",
            "gross_profit_loss": "available",
            "operating_profit_loss": "available",
            "audit_fees": "available",
            "profit_loss": "available",
            "retained_profits": "available",
            "salaries": "available",
            "other_operating_income": "available",
            "other_interest_receivable_and_similar_income_finance_income": null,
            "interest_payable_and_similar_charges_finance_costs": "available",
            "profit_loss_on_ordinary_activities_before_tax": "available",
            "tax_taxcredit_on_profit_or_loss_on_ordinary_activites": "available",
            "depreciation_expense_property_plant_equipment": "available",
            "comprehensive_income_expense": null
          },
          "balance_sheet": {
            "fixed_assets": "available",
            "intangible_assets": null,
            "investments": "available",
            "investments_fixed_assets": "available",
            "investment_property": null,
            "investment_property_fair_value_model": null,
            "investments_in_subsidiaries": null,
            "investments_in_group_undertakings": null,
            "investments_in_group_undertakings_participating_interests": null,
            "investments_in_subsidiaries_measured_fair_value": null,
            "investments_in_joint_ventures": null,
            "investments_in_associates": null,
            "other_investments_other_than_loans": null,
            "disposals_investment_property_fair_value_model": null,
            "current_assets": "available",
            "current_asset_investments": null,
            "stock": "available",
            "debtors_amounts_falling_due_current": "available",
            "trade_debtors_amounts_falling_due_current": "available",
            "debtors_amounts_falling_due_non_current": null,
            "trade_debtors_amounts_falling_due_non_current": null,
            "cash": "available",
            "total_assets": "available",
            "liabilities": "available",
            "creditors_amounts_falling_due_current": "available",
            "trade_creditors_trade_payables_due_current": "available",
            "net_current_assets_liabilities": "available",
            "creditors_amounts_falling_due_non_current": "available",
            "trade_creditors_trade_payables_due_non_current": null,
            "total_borrowings": "available",
            "loans_from_directors": "available",
            "bank_overdrafts": null,
            "bank_overdrafts_current": null,
            "bank_overdrafts_non_current": null,
            "accrued_liabilities": "available",
            "government_grants_payable": null,
            "unpaid_contributions_to_pension_schemes_current": null,
            "unpaid_contributions_to_pension_schemes_non_current": null,
            "total_assets_less_current_liabilities": "available",
            "net_assets": "available",
            "shareholders_equity": "available",
            "calledup_share_capital": "available",
            "retained_earnings_accumulated_losses": "available"
          },
          "changes_in_equity": {
            "opening_retained_earnings_accumulated_losses": "available",
            "retained_earnings_accumulated_losses": "available",
            "share_capital": "available",
            "profit_loss_affecting_equity": "available",
            "dividends_paid": null,
            "comprehensive_income_expense": null
          },
          "other_notes_to_financial_statements": {
            "employee_count": "3",
            "wages_and_salaries": "available",
            "social_security_costs": "available",
            "pension_costs_defined_contribution_plan": null,
            "pension_other_post_employment_benefit_costs_other_pension_costs": null,
            "audit_fees_expenses": "available",
            "fees_for_non_audit_services": null,
            "government_grant_income": "available",
            "government_grants_payable": null,
            "amount_specific_advance_or_credit_made_in_period_directors": null,
            "amount_specific_advance_or_credit_directors": null
          },
          "cash_flow": {
            "interest_expense_on_bank_overdrafts": null,
            "tax_taxcredit_on_profit_or_loss_on_ordinary_activites": "available",
            "gain_loss_in_cash_flows_from_change_in_inventories": "available",
            "gain_loss_in_cash_flows_from_change_in_debtors_trade_other_receivables": "available",
            "gain_loss_in_cash_flows_from_change_in_creditors_trade_other_payables": "available",
            "net_cash_generated_from_operations": "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": null,
            "net_interest_received_paid_classified_as_investing_activities": null,
            "net_cash_flows_from_used_in_investing_activities": "available",
            "dividends_paid_classified_as_financing_activities": null,
            "net_cash_flows_from_used_in_financing_activities": "available",
            "IncreaseDecreaseInCashCashEquivalentsBeforeForeignExchangeDifferencesChangesInConsolidation": "available",
            "cash_bank_on_hand": "available",
            "cash_bank_on_hand_at_beginning_of_year": "available"
          }
        }

       
    ],
    "title": "Example Company Limited",
    "isFreeRepeatSearch": null
  },
  "errorMessage": null,
  "lastDataUpdatedDate": "{dd/MM/yyyy}"
}

Response Properties

Name	Type	Nullable	Description
status	string	no	Contains Ok if the request was successful, Error if there was an error.
errorMessage	string	yes	If the request was unsuccessful, this would contain a description of the error where available
result.company_financial_list	array	no	An array where each element contains financial data for a single year.
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.
company_financial_list[].balance_sheet	object	yes	Balance sheet properties, if available, for the given year, shown in the sample above.
company_financial_list[].cash_flow	object	yes	Cash flow statement properties, if available, for the given year, shown in the sample above.
company_financial_list[].changes_in_equity	object	yes	Statement of Changes in Equity properties, if available, for the given year, shown in the sample above.
company_financial_list[].other_notes_to_financial_statements	object	yes	All data extracted from 'Notes to Financial Statements' section for the given year, shown in the sample above.
lastDataUpdatedDate	string	no	Date when the company financial data was most recently updated, in dd/MM/yyyy format.
result	object	yes	Contains the financial data for the company, where available
company_financial_list[].end_date	string	yes	The financial year end date in "dd/MM/yyyy" format (e.g., 31/12/2020). This is null when the company has not filed iXBRL accounts yet (PDF-only filers).