Companies House UK Financials & Beneficial Owners Scraper

Extract UK company records from Companies House with parsed filed accounts (iXBRL) — turnover, profit, assets, director pay — plus officers, beneficial owners (Persons with Significant Control), and registered charges. Other Companies House actors stop at basic profile fields; this one parses the actual filed accounts documents into structured financials.

What You Get

Each record includes:

Company profile

• Company number, name, status (active/dissolved/liquidation), type (ltd/plc/llp/…)
• Incorporation date, registered office address, SIC codes
• Insolvency history flag, charges flag + counts (total / outstanding)
• Filing history entry count

Officers & beneficial ownership (each independently toggleable)

• Officers — JSON array of {name, role, appointed, resigned}
• Active directors count
• PSCs (Persons with Significant Control / beneficial owners) — JSON array of {name, kind, natures_of_control, notified_on}

Parsed financials (from the company's filed iXBRL accounts, when includeFinancials is on)

• Turnover, gross profit, operating profit, profit before/after tax
• Total assets, total-assets-less-current-liabilities, current assets, total liabilities, net assets
• Cash at bank, average employees, director remuneration, highest-paid director, audit firm name
• Accounts period end date and accounts_year (1 = most recently filed year)

Every financial field is null when the filer didn't tag that concept — never fabricated. Many small companies file abridged/micro-entity accounts that only disclose the balance sheet (assets, employees), not a profit & loss statement — turnover and profit legitimately come back null for those. total_assets_gbp is reserved for a genuine gross-assets tag; the very common small-company subtotal ("total assets less current liabilities" — fixed assets + net current assets) is a distinct, separately-reported field, total_assets_less_current_liabilities_gbp, so the two are never conflated.

Billing Unit

One record = one company profile (when includeFinancials is off, or a company has no accounts filings) or one company-year of parsed financials (when includeFinancials is on — one row per requested financialYears, each with its own accounts_year). Base company/officer/PSC/charge fields repeat across each year's row for the same company.

Query Modes

Mode	Uses input field	What it does
by_company_number	companyNumbers	Direct lookup — you already know the company number(s)
by_name	names	Keyword search against company names (Companies House /search/companies)
by_sic_code	sicCodes	Companies matching a UK SIC 2007 code
by_psc_name	pscNames	Search for companies by a beneficial owner's name
advanced_search	names	Company-name-includes substring search

Known limitation — by_psc_name: Companies House's documented /search/persons-with-significant-control endpoint returned zero results for every query tried against the standard free-tier API key during construction — including an exact name pulled straight from a real company's own live PSC record. The mode is wired per the documented API, but in practice you'll get more reliable beneficial-ownership data via by_company_number + includePscs: true against a company you already know.

Inputs

Field	Type	Default	Description
mode	select	by_company_number	Query mode — see table above
companyNumbers	array	—	Companies House company numbers (mode = by_company_number)
names	array	—	Company names / keywords (mode = by_name or advanced_search)
sicCodes	array	—	UK SIC 2007 codes (mode = by_sic_code)
pscNames	array	—	Beneficial owner names (mode = by_psc_name)
includeFinancials	boolean	true	Download + parse filed iXBRL accounts
financialYears	integer	3	How many years of accounts filings to parse per company (max 10)
includePscs	boolean	true	Include Persons with Significant Control
includeOfficers	boolean	true	Include officers (directors/secretaries)
includeCharges	boolean	false	Include registered charges (liens)
maxItems	integer	100	Maximum number of records (company-years) to process

Example Output

{
  "company_number": "10122954",
  "company_name": "DRAGONS HEAD SHOP LTD",
  "company_status": "active",
  "company_type": "ltd",
  "incorporation_date": "2016-04-14",
  "registered_office_address": "14, Broadview Road, London, SW16 5AU",
  "sic_codes": "47910|62012",
  "accounts_last_made_up_to": "2022-04-30",
  "accounts_next_due": "2027-01-31",
  "accounts_overdue": false,
  "has_been_liquidated": false,
  "has_charges": false,
  "total_charges_count": 0,
  "outstanding_charges_count": 0,
  "officers_count": 2,
  "active_directors_count": 2,
  "officers": "[{\"name\":\"Mr Lee Brook\",\"role\":\"director\",\"appointed\":\"2016-04-14\",\"resigned\":null}]",
  "psc_count": 2,
  "psc_controllers": "[{\"name\":\"Mr Lee Brook\",\"kind\":\"individual-person-with-significant-control\",\"natures_of_control\":\"ownership-of-shares-25-to-50-percent\",\"notified_on\":\"2016-04-14\"}]",
  "filing_history_count": 12,
  "accounts_period_end": "2022-04-30",
  "turnover_gbp": null,
  "gross_profit_gbp": null,
  "operating_profit_gbp": null,
  "profit_before_tax_gbp": null,
  "profit_after_tax_gbp": null,
  "total_assets_gbp": null,
  "total_assets_less_current_liabilities_gbp": 9616,
  "current_assets_gbp": 9032,
  "total_liabilities_gbp": null,
  "net_assets_gbp": 7656,
  "cash_at_bank_gbp": null,
  "employees_average": 2,
  "director_remuneration_gbp": null,
  "highest_paid_director_gbp": null,
  "audit_firm_name": null,
  "accounts_year": 1
}

This example is a real micro-entity filing — note turnover/profit are correctly null (this company's abridged accounts don't tag a profit & loss statement), while the balance-sheet fields that were actually tagged (assets, net assets, employees) come back as real numbers.

Notes

• This actor calls the official Companies House REST API and Document API directly. It does not scrape HTML.
• iXBRL parsing matches concepts by their FRC taxonomy local name, independent of the namespace prefix a filer's accounting software assigns (different real filings use uk-bus:, uk-core:, core:, or custom prefixes for the identical concept).
• Where a concept is tagged more than once (current year, prior-year comparative, or a dimensional note breakdown), the parser prefers the primary (non-dimensional) statement figure for the most recent period.
• This actor uses a single orblabs-managed API key shared across all runs (and with the sibling uk-companies-house-scraper actor) — you never need to supply your own.