Documentation
/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
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
| 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).
|