# UK Company Change Alerts (`ai-coding-radar/uk-company-change-alerts`) Actor

Monitor official UK Companies House records for status, registered office, filings, SIC, accounts, mortgages, and name changes. Persistent no-key company change API for supplier watchlists and due diligence. Factual data only; no directors, scores, login, proxy, or scraping.

- **URL**: https://apify.com/ai-coding-radar/uk-company-change-alerts.md
- **Developed by:** [AI Coding Radar](https://apify.com/ai-coding-radar) (community)
- **Categories:** Automation, Developer tools, Open source
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 company checks

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## 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

```json
{
  "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.

```sh
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](https://apify.com/ai-coding-radar/uk-company-change-alerts/examples/daily-uk-supplier-status-alerts) task.
- Import the ready-made [n8n daily monitoring workflow](https://github.com/Jarvis-Dong/uk-company-change-alerts/blob/main/examples/n8n-uk-company-alerts.json).
- Follow the [n8n and Make setup recipe](https://github.com/Jarvis-Dong/uk-company-change-alerts/blob/main/examples/README.md).
- 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](https://www.gov.uk/guidance/companies-house-data-products)
- [URI customer guide](https://assets.publishing.service.gov.uk/media/5d08c0f340f0b6094a379078/uniformResourceIdentifiersCustomerGuide.pdf)
- [Official URI JSON example](https://data.companieshouse.gov.uk/doc/company/02050399.json)

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:

```json
{
  "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](https://www.gov.uk/government/organisations/companies-house/about/personal-information-charter).

### Local checks

```sh
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:

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

# Actor input Schema

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

Company numbers such as 02050399 or SC002180. Enter values without spaces; duplicate values are checked once.

## `monitorId` (type: `string`):

A stable ID for this watchlist. Reuse it on later runs so the named state store preserves the baseline.

## `emitUnchanged` (type: `boolean`):

Write one unchanged row for each successful check with no differences. Useful for audit logs and health checks; leave disabled for change-only alerts.

## Actor input object example

```json
{
  "companyNumbers": [
    "02050399"
  ],
  "monitorId": "default",
  "emitUnchanged": false
}
```

# Actor output Schema

## `results` (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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("ai-coding-radar/uk-company-change-alerts").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("ai-coding-radar/uk-company-change-alerts").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 '{}' |
apify call ai-coding-radar/uk-company-change-alerts --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,ai-coding-radar/uk-company-change-alerts"
        }
    }
}

```

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/xB4MWIkxXc41GKtfM/builds/cWPBDDiCREdRpcUIM/openapi.json