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

Version and Endpoint

Version 2 (current) Version 1 (retired)

Request

POST https://convert-ixbrl.co.uk/api/findcompanies/metadata

Use this endpoint to get the count of companies matching your filter criteria before making a request to the main findcompanies endpoint.

https://convert-ixbrl.co.uk/api/findcompanies/metadata

Method Type

HTTP POST

Authentication

This endpoint requires authentication headers. See the Authentication documentation.

HTTP Response Codes

Status Code	Description
`200`	Successful request with count result
`400`	Invalid request, invalid/missing authentication headers, or invalid `financialFilters`.
`410`	`/api/findcompanies/count` and `/api/searchresultscount` are removed; use this endpoint.
`500`	Unexpected server error

Request Body

Same payload model as POST /api/findcompanies (FindCompaniesCriteria).

SIC lookup for the industries field: /Documentation/v2/SicCodes.

Request JSON Example

{
  "apiVersion": "2",
  "industries": [62020, 70229],
  "location": "Leeds",
  "locationMaxDistance": 30,
  "status": "Active",
  "directorAgeMin": 40,
  "directorAgeMax": 50,
  "directorAgeFilterType": "any",
  "financialFilters": [
    {
      "filterName": "TurnoverRevenue",
      "description": "TurnoverRevenue",
      "minValue": 5000000,
      "maxValue": 500000000
    }
  ]
}

Response Example

{
  "success": true,
  "count": 10535,
  "error": null,
  "errorMessage": null
}

If invalid financial filters are provided, this endpoint returns 400 with details and closest-match suggestions.

Error Response Example

{
  "success": false,
  "count": 0,
  "error": "InvalidFinancialFilters",
  "errorMessage": "One or more financial filters are invalid.",
  "validationErrors": [
    {
      "index": 0,
      "message": "Unknown filterName. Provide a valid filterName from the documentation.",
      "providedDescription": null,
      "providedFilterName": "TurnoverRevenuee",
      "suggestions": ["TurnoverRevenue", "NetAssetsLiabilities", "CashBankOnHand"]
    }
  ]
}

{
  "success": false,
  "count": 0,
  "error": "InvalidRequest",
  "errorMessage": "One or more request fields are invalid.",
  "validationErrors": [
    {
      "field": "locationMaxDistance",
      "message": "locationMaxDistance must be between 0 and 30."
    }
  ]
}

Validation Rules

searchTerm: minimum 3 characters (when provided) and only allowed characters used by portal validation.
locationMaxDistance: must be between 0 and 30.
directorAgeMin: must be at least 18 (if provided).
directorAgeMax: must be 98 or less (if provided).
Date ranges: invalid dates are rejected; for each pair, from cannot be later than to.
financialFilters: unknown filters and minValue > maxValue are rejected.

Response

Field	Type	Description
success	boolean	`true` on success, `false` on error.
count	integer	Total number of matching companies for the supplied filters.
error	string?	Machine-readable error code when `success=false`.
errorMessage	string?	Safe human-readable error message.
validationErrors	array?	Present for invalid financial filter requests.

Filter Definitions

The current filter definitions (labels/categories/filter keys) are listed below.

Note: financialFilters[].filterName is case-insensitive.

All Searchable Financial Filters

The filter keys shown below already remove the taxonomy prefixes (e.g. core_, direp_, aurep_). Use the values listed here when supplying financialFilters[].filterName in search or metadata requests.

The full list below represents the filters currently searchable via financialFilters payloads.

Filter Label	Category	Filter Key (financialFilters[].filterName)
Cash at Bank/On Hand	Assets	CashBankOnHand
Total Inventories	Assets	TotalInventories,OtherInventories
Total Assets	Assets	TotalAssets
Current Assets	Assets	CurrentAssets
Fixed Assets	Assets	FixedAssets
Net Current Assets Liabilities	Assets	NetCurrentAssetsLiabilities
Total Assets Less Current Liabilities	Assets	TotalAssetsLessCurrentLiabilities
Intangible Assets - All	Assets	IntangibleAssets
Intangible Assets, Gross / At Cost	Assets	IntangibleAssetsGrossCost
Intangible Assets - Accumulated Amortisation and Impairment	Assets	AccumulatedAmortisationImpairmentIntangibleAssets
Total Liabilities	Liabilities	TotalLiabilities
Accrued Liabilities	Liabilities	AccruedLiabilities
Debtors	Debtors	Debtors,OtherDebtors
Trade Debtors/ Trade Receivables	Debtors	TradeDebtorsTradeReceivables
Creditors	Creditors	Creditors,OtherCreditors,AccruedLiabilitiesNotExpressedWithinCreditorsSubtotal
Trade Creditors/ Trade Payables	Creditors	TradeCreditorsTradePayables
TurnoverRevenue	TurnoverRevenue and Profit/Loss	TurnoverRevenue
Profit/Loss	TurnoverRevenue and Profit/Loss	ProfitLoss
Net Cash Generated from Operations	TurnoverRevenue and Profit/Loss	NetCashGeneratedFromOperations
Interest Income on Bank deposits	TurnoverRevenue and Profit/Loss	InterestIncomeOnBankDeposits
Pension and other post-employment benefit costs / other pension costs	Tax, Pension and Benefits	PensionOtherPost-employmentBenefitCostsOtherPensionCosts
Pension costs - Defined Contribution Plan	Tax, Pension and Benefits	PensionCosts
Pension - Unpaid contributions to Pension Schemes	Tax, Pension and Benefits	UnpaidContributionsToPensionSchemes
Social Security, Taxation and other related costs	Tax, Pension and Benefits	SocialSecurityCosts,OtherTaxationSocialSecurityPayable,TaxationSocialSecurityPayable,TaxationSocialSecurityPayable
Corporation Tax Payable	Tax, Pension and Benefits	CorporationTaxPayable
Government Grant Income	Grants	GovernmentGrantIncome
Government Grants Payable	Grants	GovernmentGrantsPayable
Employee Wages & Salaries	Employees and Salaries	WagesSalaries
Director Salaries and Fees	Employees and Salaries	SalariesFeesDirectors
Average Number of Employees	Employees and Salaries	AverageNumberEmployeesDuringPeriod
Amount of Specific Advance or Credit Made in Period to Directors	Uncategorised	AmountSpecificAdvanceOrCreditMadeInPeriodDirectors
Amount of Specific Advance or Credit Made to Directors	Uncategorised	AmountSpecificAdvanceOrCreditDirectors
Total Borrowings	Liabilities	TotalBorrowings
Bank Overdrafts	Liabilities	BankOverdrafts
Bank Borrowings	Liabilities	BankBorrowingsOverdrafts
Other Remaining Borrowings	Liabilities	OtherRemainingBorrowings
Loans From Directors	Liabilities	LoansFromDirectors
Amounts Owed to Directors	Liabilities	AmountsOwedToDirectors
Advances and Credits Repaid in Period to Directors	Liabilities	AdvancesCreditsRepaidInPeriodDirectors
Finance Lease Liabilities - Present Value Total	Liabilities	FinanceLeaseLiabilitiesPresentValueTotal
Investments	Investments	Investments
Investments - Fixed Assets	Investments	InvestmentsFixedAssets
Investments - Property	Investments	InvestmentProperty
Investments - Property Fair Value Model	Investments	InvestmentPropertyFairValueModel
Investments - Current Asset	Investments	CurrentAssetInvestments
Investments - Other (excluding loans)	Investments	OtherInvestmentsOtherThanLoans
Investments - Group Undertakings	Investments	InvestmentsInGroupUndertakings,InvestmentsInGroupUndertakingsParticipatingInterests
Investments - In Subsidiaries	Investments	InvestmentsInSubsidiaries,InvestmentsInSubsidiariesMeasuredFairValue
Investments - In Associates	Investments	InvestmentsInAssociates
Investments - In Joint Ventures	Investments	InvestmentsInJointVentures
Investments - Disposals(Property, Fair Value Model	Investments	DisposalsInvestmentPropertyFairValueModel
Net Assets/Liabilities	Equity	NetAssetsLiabilities
Equity - All	Equity	Equity
Number of Shares Fully Paid	Equity	NumberSharesIssuedFullyPaid
Dividends Paid	Equity	DividendsPaidOnShares,DividendsPaid
Called Up Share Capital Not Paid	Equity	CalledUpShareCapitalNotPaidNotExpressedAsCurrentAsset
Called Up Share Capital Not Paid	Equity	CalledUpShareCapitalNotPaid
Property, Plant & Equipment	Property, Plant & Equipment	PropertyPlantEquipment
Property, Plant & Equipment Gross Cost	Property, Plant & Equipment	PropertyPlantEquipmentGrossCost
Audit - Fee/Expenses	Audit Related Fees	AuditFeesExpenses
Audit - Fee for Non Audit Services	Audit Related Fees	FeesForNonauditServices,OtherNonauditServicesFees