UK Companies House Streaming Change Monitor

Get a typed, alert-ready event when a company on your watchlist has a Companies House change that matters to credit and compliance: an insolvency case (liquidation, administration, winding-up), a director / officer appointment or resignation, a PSC change (persons with significant control), a new or satisfied charge, a new filing, or a company status / name / address change. Built on the official Companies House Streaming API (not HTML scraping). You pay only when a change for a company on your list is delivered.

Quick start: replace the example company numbers with yours → set Source mode = live → paste your free Companies House Streaming API key (not the REST key) → save as a Task and schedule it every 5–15 minutes. Clicking Start with the defaults runs a free health check only (one RUN_STATUS row, no Companies House data).

Who this is for

• UK credit control, trade credit and B2B lending teams watching customer or debtor books for insolvency, new charges and director changes.
• KYB / KYC and compliance analysts who need ongoing PSC and officer change monitoring on companies they have already onboarded.
• Accountants, insolvency practitioners and corporate-development teams tracking client, supplier or target companies.

Not a company-search directory, not a bulk Companies House data dump, and not an always-on websocket.

Typical workflow

1. Export the company numbers you care about (8 characters, e.g. 01234567, SC123456).
2. Get a free Streaming API key from the Companies House developer hub (create a Streaming application key; the REST key will not work).
3. Run with sourceMode: "live" + your key, save it as a Task, and schedule it every 5–15 minutes.
4. Each run resumes from where the last one stopped and delivers only changes for companies on your list. Route new dataset items to Slack, email, a webhook or your CRM with Apify integrations, filtering on event_type (e.g. INSOLVENCY, OFFICER_RESIGNED, PSC_CEASED, CHARGE_CREATED).
5. Quiet periods deliver nothing and incur no change-event charges.

First run vs later runs

There is no "baseline" step for this Actor: the first live run starts from the current stream position, so you see an event as soon as a company on your list changes after you start. It does not backfill historical filings.

Example output (SAMPLE)

SAMPLE — illustrative values in the real output shape; XX000000 / EXAMPLE TRADING LIMITED are placeholders, not a real company or a real Companies House event.

{
  "company_number": "XX000000",
  "company_name": "EXAMPLE TRADING LIMITED",
  "event_type": "OFFICER_RESIGNED",
  "event_subtype": "deleted",
  "changed_fields": [],
  "published_at": "2026-09-12T09:05:00Z",
  "effective_date": "2026-09-12",
  "resource_kind": "officer-appointment",
  "resource_id": "example-officer-id",
  "summary": "XX000000 (EXAMPLE TRADING LIMITED): OFFICER_RESIGNED",
  "source_url": "https://api.company-information.service.gov.uk/company/XX000000/appointments/example-officer-id",
  "raw_source_reference": "officers:3002:example-officer-id",
  "detected_at": "2026-09-12T09:06:10.000Z",
  "event_uid": "<md5 of stream + resource + timepoint>",
  "stream": "officers",
  "timepoint": 3002,
  "billable": true
}

What you get per $0.015 event: one deduplicated change for one company on your watchlist (one dataset row like the sample above). Health rows, quiet runs, duplicates and companies not on your list are never charged.

Value proposition

• Catch up on official stream queues with resumable timepoints (not HTML scraping, not “diff two REST snapshots and hope”).
• Get structured events (NEW_FILING, OFFICER_*, PSC_*, STATUS_CHANGED, …) ready for Slack/webhooks/CRM — not opaque blobs.
• Pay only when we deliver a unique watchlist change. Quiet schedules stay cheap.
• One short scheduled run can drain multiple streams with durable state.

How it works (Approach A)

1. Schedule the Actor (e.g. every 5–15 minutes) with a watchlist of companyNumbers.
2. Each run connects briefly to the selected Streaming API endpoints, resumes from stored timepoints, and processes NDJSON until time/event/idle budgets.
3. Events for companies on your watchlist are normalized, deduplicated (event_uid), written to the dataset, and charged once under pay-per-event.
4. Timepoints are saved only after successful processing so a crash does not skip unpaid work incorrectly.
5. Every successful run also writes one non-billable RUN_STATUS health row so quiet / Store auto-test runs still leave a non-empty dataset.

This is near-real-time catch-up, not a guaranteed instant push consumer. Detection latency ≈ your schedule interval + stream lag. Companies House allows a maximum of two concurrent streaming connections per account; this design avoids forever-open connections.

PRODUCTION USE (required for real monitoring)

Store default ≠ product. Schema defaults use sourceMode=fixture so Apify Store daily auto-tests leave a non-empty health dataset without a Streaming key. That fixture path only writes a non-billable RUN_STATUS / FIXTURE_HEALTH row. It is not Companies House monitoring.

For production monitoring you must:

1. Set sourceMode = live
2. Provide secret input companiesHouseStreamingApiKey — a Companies House Streaming API key (not the free REST API key; they are different products)
3. Schedule short runs (e.g. every 5–15 minutes) with your companyNumbers watchlist

Official docs: Companies House Streaming API overview · Developer hub

Detection latency ≈ your schedule interval + stream lag. This Actor does not claim instant delivery or that it never misses an event (416 stale timepoints require resync; overlapping live runs can hit the 2-connection CH limit).

Apify Store daily auto-test / default input

Apify Store runs Actors daily with schema default input. Defaults are chosen so that path:

Field	Default
companyNumbers	["00000006","SC123456"]
streams	all 7 supported streams
maxRunSeconds	55
maxEvents	500
resumeFromStoredTimepoints	true
sourceMode	fixture
emitFixtureDemoEvents	false
maxIdleHeartbeats	3

On that path the Actor:

• SUCCEEDS quickly (no CH network call)
• Pushes exactly one dataset row: event_type: "RUN_STATUS", event_subtype: "FIXTURE_HEALTH", billable: false
• Does not call Actor.charge / does not emit fabricated filing/officer/PSC/company changes
• Leaves a non-empty default dataset within well under 5 minutes

emitFixtureDemoEvents: true is only for unit/local demos of typed change shapes; leave it false on Store and in production.

Features

• Streams: companies, filings, officers, persons-with-significant-control, persons-with-significant-control-statements, charges, insolvency-cases
• Watchlist filter with company-number normalization (trim, upper case, zero-pad)
• Durable timepoints + seen event_uids in the default Key-Value Store
• sourceMode: fixture | live — fixture default for Store auto-test / local CI without a streaming key
• Always-on non-billable RUN_STATUS health row (HEALTH_OK | MONITOR_IDLE | CATCHUP_COMPLETE | FIXTURE_HEALTH)
• Handles heartbeats (blank lines), 429 backoff guidance, 416 resync guidance
• Secret input for Streaming API key (never logged)

Input (summary)

Field	Notes
companyNumbers	Watchlist (required)
streams	Subset of streams (default: all supported)
maxRunSeconds	Wall-clock budget (default 55)
maxEvents	Max delivered change events per run
resumeFromStoredTimepoints	Default true
sourceMode	fixture (default, Store-safe) or live (production)
emitFixtureDemoEvents	Default false; gate for fabricated fixture changes
companiesHouseStreamingApiKey	Secret; Streaming key only — not the REST key
maxTotalChargeUsd	Optional budget hint
maxIdleHeartbeats	Leave a quiet stream after N blank heartbeats

Production example

{
  "companyNumbers": ["00000006", "SC123456"],
  "streams": ["filings", "officers", "charges"],
  "maxRunSeconds": 55,
  "sourceMode": "live",
  "companiesHouseStreamingApiKey": "YOUR_STREAMING_KEY",
  "resumeFromStoredTimepoints": true
}

Output

Change events (billable under PPE)

Dataset rows for real CH changes include: company_number, company_name, event_type, event_subtype, changed_fields, published_at, effective_date, resource_kind, resource_id, summary, source_url, raw_source_reference, detected_at, event_uid, billable: true.

RUN_STATUS health row (never billed)

Every successful run also pushes one row:

Field	Value
event_type	RUN_STATUS
event_subtype	HEALTH_OK | MONITOR_IDLE | CATCHUP_COMPLETE | FIXTURE_HEALTH
billable	false
summary	Honest counts: streams processed, events read/matched/delivered/charged, timepoints ok
resource_kind	actor-run-status

Quiet live runs (no watchlist matches) still SUCCEED with a MONITOR_IDLE (or similar) RUN_STATUS row — the dataset is never empty on success.

Pricing

Pay-per-event: change-event-delivered at $0.015 per delivered unique watchlist change.

Never charged: RUN_STATUS health rows, no-change runs, invalid company numbers, duplicates (event_uid), heartbeats, retries, filtered non-watchlist traffic, or fixture Store-health runs.

Limitations (honest)

• Near-real-time catch-up, not guaranteed sub-second delivery.
• Live mode needs a Companies House Streaming API key (separate from the free REST key).
• If a stored timepoint is too old, CH returns 416 — clear state and resync from an official snapshot if you need historical continuity.
• Max two concurrent CH streaming connections per account; do not run many overlapping live actors with the same key.
• Fixture mode does not contact Companies House; with default emitFixtureDemoEvents=false it only writes RUN_STATUS.

Data source

Companies House Streaming API — Crown copyright public data. Respect rate limits and attribution.

FAQ

Do I need an API key for local / Store default tests?
No — use sourceMode: "fixture" (the schema default). You get a RUN_STATUS / FIXTURE_HEALTH row only.

How do I run production monitoring?
Set sourceMode: "live" and your Streaming API key as a secret input.

Can I use my REST API key?
No. Streaming uses a distinct streaming key. Do not put either key in git.

Will I be charged on quiet days?
No — only delivered unique watchlist changes. RUN_STATUS is free.

Is this an always-on stream?
No. Short scheduled runs by design.

MCP / API notes

Run via Apify API, Scheduler, or MCP (https://mcp.apify.com) like any Actor. Pass the streaming key as a secret input field; never embed it in prompts or repos.