UK Company Change Alerts

Check basic UK company register facts from the official Companies House URI JSON service and emit only the changes observed since the previous run. The Actor does not need a Companies House API key, account, login, cookie, proxy, or browser automation.

This is a factual change feed, not a credit report, identity product, legal opinion, or insolvency prediction. The name deliberately avoids CompanyWatch, which is already used by an established UK financial-risk provider.

Input

{
  "companyNumbers": ["02050399", "SC002180"],
  "monitorId": "supplier-watchlist",
  "emitUnchanged": false
}

Provide 1-100 company numbers. Values are uppercased and duplicates are checked once. Company numbers are never treated as URLs. Keep the same monitorId on later runs. It selects a named Key-Value Store that persists the baseline across separate Actor runs. Use a different ID for an independent watchlist.

Copy-paste REST quickstart

Use an Apify API token from your own account and keep it in an environment variable. The token belongs in the Authorization header, not in a URL or a public workflow export.

curl -X POST \
  'https://api.apify.com/v2/actors/ai-coding-radar~uk-company-change-alerts/run-sync-get-dataset-items?clean=1' \
  -H "Authorization: Bearer $APIFY_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"companyNumbers":["02050399"],"monitorId":"supplier-watchlist","emitUnchanged":false}'

The generated API client's empty {} input is also safe: it checks only the single public example company 02050399 under the default baseline. Use an explicit monitorId for every real watchlist so unrelated baselines never mix.

The first successful call for a new monitorId returns baseline_created. Repeat the same request with the same ID; a healthy no-change run returns an empty array, and later register differences return changed rows. Source failures remain explicit error rows. Each call uses the Store's published pay-per-event price.

Automate alerts without writing code

• Duplicate the ready-to-run daily UK supplier status and filing alerts task.
• Import the ready-made n8n daily monitoring workflow.
• Follow the n8n and Make setup recipe.
• Or create an Apify Task from this Actor and schedule it daily or weekly. Keep the same monitorId so later runs compare against the same baseline.

The first successful run creates a baseline. The example workflow sends rows downstream only for actual field changes or source failures, so baseline and unchanged checks do not create false alerts. Every run uses the caller's own Apify account and the Store's published pay-per-event pricing.

Run semantics

1. The Actor fetches https://data.companieshouse.gov.uk/doc/company/{number}.json.
2. On the first successful run for a number, it stores a baseline in the named Apify Key-Value Store selected by monitorId and emits one baseline_created row whose currentValue contains the selected basic fields.
3. On later runs, it compares the baseline and emits one changed row per changed field. Unchanged checks emit no dataset row; the terminal status still reports how many were checked.
4. A successful check updates the baseline even when no fields changed.
5. A missing company emits source_not_found; an HTTP, network, JSON, or payload failure emits source_error. Error rows contain a safe error code and message and never include a response body.

Set emitUnchanged to true when a non-empty audit heartbeat is more useful than a change-only feed. Each successful check with no differences then emits one unchanged row without charging a change-event. The public Store health check uses this mode so repeated daily self-tests remain healthy; alerting workflows should normally keep the default false and trigger only when rows are present.

The baseline key is COMPANY_BASELINE_V1. Each Actor run receives a new default Key-Value Store, so the Actor deliberately opens the persistent named store uk-company-change-alerts-{monitorId}. Changing monitorId intentionally starts an independent baseline.

Watched fields

The first version intentionally stays narrow and excludes directors, PSCs, birthdays, officer address profiles, and any derived score:

• company name, status, country of origin, incorporation/dissolution dates
• registered office address
• previous names
• accounts and returns filing dates/categories
• mortgage charge counts
• SIC code text

Every row links back to the official URI and includes an observedAt timestamp. Values are copied from the public register response; no AI interpretation is added. The URI service is documented by Companies House as a free basic-data service that can be used in software and can return JSON, XML, CSV, YAML, RDF, or HTML:

• Companies House data products
• URI customer guide
• Official URI JSON example

The URI guide is old and Companies House does not publish a freshness SLA for this endpoint. Use a daily or weekly schedule, treat observedAt as the local observation time, and do not market the result as guaranteed real-time data.

Dataset rows

Each row contains:

{
  "companyNumber": "02050399",
  "companyName": "Example Company Limited",
  "observedAt": "2026-08-14T08:00:00Z",
  "sourceUrl": "https://data.companieshouse.gov.uk/doc/company/02050399.json",
  "status": "changed",
  "field": "companyStatus",
  "previousValue": "active",
  "currentValue": "dissolved",
  "errorCode": null,
  "errorMessage": null
}

Pay-per-event setup

Configure these events on the Apify Console publication page. Prices are intentionally explicit and are not inferred from traffic or estimates:

Event	Meaning	Suggested price
apify-actor-start	One Actor start	$0.00005
company-check	One successful company source check, including a baseline or unchanged check	$0.003
change-event	One changed field emitted in the dataset	$0.01

Source errors, not-found records, and rejected input are not charged as company-check. The Actor charges successful checks and changed fields through the Apify SDK; the actual event prices are configured in the Store publication wizard. Pass platform usage through to users if the Console offers that option.

Privacy and operational boundaries

• Uses only the official public Companies House URI JSON endpoint.
• No API key, OAuth, cookie, CAPTCHA, proxy, scraping, or browser RPA.
• Does not fetch or publish officer/PSC profiles, birthdays, or risk scores.
• Keeps the public company registered-office field; for some companies that can also be a residential address, so downstream users must handle it as potentially personal data.
• Keeps only the selected company-level baseline in the named Key-Value Store.
• Does not claim that a source failure, missing field, or unchanged check is a successful change.
• The publisher remains responsible for any applicable data-protection, copyright, and other legal obligations when redistributing public-register data. See the Companies House personal information charter.

Local checks

python3 -m unittest discover -s tests -v
python3 -m compileall -q uk_company_change_alerts
npx --yes apify-cli validate-schema

Offline fixture mode accepts a JSON object mapping company numbers to the primaryTopic object returned by the URI endpoint:

python3 -m uk_company_change_alerts.main --fixture tests/fixtures/sample.json