# Companies House Filing Monitor - UK Company Changes (`maydit/companies-house-filing-monitor`) Actor

Monitor filings for explicit UK company watchlists. Export filing dates, types, descriptions and document links, with saved new or changed observations. No API key.

- **URL**: https://apify.com/maydit/companies-house-filing-monitor.md
- **Developed by:** [Brandt May](https://apify.com/maydit) (community)
- **Categories:** Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.80 / 1,000 company filing observations

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

![Company filings, ready for review — illustrative workflow](https://api.apify.com/v2/key-value-stores/YGxD9JRpduom8Q5Zd/records/companies-house-filing-monitor-131608a83dcf.png?signature=12xvcD3FDZLfCJp4IEqyE)

### Company filings, ready for review

Maintain a sourced filing feed for supplier, customer or company research. This Actor reads bounded public Companies House filing-history pages and can compare saved filing metadata over time.

[Open this Actor in Console](https://console.apify.com/actors/ucwQgaRvyqjjs1n3v/input) · [First run](#try-this-actor) · [Results](#result-preview) · [Cost](#usage-and-pricing) · [Full guide](#full-guide)

### Try this Actor

1. **Choose a small scope.** Use the existing **Tesco filing feed** example below: company `00445790`, one filing-history page and at most five saved rows. Keep comparison off for a first look.
2. **Run and review.** Open the dataset for filing observations and the run's key-value-store `SUMMARY` for each company's page-window coverage. A company page failure does not produce paid partial-window rows.
3. **Use the results.** Export CSV for a filing list or JSON for comparisons. Follow the official document link when you need the underlying filing; this Actor does not download PDFs.

**Read this before using the data:** The filed date is not necessarily the transaction or effective date mentioned in a document. A bounded filing list is not a full archive or a legal/compliance verdict. The Actor does not send alerts itself.

**Tesco Company Filing History** — copy this input into the JSON editor in Console.

```json
{"companyNumbers":["00445790"],"maxResults":5,"maxSourcePages":1}
```

### Result preview

The dataset view highlights these columns:

- **Filing ID** · `filingId`
- **Company number** · `companyNumber`
- **Current company name** · `companyName`
- **Filed date** · `filedDate`
- **Filing type code** · `filingType`
- **Published description** · `description`

Use the original source links and the field definitions below when interpreting the results. CSV works well for flat columns; JSON preserves nested values.

### Usage and pricing

Base result rate on the FREE tier: **$3 per 1,000 company filing observations**. The [Pricing tab](https://apify.com/maydit/companies-house-filing-monitor/pricing) shows your plan's result rate and any Actor Start charge. Set a small result limit for the first run; the requested limit is not a guarantee of that many results.

***

### Full guide

Monitor a **small, explicit UK company watchlist** for new filings and changed filing descriptions or annotations. Export stable filing IDs, filed dates, type codes and official document links. The Actor uses public Companies House pages and needs no API key.

#### Why use it

Connect a supplier or customer watchlist to a repeatable filing feed. Each saved observation includes a stable transaction ID and a content hash. Optional named history identifies new or changed filings and provides the previous observation and changed fields. Use Apify integrations to consume the dataset; this Actor does not send alerts itself.

**Price:** $0.003 per saved filing on FREE/BRONZE, plus the configured $0.00005 start event. SILVER results are 20% less; GOLD and higher are 40% less. Unchanged observations skipped by `onlyChanges` have no result charge. Apify's configured prices govern the actual charge.

#### Fast default

`{}` reads one Tesco filing-history page and saves at most five filings. `companyNumbers` is an explicit watchlist, not a search or bulk export. A company number can be eight digits or a two-letter prefix with six digits; numeric strings are padded with leading zeros.

#### Inputs

| Field | Meaning |
|---|---|
| `companyNumbers` | Up to 20 explicit Companies House numbers. Empty uses `00445790` (Tesco). |
| `filingTypes` | Optional exact published codes such as `AA`, `CS01`, `SH03`; multiple codes are ORed. |
| `filedFrom`, `filedTo` | Optional inclusive `YYYY-MM-DD` bounds on the date filed at Companies House. |
| `maxSourcePages` | 1–3 official filing-history pages per company; default 1. |
| `maxResults` | Maximum saved rows, default 5 and maximum 1,000. |
| `comparePrevious` | Compare this exact watchlist and page/filter scope with saved observations; default false. |
| `onlyChanges` | Implies comparison and skips unchanged observations; default false. |
| `snapshotName` | Named history scope, default `default`. Use one writer for each name and scope. |
| `maxRunSeconds` | Own deadline, default 240 seconds, range 30–900; also respects the platform deadline with a 25-second reserve. |

The date/type filters inspect only the selected pages. Older matching records can be outside that window. The whole selected company window is fetched and validated before that company's results are emitted. A page failure makes that company incomplete and produces no paid partial company-window observations.

#### Output

One row per saved filing:

- `filingId` (`companyNumber:transactionId`), `transactionId`, `companyNumber`, `companyName`.
- `filedDate`, `filingType`, and `description` as published, including annotation text visible in the index.
- `documentPages` where the source publishes a page count; otherwise null.
- `url` (official document link), `sourceUrl`, `sourcePage`, `dateMeaning`, `contentHash`, `observedAt` and attribution.
- `comparisonStatus`: `not_requested`, `new`, `changed` or `unchanged`; `changedFields`, `previousObservedAt`, and `previous`.

**Date meaning matters:** `filedDate` is when the document was filed. A description may contain earlier transaction or effective dates. Those are preserved as text and never silently substituted for the filing date.

The content comparison covers filed date, filing type, description/annotations and page count. It does not compare PDF contents. A later company-name change updates the displayed current company name but does not label every historical filing as changed.

#### Three exact examples

##### Tesco filing feed

Use the [copyable first-run input](#try-this-actor) above.

##### Unilever accounts and confirmation statements

```json
{"companyNumbers":["00041424"],"filingTypes":["AA","CS01"],"maxResults":5,"maxSourcePages":1}
```

##### BP filing feed

```json
{"companyNumbers":["00102498"],"maxResults":5,"maxSourcePages":1}
```

#### Repeated observations

History is kept in the named key-value store `maydit-companies-house-filings-history`; `snapshotName`, company list, source-page window and filters define its scope. The first comparison run emits `new` observations and logs a warning. `onlyChanges` can legitimately return zero rows when the selected observations are unchanged.

History advances only for confirmed saved rows. A rejected spending-limit row never updates history. A final accepted row still counts if the SDK also signals the spending cap. If the saved result limit is smaller than the selected source window, a later `onlyChanges` run can emit previously unsaved filings from that same window. To establish a complete one-page comparison baseline, use one company and `maxResults:1000` for both baseline and repeat runs.

Before committing, the Actor re-reads history and rejects a detected concurrent change. This is an optimistic check, not an atomic lock: **run one writer per snapshot scope**. Malformed history is rejected, and a new `snapshotName` provides a clean baseline. Missing filings never generate deletion events; a bounded index does not prove a filing was removed.

#### Coverage and failures

`SUMMARY` reports `status`, `incomplete`, `rowsSaved`, `rowsObserved`, `unchangedSkipped`, `sourcesSucceeded`, `sourceCoverage`, `failedSources`, and limit flags. The normal bounded page or result cap is intentional scope, not a full company archive. An upstream, parser or deadline failure is explicit; if no usable observations can be saved, the run fails. Valid empty filters, unchanged repeats and a zero-result spending stop are reported without fake result rows.

The Actor does not search the company database, download PDFs, extract accounts, retrieve officer profiles or private contact details, or determine legal/compliance status. Public filing descriptions can name officers in their professional role. Company and filing facts are recorded as published, not independently verified.

#### Source and access

[Companies House guidance](https://www.gov.uk/guidance/searching-the-companies-house-register) states that the public service is available without registration. Its searchable databases are not intended for bulk downloads and may restrict high access volumes. This Actor uses bounded watchlists, checks robots rules, paces requests and stops on denied access. It does not bypass an API key: the separate official API requires credentials, while this product reads public HTML pages.

Source markup, temporary outages and shared cloud rate limits can change. A successful sample is not an availability guarantee. Contains public sector information licensed under the [Open Government Licence v3.0](https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/).

For support or correction/deletion requests, use Actor Issues or **bmay@mayd-it.com**.

### Help with your run

Open the **Issues** tab on this Actor with the run URL, the input field that caused trouble and what you expected to receive. Remove API keys and private information before posting.

[Explore more Mayd-It Actors](https://apify.com/maydit)

### Understand your run

Open **Run report** in the run’s Output tab for saved-record counts, reported source issues and limits, and suggested next steps. Use **CSV export** to take the saved results into a spreadsheet. The existing JSON results and detailed machine-readable summary remain available.

The report reflects this run’s recorded coverage. A successful run or a saved result does not establish that every possible source record was collected.

# Actor input Schema

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

Explicit watchlist of at most 20 Companies House numbers, including leading zeros or a two-letter prefix. Empty input uses Tesco 00445790. No bulk company discovery.

## `filingTypes` (type: `array`):

Optional exact published codes, such as AA, CS01 or SH03. Match is case insensitive; multiple codes are ORed.

## `filedFrom` (type: `string`):

Optional inclusive YYYY-MM-DD bound on the date filed at Companies House, not the effective date mentioned in a document.

## `filedTo` (type: `string`):

Optional inclusive YYYY-MM-DD filed-date upper bound. Only the selected source pages are inspected.

## `maxSourcePages` (type: `integer`):

Read 1–3 official filing-history pages per company. The chosen window is validated before output; additional older pages are not inferred or searched.

## `maxResults` (type: `integer`):

Upper bound on paid saved rows. Unchanged observations skipped by onlyChanges do not consume this limit.

## `comparePrevious` (type: `boolean`):

Compare within this exact configured watchlist/scope. The first run reports new observations; history advances only after confirmed saved output.

## `onlyChanges` (type: `boolean`):

Enables comparison and skips unchanged observations. First observations are emitted. A valid no-change run has zero results and a warning.

## `snapshotName` (type: `string`):

1–80 letters, numbers, underscores or hyphens. Use one writer per name/scope. Concurrent modification is checked before saving, but the store is not an atomic lock.

## `maxRunSeconds` (type: `integer`):

Own wall-clock deadline, also bounded by the platform deadline with a 25-second safety reserve. Network requests and retry delays stay within it.

## Actor input object example

```json
{
  "companyNumbers": [
    "00445790"
  ],
  "filingTypes": [],
  "maxSourcePages": 1,
  "maxResults": 5,
  "comparePrevious": false,
  "onlyChanges": false,
  "snapshotName": "default",
  "maxRunSeconds": 240
}
```

# Actor output Schema

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

No description

## `runReport` (type: `string`):

Readable summary of saved records, reported source coverage, limits and next steps. Available when this run saves its SUMMARY.

## `csvExport` (type: `string`):

Download saved dataset records as a CSV file for spreadsheets and other tools.

## `summary` (type: `string`):

No description

# 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": [
        "00445790"
    ],
    "filingTypes": []
};

// Run the Actor and wait for it to finish
const run = await client.actor("maydit/companies-house-filing-monitor").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": ["00445790"],
    "filingTypes": [],
}

# Run the Actor and wait for it to finish
run = client.actor("maydit/companies-house-filing-monitor").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": [
    "00445790"
  ],
  "filingTypes": []
}' |
apify call maydit/companies-house-filing-monitor --silent --output-dataset

```

## MCP server setup

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

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/ucwQgaRvyqjjs1n3v/builds/ZrNh3Etu0KgI2PbO1/openapi.json