DEV Community

Steadfetch
Steadfetch

Posted on Edited on

Monitor UK Companies House changes as delta events — without building your own polling pipeline

#json #api #tutorial #data

If you build anything that touches UK companies — credit checks, KYB onboarding, supplier risk, B2B lead scoring — you eventually need to answer the same question continuously: what changed at the companies I care about?

The official Companies House public data API is free and well-documented. But it's a request/response register, not a feed. To watch a portfolio of companies you have to build the plumbing yourself: poll each record, store a snapshot per company, diff the fields you care about, and decide what counts as a "change" worth alerting on. That's a weekend of work to build and a permanent tax to maintain.

In this post I'll show how to get the same result with a hosted delta feed: companies-house-monitor, an Actor we run at Steadfetch. You keep a private watchlist, and every run returns only what changed — as validated JSON events you can pipe straight into your system.

(Full disclosure: we build this Actor. It reads only public register data.)

What you get

Each run emits delta events with a stable schema:

  • new_match — first delivery for a watch (or a new company matching a saved search)
  • status_changed — register status moved (active → liquidation, active-proposal-to-strike-off, dissolved…)
  • accounts_overdue_changed — the accounts-overdue flag flipped
  • risk_indicator — one of the risk signals: new insolvency case, new/satisfied charge, DS01 (dissolution request), registered-office change, late accounts filing

Every event carries company_number, company_name, company_status, the risk_sub_type and a human-readable risk_description, plus source_url (the public register page, for verification) and licence: "OGL v3". Only company-level fields are mapped — officer and PSC endpoints are never called, so no personal data comes back. That matters if your compliance team asks where the data comes from: it's public sector information under the Open Government Licence v3.0.

Two kinds of watches

A company watch tracks one register record. A query watch is a saved search: every newly incorporated company matching it becomes a new_match. That second one is underrated — it's how you get "tell me about every new UK company in renewable energy" without running your own crawl.

You manage the watchlist through the Actor itself, in manage mode. Management runs fetch no data and push nothing, so they don't bill a result.

Quickstart

Install the Apify CLI and add your first watch:

apify call steadfetch/companies-house-monitor --input='{
  "mode": "manage",
  "manage": {
    "action": "add",
    "targets": [
      { "type": "company", "company_number": "08209948" },
      { "type": "query", "query": "renewable", "since": "2026-01-01" }
    ]
  }
}'
Enter fullscreen mode Exit fullscreen mode

Then schedule a daily watch run:

apify call steadfetch/companies-house-monitor --input='{"mode":"watch","monitorMode":true,"maxResults":100}'
Enter fullscreen mode Exit fullscreen mode

The first watch run delivers a baseline; every later run delivers only changes. An unchanged watch returns 0 events.

From JavaScript 

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: '<YOUR_API_TOKEN>' });

const run = await client
  .actor('steadfetch/companies-house-monitor')
  .call({ mode: 'watch', monitorMode: true, maxResults: 100 });

const { items } = await client.dataset(run.defaultDatasetId).listItems();
for (const event of items) {
  console.log(event.event_type, event.company_number, event.risk_sub_type);
}
Enter fullscreen mode Exit fullscreen mode

From Python 

from apify_client import ApifyClient

client = ApifyClient("<YOUR_API_TOKEN>")

run = client.actor("steadfetch/companies-house-monitor").call(
    run_input={"mode": "watch", "monitorMode": True, "maxResults": 100}
)

for event in client.dataset(run.default_dataset_id).iterate_items():
    print(event["event_type"], event["company_number"])
Enter fullscreen mode Exit fullscreen mode

Wiring it into AI agents

If you're building agents rather than dashboards, the Actor is reachable through the hosted Apify MCP server, so your agent can call it as a tool:

{
  "mcpServers": {
    "apify": {
      "type": "http",
      "url": "https://mcp.apify.com/?tools=fetch-actor-details,steadfetch/companies-house-monitor"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

A typical agent loop: watch a portfolio, receive risk_indicator events (insolvency, new charge, DS01), and let the agent decide what to do — draft an email to your account manager, open a ticket, or flag the customer in your billing system.

Rate limits and your own API key

Companies House allows 600 calls per 5 minutes per API key. The Actor works out of the box with a shared key, but you should pass your own free Companies House key in the apiKey input to get the full budget for yourself.

Pricing, stated up front

The Actor is pay-per-event on Apify:

  • $4.00 per 1,000 delta events ($0.004 per event)
  • $0.05 per 1,000 monitor checks (one check per evaluated watch per run, even if nothing changed)
  • ~$0.0002 per run start at the default 4 GB memory (billed per GB of memory, 1 GB minimum)

An unchanged watch bills one check and zero events. manage runs bill neither. Failed watches and schema-rejected events are not billed. On the Apify free plan, the $5 monthly credit covers roughly 1,249 company records.

One-off snapshots: set monitorMode: false and every stored watch delivers its current state as new_match without touching your watchlist or billing checks.

Try it

If you build something with it or hit a rough edge, tell us in the comments — that's the fastest way we improve it.

Top comments (0)