# UK Company Financials: Balance Sheets and New-Accounts Alerts (`tan-solutions/uk-company-financials`) Actor

UK company financials from Companies House accounts: net assets, current assets, creditors, cash and employees from the latest iXBRL filing, with your own free API key. Alerts when new accounts are filed. Not affiliated with Companies House.

- **URL**: https://apify.com/tan-solutions/uk-company-financials.md
- **Developed by:** [Tan Solutions](https://apify.com/tan-solutions) (community)
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 company delivereds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## UK Company Financials: Balance Sheets and New-Accounts Alerts

UK company financials from the latest accounts each company filed: net assets, current assets, creditors due within a
year, cash and employees, read from the structured (iXBRL) accounts document, not guessed from a PDF. Give it company
numbers, get one clean row per company. Turn on monitor mode and schedule it, and you get an alert row whenever one of
your companies files new accounts, with the key figures that moved. The data comes from the official Companies House
REST and Document APIs, called with **your own free API key**.

Not affiliated with Companies House or the UK Government.

### Run it from the API or on a schedule

Get the balance sheets back in one call (replace the two placeholders with your Apify token and your Companies House
key):

```bash
curl -X POST "https://api.apify.com/v2/acts/tan-solutions~uk-company-financials/run-sync-get-dataset-items?token=<YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"apiKey": "<YOUR_COMPANIES_HOUSE_KEY>", "companyNumbers": ["06534961", "SC404279"], "monitorId": "my-watchlist"}'
```

Watch the same companies every Monday at 07:00 UK time with an Apify schedule. The first run stores a baseline; every
later run returns only the companies that filed new accounts since the last run:

```bash
curl -X POST "https://api.apify.com/v2/schedules?token=<YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"name": "uk-financials-weekly", "cronExpression": "0 7 * * 1", "timezone": "Europe/London", "isEnabled": true, "isExclusive": true,
       "actions": [{"type": "RUN_ACTOR", "actorId": "3eNzAQGCUbJjcBrmW",
         "runInput": {"body": "{\"apiKey\":\"<YOUR_COMPANIES_HOUSE_KEY>\",\"companyNumbers\":[\"06534961\",\"SC404279\"],\"monitorId\":\"my-watchlist\"}", "contentType": "application/json"}}]}'
```

In Apify Console the same is: **Schedules**, **Create new**, cron `0 7 * * 1`, add this Actor with your input.

### What it does

- **Balance sheet figures from Companies House accounts:** net assets, current assets, net current assets, creditors
  due within one year, cash at bank and average number of employees, with the currency (GBP or the filing's own).
- **Accounts details:** accounts type (micro-entity, total exemption full, small, full, group, dormant and others),
  period end, made-up date, filing date and a dormant flag.
- **Source links:** a link to the accounts document and to the company's filing history on the public register, so
  every figure can be checked.
- **Monitor mode:** give the list a name (`monitorId`) and schedule the run. You get one alert row when a company
  files new accounts, listing which key figures (net assets, current assets, creditors) moved by your threshold
  (10 % by default) or changed sign.
- **Honest about gaps:** a company whose latest accounts were filed as PDF only gets a free `pdf-only` row with the
  link; a company that has not filed accounts yet gets a free `no-accounts` row.

It reads the balance sheet only. It does not return turnover or profit: most small UK companies file accounts without
a profit and loss account, so those figures are not on the public record.

### Who it is for

- **Credit control and trade credit:** check a customer's net assets and creditors before you extend terms.
- **Suppliers and procurement:** screen suppliers for negative net assets or a dormant company.
- **Lenders, brokers and due diligence:** a quick balance sheet view of many UK companies at once.
- **Portfolio and account monitoring:** a weekly alert when your watched companies file new accounts.
- **Developers:** feed uk balance sheet data into your own app, sheet or CRM through the Apify API.

### Quick start

1. Get your free key (below, about 2 minutes).
2. Paste it into the **Companies House API key** field.
3. Add company numbers and click **Start**.

### How to get a key in 2 minutes

The key is free and needs no card.

1. Sign in (or create a free account) at the Companies House Developer Hub:
   developer.company-information.service.gov.uk.
2. Go to **Your applications** and click **Create an application**. Give it any name, and choose the **Live**
   environment.
3. Open the application and click **Create new key**. Choose the key type **REST**. If the form offers IP address or
   JavaScript domain restrictions, leave them empty: Apify runs come from changing IP addresses, so a key restricted
   to IPs is refused.
4. Copy the key and paste it into this Actor's **Companies House API key** field (`apiKey`). It is stored as a secret
   input: it is never logged or written to the dataset.

Without a key the run still succeeds, but it returns only one free row that says "API key required".

### Input

| Field | What it means | Default |
| --- | --- | --- |
| Companies House API key (`apiKey`) | Your own REST API key (see above). Secret. | none |
| Company numbers (`companyNumbers`) | Register numbers, e.g. `06534961`, `SC404279`, `OC301540`. Spaces and lowercase are fine; short numbers are padded to 8 digits; duplicates are removed. | `06534961` |
| Monitor name (`monitorId`) | Turns on monitor mode: letters, digits and dashes, e.g. `my-watchlist`. The first run stores a baseline; later runs return only companies with new accounts. Use a different name for each list. | none (off) |
| Alert threshold (%) (`changeThresholdPercent`) | Monitor mode: a key figure counts as moved when it changes by at least this many percent, or changes sign. | 10 |
| Also list unchanged companies (`includeUnchanged`) | Monitor mode: also write a free row for each company with no new accounts. | off |
| Max companies (`maxCompanies`) | Stops after this many companies (1 to 10,000). | 1,000 |
| Requests per second (`requestsPerSecond`) | 0.2 to 2. Companies House allows 600 requests per 5 minutes per key. | 2 |

Example input:

```json
{
  "apiKey": "<your key>",
  "companyNumbers": ["06534961", "SC404279"],
  "monitorId": "my-watchlist",
  "changeThresholdPercent": 10
}
```

### Output

One row per company. A real row from a cloud run on 14 Nov 2026 (the default company, accounts made up to 31 March 2025,
shortened). The company name comes from the accounts as filed, so its letter case can differ from the register:

```json
{
  "input": "06534961",
  "companyNumber": "06534961",
  "companyName": "Manufacturing Capacity Solutions Limited",
  "status": "ok",
  "accountsType": "total-exemption-full",
  "dormant": false,
  "periodEnd": "2025-03-31",
  "madeUpDate": "2025-03-31",
  "filingDate": "2025-10-21",
  "currency": "GBP",
  "netAssets": 241481,
  "currentAssets": 431975,
  "netCurrentAssets": 196222,
  "creditorsWithinYear": 235753,
  "creditorsWithinYearDerived": false,
  "employees": 11,
  "cash": 183117,
  "documentFormat": "xhtml",
  "documentUrl": "https://find-and-update.company-information.service.gov.uk/company/06534961/filing-history/MzQ4NTc4MDc0M2FkaXF6a2N4/document?format=xhtml&download=0",
  "monitor": null,
  "alert": false,
  "error": null
}
```

Fields:

- `status`: `ok` (figures delivered), `pdf-only` (the latest accounts are a PDF only: no figures, the link is given),
  `no-accounts` (the company has not filed accounts yet) or `failed` (see `error`).
- `netAssets`, `currentAssets`, `netCurrentAssets`, `creditorsWithinYear`, `cash`, `employees`: from the latest
  accounts; `null` when the company did not file that figure (cash and employees are often missing).
- `creditorsWithinYearDerived`: `true` when the filing did not state creditors due within a year and the value was
  worked out as current assets minus net current assets.
- `dormant`: `true` for dormant-company accounts.
- `monitor`: `baseline` (first run of a monitor), `new-accounts` (alert row), `unchanged` (only with "Also list
  unchanged companies": a free row without figures) or `null` (monitor mode off). `alertReasons` and `changes` list the figures that moved, with
  the old and new value; `previousPeriodEnd` is the period of the accounts compared against.
- `error`: `null`, or a code and message: `INVALID_INPUT`, `NOT_FOUND`, `PDF_ONLY`, `NO_DOCUMENT`, `NO_FIGURES`,
  `DOCUMENT_TOO_LARGE`, `DOCUMENT_ERROR`, `PARSE_ERROR`, `HTTP_ERROR` or `API_KEY_REQUIRED`.

The run also writes a `SUMMARY` record (companies, delivered, free rows, PDF-only, no accounts, alerts, requests) to
the key-value store.

### Pricing

Pay per event: you are charged once per company row with status `ok` that carries figures (including monitor
baseline and alert rows). The price per 1,000 companies for your Apify plan is shown on the Pricing tab.

Free, never charged: `pdf-only` and `no-accounts` rows, `failed` rows (including `NO_FIGURES`, `INVALID_INPUT`,
`NOT_FOUND` and `API_KEY_REQUIRED`), unchanged companies in monitor mode, and companies a run did not fetch. A run
stopped by a rejected key charges nothing for the companies it did not fetch.

### Limits

- One company takes about 3 requests (filing history, document details, document). Companies House allows 600
  requests per 5 minutes per key, so 1,000 companies take roughly half an hour. When the window is used up, the Actor
  waits for it to reset and then goes on.
- Use one key per run at a time: two runs with the same key share the same limit.
- Up to 10,000 companies per run; accounts documents over 16 MB are skipped with a free `DOCUMENT_TOO_LARGE` row.
- Large and listed companies often file PDF accounts only; those come back as free `pdf-only` rows.
- Data is as current as the public register, which can be late or wrong. Figures are as filed, in the filing's
  currency; they are not audited or adjusted by us.

### FAQ

**Why do I need my own key?** Companies House gives each user a free key, and the rate limit (600 requests per 5
minutes) belongs to that key. With your own key you control your access and your limit, and the data comes straight
from the official API.

**Why are some companies `pdf-only`?** Their latest accounts were filed as a scanned or PDF document, not in the
structured iXBRL format, so there are no machine-readable figures. You get the link and you are not charged.

**Why is there no turnover or profit?** Most small and micro companies are allowed to file a balance sheet only.
This Actor does not return turnover or profit, so you never pay for empty columns.

**How does monitor mode know what changed?** It keeps the last accounts it saw for each company in a named
key-value store in your Apify account (`uk-financials-monitor-<your monitor name>`). Delete that store to start a
fresh baseline.

**My key is refused (HTTP 401 or 403).** A 401 means the key is wrong or incomplete, or it is a stream key: create a
REST key (step 3 above) and paste all of it. A 403 means the key is restricted to IP addresses or domains: create a
new REST key without restrictions.

### Related tools by Tan Solutions

- [US Company Filings & Financials](https://apify.com/tan-solutions/company-filings): 10-K, 10-Q, 8-K filings and XBRL
  financial facts of US public companies from SEC EDGAR.
- [Domain Intelligence](https://apify.com/tan-solutions/domain-intel): DNS, WHOIS/RDAP, SSL and tech stack of a
  company's website domain.
- [URL to Markdown](https://apify.com/tan-solutions/url-to-markdown): turn any web page into clean Markdown for LLMs,
  RAG and AI agents.
- [Document to Markdown](https://apify.com/tan-solutions/document-to-markdown): PDF, Word and PowerPoint files (annual
  reports, filings) to Markdown.
- [SEO Audit](https://apify.com/tan-solutions/seo-audit): on-page SEO checker with PageSpeed for any website.

### More from Tan Solutions

- [UK company financials tool page](https://www.tansolutions.org/tools/uk-company-financials/): details and examples for this Actor on our site.
- [Guide: Companies House API key, rate limit and fields](https://www.tansolutions.org/guides/companies-house-api-key-limits-fields/)
- [All Tan Solutions data tools](https://www.tansolutions.org/tools/)

### Data licence

Contains public sector information licensed under the Open Government Licence v3.0. The figures are taken from
accounts filed at Companies House and are passed on as filed.

### Your responsibilities

- You need your own Companies House API key and you are responsible for complying with the Companies House terms
  for its use.
- The output is company financial data. If you combine it with personal data, you are the controller of that
  personal data and must have a lawful basis under UK GDPR (or your own law).
- No warranty: register data can be wrong or late. Liability is capped at the fees you paid in the last 12 months.
- Not affiliated with Companies House or the UK Government. No Crown logo or GOV.UK branding is used.
- Questions and issues are answered within 14 days through the Actor's Issues tab.

Made by Tan Solutions.

# Actor input Schema

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

Your own REST API key from the Companies House Developer Hub (free, about 2 minutes: see the README). Do not restrict the key to IP addresses: Apify runs use changing IPs.

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

UK company numbers, for example 06534961, SC404279 or OC301540. Short numbers are padded to 8 digits. Duplicates are removed.

## `monitorId` (type: `string`):

Turns on monitor mode. Give the list a short name (letters, digits and dashes, for example my-watchlist) and schedule the run. The first run saves a baseline. Later runs write a row only when a company files new accounts, with how net assets, current assets and creditors moved. Companies with no new accounts are free.

## `changeThresholdPercent` (type: `integer`):

Monitor mode: a key figure counts as moved when it changes by at least this many percent, or changes sign.

## `includeUnchanged` (type: `boolean`):

Monitor mode: also write a free row (no figures) for each company with no new accounts.

## `maxCompanies` (type: `integer`):

Stop after this many companies (after duplicates are removed).

## `requestsPerSecond` (type: `number`):

Pace of calls to Companies House. 2 per second keeps within the 600-per-5-minutes limit of one key. Lower it if the same key is used elsewhere at the same time.

## Actor input object example

```json
{
  "companyNumbers": [
    "06534961"
  ],
  "changeThresholdPercent": 10,
  "includeUnchanged": false,
  "maxCompanies": 1000,
  "requestsPerSecond": 2
}
```

# Actor output Schema

## `results` (type: `string`):

One item per company: accounts type, period end, net assets, current assets, creditors due within a year, cash, employees and currency from the latest filed accounts; in monitor mode, alert rows for new accounts.

# 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": [
        "06534961"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("tan-solutions/uk-company-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": ["06534961"] }

# Run the Actor and wait for it to finish
run = client.actor("tan-solutions/uk-company-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": [
    "06534961"
  ]
}' |
apify call tan-solutions/uk-company-financials --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,tan-solutions/uk-company-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/3eNzAQGCUbJjcBrmW/builds/umsdSbhc7nS6J9B9i/openapi.json
