UK Companies House Streaming Change Monitor

Watch a portfolio of UK companies and receive typed change events when Companies House publishes updates — filings, officers, persons with significant control (PSC), charges, insolvency cases, and company profile fields — via the official Companies House Streaming API.

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.