# Companies House Financials: accounts, filings, iXBRL data (`spongy_frame/companies-house-financials`) Actor

Extract UK company profiles, accounts filing history and parsed iXBRL financials (turnover, profit, net assets, cash) from Companies House. No personal data.

- **URL**: https://apify.com/spongy\_frame/companies-house-financials.md
- **Developed by:** [Spongy Frame Tools](https://apify.com/spongy_frame) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 company profiles

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

### What does Companies House Financials do?

Companies House Financials turns a list of UK company numbers (or company names) into clean, structured JSON: the company profile, its accounts filing history, and, where the accounts were filed digitally, the actual financial figures parsed straight out of the iXBRL document. You get turnover, gross and operating profit, profit before and after tax, net assets, total assets, cash, creditors, equity, share capital, dividends and average employee numbers for the current and prior period, without opening a single PDF.

Everything comes from the official Companies House Public Data API and Document API. The Actor never touches officers, persons with significant control or disqualified-directors endpoints and never outputs a person's name, date of birth, nationality, occupation or home address. It is built for credit checks, lead qualification, market sizing, supplier due diligence and research on UK limited companies.

### Why use this one?

- **Real numbers, not just metadata.** Most UK company data tools stop at status, SIC codes and filing dates. This one reads the iXBRL accounts and returns the figures as typed numbers with the period they belong to and the currency.
- **Current and prior period side by side.** Every parsed document gives you a `current` and a `prior` block, so growth and trend calculations need no extra work.
- **Names or numbers.** Paste `00445790` or `Tesco PLC`; names are resolved through the Companies House search and flagged `resolved_from_search` so you can audit the match.
- **Official source, no scraping risk.** Data comes through the documented API with your own free key, at a rate that respects the 600-requests-per-5-minutes limit, with retries and `Retry-After` handling built in.
- **Privacy by design.** No personal data endpoints are called, and director names embedded in accounts documents are dropped during parsing.
- **Honest about limits.** Accounts filed as PDF only (most filings before 2016 and some audited group accounts) cannot be parsed; they are reported as `financials: []` with `accounts_parse_status: "no_ixbrl_available"` rather than guessed.

### How to use it

1. **Get a free Companies House API key (about 2 minutes).** Go to [developer.company-information.service.gov.uk](https://developer.company-information.service.gov.uk/), sign in or register, open *Your applications*, create an application of type *REST*, and add a *REST API key*. Copy the key.
2. **Give the Actor the key.** Either paste it into the `apiKey` input field (stored as a secret) or set the environment variable `COMPANIES_HOUSE_API_KEY` in the Actor's settings. If neither is present the run stops immediately with a clear message.
3. **Enter company numbers or names and run.** Results land in the dataset; a `SUMMARY` record and any `FAILURES` are written to the key-value store.

### Input

```json
{
  "companyNumbers": ["00445790", "00102498", "SC327000", "Widget Makers Ltd"],
  "maxItems": 100,
  "parseAccounts": true,
  "accountsYears": 1,
  "includeFilingHistory": true,
  "includeRegisteredAddress": true,
  "outputFormat": "full"
}
```

- `companyNumbers`: 8-character numbers, shorter numeric values (padded with leading zeros), prefixed numbers such as `SC`, `NI`, `OC`, or company names.
- `maxItems`: stop after this many companies.
- `parseAccounts` and `accountsYears`: parse the latest 1 to 5 iXBRL accounts documents per company.
- `includeFilingHistory`: last 10 accounts filings with public document links.
- `includeRegisteredAddress`: the registered office (a corporate address).

### Output

One item per company:

```json
{
  "company_number": "01234567",
  "company_name": "WIDGET MAKERS LIMITED",
  "company_status": "active",
  "company_type": "ltd",
  "incorporated_on": "2009-05-01",
  "dissolved_on": null,
  "sic_codes": ["28990"],
  "registered_office_address": {
    "address_line_1": "2 Example Street", "address_line_2": null,
    "locality": "London", "region": null, "postal_code": "EC1A 1AA", "country": "United Kingdom"
  },
  "accounts": {"next_due": "2025-12-31", "last_made_up_to": "2024-03-31", "overdue": false, "accounting_reference_date": "03-31"},
  "confirmation_statement": {"next_due": "2025-05-15", "overdue": false},
  "has_charges": false,
  "has_insolvency_history": false,
  "filing_history": [
    {"date": "2024-11-20", "type": "AA", "description": "accounts-with-accounts-type-unaudited-abridged",
     "category": "accounts", "made_up_date": "2024-03-31", "transaction_id": "MzQw...",
     "document_url": "https://find-and-update.company-information.service.gov.uk/company/01234567/filing-history/MzQw.../document?format=pdf&download=0"}
  ],
  "financials": [
    {
      "period_end": "2024-03-31", "period_start": "2023-04-01", "currency": "GBP",
      "accounts_type": "Full accounts (Unaudited)", "balance_sheet_date": "2024-03-31",
      "entity_name": "WIDGET MAKERS LIMITED",
      "current": {"turnover": 1234567, "gross_profit": 456789, "operating_profit": -12500,
                  "profit_before_tax": -15000, "profit_after_tax": -16200, "net_assets": 250500,
                  "total_assets": 430500, "current_assets": 180500, "fixed_assets": 250000, "cash": 42300,
                  "creditors_due_within_one_year": 120000, "creditors_due_after_one_year": 60000,
                  "total_equity": 250500, "shareholder_funds": null, "average_employees": 12,
                  "dividends_paid": 0, "called_up_share_capital": 100},
      "prior": {"turnover": 1100000, "...": "..."},
      "parsed_concepts_count": 32,
      "unmapped_concepts_sample": ["DepreciationExpenseFixedAssets", "WagesSalaries"],
      "source_document_id": "abc123"
    }
  ],
  "accounts_parse_status": "parsed",
  "resolved_from_search": false,
  "source_url": "https://find-and-update.company-information.service.gov.uk/company/01234567",
  "fetched_at": "2026-09-24T10:15:00+00:00"
}
```

`accounts_parse_status` is one of `parsed`, `no_ixbrl_available` (PDF only), `no_accounts_filed`, `parse_failed`, `skipped` (parsing disabled) or `skipped_charge_limit`. Fields that the filer did not tag are `null`.

### How much does it cost?

The Actor is pay-per-event. You pay only for what is produced.

| Event | Charged when | Price |
|---|---|---|
| `company-profile` | a company item is pushed to the dataset | $0.004 |
| `accounts-parsed` | an iXBRL accounts document is parsed successfully (at least 3 mapped concepts) | $0.03 |

Companies that are not found are recorded under `FAILURES` and are not charged. PDF-only accounts are not charged.

**Example 1: 500 companies, profile and filing history only** (`parseAccounts: false`): 500 × $0.004 = **$2.00**.

**Example 2: 500 companies with the latest accounts parsed**, of which 420 have iXBRL: 500 × $0.004 + 420 × $0.03 = $2.00 + $12.60 = **$14.60**. Add `accountsYears: 3` and the accounts part roughly triples.

Platform compute is included in these prices; nothing else is billed.

### Limits and fair use

- Companies House allows 600 requests per 5 minutes per key. The Actor paces itself at 2 requests per second and backs off on `429`, so around 1,500 to 2,500 companies per hour is a realistic throughput with accounts parsing on.
- Each company needs 2 to 6 API calls (profile, filing history, document metadata and document content per parsed year, plus a search call for names).
- iXBRL documents are typically 200 KB to 2 MB; very large audited group accounts may take a few seconds each.
- `maxItems` caps the number of companies, and runs also stop cleanly when your Apify spending limit for an event is reached.
- Name lookups take the top exact-ish search match; check `resolved_from_search` and `search_query` if precision matters, or supply numbers.

### Legal note

All data is retrieved from the Companies House Public Data API and Document API under the [Companies House API terms](https://developer.company-information.service.gov.uk/) and is Crown copyright, reusable under the Open Government Licence. This Actor deliberately excludes officer, PSC, disqualified-officer and UK-establishment endpoints and strips person names from parsed documents; the only address returned is the company's registered office. You remain responsible for how you use the output.

### FAQ

**Why did my run stop early?**
Either `maxItems` was reached, your Apify spending limit for `company-profile` or `accounts-parsed` was hit (the log says which), or the API key was rejected (`401`), which stops the run immediately. Check the run log and the `SUMMARY` record.

**Why is `financials` empty for a company?**
The latest accounts were filed as a PDF only (`no_ixbrl_available`), no accounts have been filed yet (`no_accounts_filed`), or the document could not be parsed (`parse_failed`). Try `accountsYears: 2` or `3` to reach an older iXBRL filing.

**Some figures are `null`. Is that a bug?**
Small companies file abridged or micro-entity accounts and often do not tag turnover or profit at all. `null` means the filer did not tag that concept. `unmapped_concepts_sample` shows what they did tag.

**Do I need to pay Companies House?**
No. The API key is free and there is no usage fee; the limit is 600 requests per 5 minutes.

**Can I get directors or shareholders?**
No, by design. This Actor does not call those endpoints and does not output personal data.

### Support

Use the Issues tab on the Actor page for bugs and feature requests. We answer within 24 hours on working days.

# Actor input Schema

## `companyNumbers` (type: `array`):

Companies House numbers (e.g. 00445790, SC327000, 1234567 is padded to 01234567) or company names (resolved via the Companies House search, top match, flagged `resolved_from_search`).

## `apiKey` (type: `string`):

Free key from https://developer.company-information.service.gov.uk/ (create a REST API application, 2 minutes). Leave empty to use the COMPANIES\_HOUSE\_API\_KEY environment variable instead.

## `maxItems` (type: `integer`):

Stop after this many companies have been pushed to the dataset.

## `parseAccounts` (type: `boolean`):

Download the latest accounts filed in iXBRL format and extract turnover, profit, net assets, cash, creditors, employees and more. Accounts filed as PDF only cannot be parsed.

## `accountsYears` (type: `integer`):

How many of the most recent iXBRL accounts documents to parse per company (1 to 5). Each parsed document is charged as an `accounts-parsed` event.

## `includeFilingHistory` (type: `boolean`):

Add the last 10 accounts filings (date, type, description, made-up date, public document link).

## `includeRegisteredAddress` (type: `boolean`):

Include the company's registered office address (a corporate address, not personal data).

## `outputFormat` (type: `string`):

`full` returns every field. Reserved for future compact formats.

## Actor input object example

```json
{
  "companyNumbers": [
    "02012715",
    "08130873",
    "09446231"
  ],
  "maxItems": 5,
  "parseAccounts": true,
  "accountsYears": 1,
  "includeFilingHistory": true,
  "includeRegisteredAddress": true,
  "outputFormat": "full"
}
```

# Actor output Schema

## `dataset` (type: `string`):

One record per company: profile, accounts filing history and parsed iXBRL financials (current and prior period). No officer or PSC data.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "companyNumbers": [
        "02012715",
        "08130873",
        "09446231"
    ],
    "maxItems": 5,
    "accountsYears": 1
};

// Run the Actor and wait for it to finish
const run = await client.actor("spongy_frame/companies-house-financials").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "companyNumbers": [
        "02012715",
        "08130873",
        "09446231",
    ],
    "maxItems": 5,
    "accountsYears": 1,
}

# Run the Actor and wait for it to finish
run = client.actor("spongy_frame/companies-house-financials").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "companyNumbers": [
    "02012715",
    "08130873",
    "09446231"
  ],
  "maxItems": 5,
  "accountsYears": 1
}' |
apify call spongy_frame/companies-house-financials --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,spongy_frame/companies-house-financials"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/WdHGbUIQhHIoNiise/builds/PvopofWaqHdkbzQ8Y/openapi.json