# UK Supplier and Customer Risk Watch (`fractionalhqforyou/uk-counterparty-risk-watch`) Actor

Watch UK suppliers and customers for changed filings and Gazette notices. Get evidence links and explained OK, WATCH or ACTION flags. Bring a free Companies House key for live runs. Try the synthetic demo free.

- **URL**: https://apify.com/fractionalhqforyou/uk-counterparty-risk-watch.md
- **Developed by:** [Jessy Mariau](https://apify.com/fractionalhqforyou) (community)
- **Categories:** Automation, Integrations
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $10.00 / 1,000 company checks

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#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 Supplier and Customer Risk Watch

Keep a customer or supplier list under review with Companies House and Gazette evidence in one place. See newly overdue filings, status changes, resignations and insolvency notices with reasons and source links.

### A watch list you can review

Selected rows from the built-in **synthetic demo**. Every company below is fictional; this demonstrates the rubric rather than live business conditions.

| Demo company | Register status | Flag | Reason shown |
|---|---|---|---|
| DEMO BAKERY LIMITED | active | OK | No configured risk signal |
| DEMO SOFTWARE STUDIO LTD | active | WATCH | Overdue confirmation statement and new charge |
| DEMO LOGISTICS HOLDINGS PLC | liquidation | ACTION | Status change and Gazette notice |
| DEMO FABRICATION WORKS LIMITED | active | ACTION | Overdue accounts |

In live results, changes carry `type`, `severity`, `detail` and `evidence_url`. OK means none of the configured signals were found; it is not a credit rating.

**Preview free:** leave `apiKey` empty. For your list, add a free Companies House key, company numbers or names, and a `watchKey`.

The first live run saves a baseline and reports current signals. Repeat with the same key for changes. Use a separate key for each list. Scheduled Slack or email delivery requires your own integration.

### What it does

You paste your list, one company per line. Numbers are looked up directly. A name is searched, and the match is only accepted when the top hit is the same name once case, punctuation and LTD versus LIMITED are ignored. Anything else comes back unmatched with the top 3 candidates attached, so you make the call instead of the Actor guessing.

For each company it reads the current state from the official Companies House API and searches The Gazette, the UK's official public record, for corporate insolvency notices. Then it compares all of that against the snapshot it saved last time you ran with the same watch key, and reports the difference.

Eight kinds of change come back, each with a severity, a plain sentence saying what happened, and a link to the page that proves it:

`status_change` when the company moves between active, liquidation, administration, dissolved and the rest. `insolvency_notice` for a new Gazette notice or a new insolvency case on the register. `accounts_overdue` and `confirmation_overdue` the first time a filing deadline is missed. `new_charge` when someone registers security over the company's assets, with the name of who. `officer_resignations` with who left and when. `registered_office_change` and `name_change` for the quieter signals that often arrive first.

Every company also gets a `risk_state` of OK, WATCH or ACTION, and the reasons behind it.

The first run against a new watch key sets the baseline. There is nothing to compare against yet, so no register changes are reported, and `first_run` comes back true. The risk state is still real on that first run, because it is read from the company's current state and its live Gazette notices rather than from the comparison.

### What you need

A Companies House API key. It is free and takes about two minutes: register at https://developer.company-information.service.gov.uk/, create an application, add a REST API key. Paste it into `apiKey` and Apify stores it as a secret. It never reaches the log or the dataset.

The Gazette needs nothing. Its search is open, no account and no key.

Run with no key at all and you get four sample rows in demo mode covering OK, WATCH and both flavours of ACTION. Nothing is charged and nothing leaves the container.

### How to run it

```json
{
  "apiKey": "your-companies-house-key",
  "companies": "09876543\nSC123456\nExample Trading Ltd\nAcme Fabrication",
  "watchKey": "suppliers",
  "checkGazette": true,
  "staleAccountsGraceDays": 0
}
```

Schedule that weekly and keep `watchKey` the same, and every run after the first hands you the week's changes. Run a second list under a different watch key and the two never touch each other.

The `OUTPUT` record in the key-value store carries the summary: how many companies were watched, the count in each risk state, every ACTION company named with its reason, and one line you can drop into Slack.

### Output fields

| Field | What it holds |
|---|---|
| `input` | The line you gave. |
| `matched` | True when a company was found. |
| `first_run` | True when this watch key had no snapshot for this company yet. |
| `company_number`, `company_name`, `status` | As registered. |
| `risk_state` | OK, WATCH or ACTION. |
| `risk_reasons` | Why, in plain sentences. |
| `changes` | Every change found. Each carries `type`, `severity`, `detail` and `evidence_url`. |
| `top_change` | The first change, for a summary column. |
| `accounts_next_due`, `accounts_overdue_days` | The accounts deadline and how far past it the company is. |
| `confirmation_next_due` | The confirmation statement deadline. |
| `has_charges`, `has_insolvency_history` | Booleans from the profile. |
| `gazette_notices` | Date, notice type and link for each insolvency notice found. |
| `gazette_checked`, `gazette_reason` | False plus a reason when the Gazette could not be reached or was switched off. |
| `companies_house_url` | The company's public page. |
| `previous_checked_at` | When this company was last seen, or null on a first run. |
| `checked_at` | When this run happened. |
| `candidates` | For an unmatched name, up to 3 possible companies. |
| `error` | Why a row could not be read, or null. |

### The risk rubric

ACTION is kept for the things that genuinely change how you trade with someone. Everything softer is WATCH.

| State | What puts a company there |
|---|---|
| ACTION | An insolvency notice in The Gazette from the last 12 months. An insolvency case on the register. A status of liquidation, administration, receivership, dissolved or similar. Accounts past the filing deadline by more than your grace days. |
| WATCH | Confirmation statement overdue. A new charge registered. Officers resigning. A name or registered office change. An insolvency history on the record with nothing currently open. Accounts late but still inside the grace period. |
| OK | None of the above. |

`staleAccountsGraceDays` moves the line between late accounts being WATCH and being ACTION. Leave it at 0 and the deadline itself is the line.

### Pricing

One `company-watched` event per company actually checked. A name that could not be matched, a number that does not exist and a lookup that failed all cost nothing. Officers, charges, insolvency and the Gazette search are extra requests behind the scenes and none of them add a charge.

100 checked companies cost $1 each run, or $4 for four weekly runs. Unchanged companies and first-run baselines are checked and charged.

These examples describe Actor event charges. Any additional platform or proxy charges shown by Apify are separate. Review run costs before scheduling repeated checks.

### Limits

This reports the public record and public notices, nothing further. No credit file sits behind it and no rating agency stands over it. It tells you what has been filed and published. You decide what that means for your terms.

The register lags reality by however long a filing takes. A company can be in trouble for months before anything reaches Companies House, which is exactly why the Gazette half is here: notices are published when they happen.

Gazette coverage, stated honestly. The search runs on the company number under the corporate insolvency notice codes, which narrows matching to a company identifier. Check the notice link before acting on a flag. Searching by name instead is a full text search and will happily return notices about other companies that merely mention a street with your supplier's name in it, so I do not do that. The trade-off is that notices too old to carry a company number in their text are not found this way, and I saw that happen on a Northern Irish company whose 1999 liquidation notices are titled by notice type and carry no number. The register's own insolvency record covers those cases, and it did: the company still came back ACTION. The window is a rolling 12 months, so a live petition keeps holding the risk state week after week, but it is only reported as a change the first time you see it.

Requests to Companies House are paced at roughly 1.8 per second against its documented 600 per five minutes, and Gazette requests at one every two seconds against its published fair use policy of five per ten seconds. A long list takes a while, and that is deliberate.

Nothing beyond the public register is collected. No credit files, no private data, no scraping where an API exists.

### Pair it with a workflow

If you run n8n, my free templates on https://n8n.io/creators/fractional-hq take a list like this Actor's output and turn it into alerts, credit-hold flags and a weekly digest without another tool in the chain.

The build itself, including what I chose not to do, is written up at https://fractionalhq.uk/use-cases/counterparty-risk-watch

Building a lead list rather than watching one? My sibling Actor does the enrichment half: https://apify.com/fractionalhqforyou/uk-companies-house-enrichment

### Use it from an AI agent

The watch is also available as an MCP server for AI agents. Its endpoint is `https://fractionalhqforyou--uk-counterparty-risk-watch.apify.actor/mcp` and the one tool on it is `watch_uk_counterparties`, which takes your counterparty list and returns the flagged filings in the same call. Pricing does not change: the same per-event charge applies to an agent run. A client without a raw endpoint option can load `apify/actors-mcp-server` and pass `fractionalhqforyou/uk-counterparty-risk-watch` as the Actor to expose.

### Related Actors I publish

Risk on a counterparty list rarely stops at Companies House, so I publish these Actors to cover the rest of the picture.

- [UK Companies House Enrichment](https://apify.com/fractionalhqforyou/uk-companies-house-enrichment): adds the filing record behind a UK company name so you know who you are dealing with.
- [Vendor Policy and Subprocessor Change Watch](https://apify.com/fractionalhqforyou/vendor-policy-change-watch): tells you when a vendor quietly changes its terms or its subprocessor list.
- [First-Time Hire Signals](https://apify.com/fractionalhqforyou/first-time-hire-signals): spots companies advertising their first marketer or first IT hire.

### Help and maintenance

Built and maintained by [Jessy at Fractional HQ](https://fractionalhq.uk). For a bug, open this Actor's Issues tab with the run ID and expected result. Remove keys and private data before sharing an input.

Need the results connected to your process? [Describe the workflow](https://fractionalhq.uk/brief).

# Actor input Schema

## `companies` (type: `string`):

One per line. A company number (for example 09876543 or SC123456) is looked up directly. A name is searched and only accepted when the top hit is the same name; otherwise the row comes back unmatched with the top 3 candidates and costs nothing.

## `apiKey` (type: `string`):

Free. Register at https://developer.company-information.service.gov.uk/ and create a REST API key. Apify stores it as a secret. Without it the Actor runs in demo mode: 4 sample rows, nothing charged.

## `watchKey` (type: `string`):

Names the saved snapshot this run compares against. Use the same key every week for the same list and you get the changes since last time. Use a different key and you start a fresh baseline.

## `checkGazette` (type: `boolean`):

Searches the official public record at thegazette.co.uk for insolvency notices naming each company. Adds one request per company. Switch off to run on the Companies House register alone.

## `staleAccountsGraceDays` (type: `integer`):

How many days past the filing deadline before overdue accounts count as ACTION rather than WATCH. 0 means the deadline itself is the line.

## `maxCompanies` (type: `integer`):

Cap on how many lines are processed. Each company actually checked is one charged event.

## Actor input object example

```json
{
  "watchKey": "default",
  "checkGazette": true,
  "staleAccountsGraceDays": 0,
  "maxCompanies": 200
}
```

# Actor output Schema

## `companies` (type: `string`):

One row per company: risk\_state, the reasons behind it, every change found since the last snapshot, filing dates, charges, insolvency history and any Gazette notices.

## `summary` (type: `string`):

The OUTPUT record: how many companies were watched, the count in each risk state, every ACTION company named with its reason, and one plain line.

# 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 = {
    "companies": ""
};

// Run the Actor and wait for it to finish
const run = await client.actor("fractionalhqforyou/uk-counterparty-risk-watch").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 = { "companies": "" }

# Run the Actor and wait for it to finish
run = client.actor("fractionalhqforyou/uk-counterparty-risk-watch").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 '{
  "companies": ""
}' |
apify call fractionalhqforyou/uk-counterparty-risk-watch --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,fractionalhqforyou/uk-counterparty-risk-watch"
        }
    }
}

```

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/dftBB3FFtHTMFaIXp/builds/8VQU0giPTtueF3gaO/openapi.json