# UK Subcontractor Health Check (`robert-white/uk-subcontractor-health-check`) Actor

Check a list of UK subcontractors or suppliers in one run. RED / AMBER / GREEN rating with plain-English reasons from Companies House, Gazette insolvency notices and GOV.UK payment practices data.

- **URL**: https://apify.com/robert-white/uk-subcontractor-health-check.md
- **Developed by:** [Robert White](https://apify.com/robert-white) (community)
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $400.00 / 1,000 company checkeds

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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

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

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## UK Subcontractor Health Check

**Check a whole list of UK subcontractors or suppliers in one run. Each one gets a RED / AMBER / GREEN rating and the reasons behind it, taken from official public records.**

Built for quantity surveyors, procurement and supply chain teams, and anyone who keeps a preferred supplier list (PSL) up to date by hand.

- **Catch failing firms early:** liquidation, administration, strike-off notices and Gazette winding-up petitions.
- **Spot warning signs:** overdue accounts, a wave of director resignations, new secured lending, very young companies.
- **See how big firms pay their supply chain:** average days to pay and % of invoices paid late, from GOV.UK payment practices reports.
- **Pay only for companies we find and check.** Names that don't match a company cost nothing.

### Who it's for

- **QS and commercial teams** vetting subcontractors before you let a package
- **Procurement and supply chain managers** refreshing a PSL every quarter
- **Tier 1 and Tier 2 contractors** checking the firms they rely on
- **Suppliers and merchants** checking customers before offering credit
- **AI agents** running supplier due diligence (this Actor accepts agentic payments)

### What you get for each company

| Field | What it means |
| --- | --- |
| `rag` | `RED`, `AMBER`, `GREEN` or `NOT FOUND` |
| `flags` | Plain-English reasons, e.g. *"Accounts overdue at Companies House"* |
| `companyName`, `companyNumber` | The company we matched to what you entered |
| `matchConfidence` | `company-number`, `exact`, `probable` or `uncertain`. Check anything that isn't exact |
| `companyStatus` | `active`, `liquidation`, `administration`, `dissolved`... |
| `accountsLastMadeUpTo`, `accountsType`, `accountsNextDue`, `accountsOverdue` | Accounts filing position |
| `confirmationStatementOverdue` | Confirmation statement filing position |
| `companyAgeYears`, `incorporatedOn` | How long they've been trading |
| `activeDirectors`, `directorResignationsLast12Months` | Board stability (counts only, no personal details) |
| `outstandingCharges`, `newChargesLast12Months` | Secured lending (debentures, mortgages) |
| `gazetteNotices` | Corporate insolvency notices from The Gazette, with links |
| `paymentPractices` | Average days to pay, % paid within 30 days, % paid after 60 days (large companies only) |
| `companiesHouseUrl` | A link to check the record yourself |

#### Example output

```json
{
  "input": "Acme Civils Ltd",
  "companyName": "ACME CIVILS LIMITED",
  "companyNumber": "01234567",
  "matchConfidence": "exact",
  "rag": "AMBER",
  "flags": [
    "Accounts overdue at Companies House",
    "2 director resignations in the last 12 months"
  ],
  "companyStatus": "active",
  "accountsLastMadeUpTo": "2024-03-31",
  "accountsOverdue": true,
  "companyAgeYears": 27.5,
  "activeDirectors": 2,
  "directorResignationsLast12Months": 2,
  "outstandingCharges": 1,
  "gazetteNotices": [],
  "paymentPractices": null,
  "companiesHouseUrl": "https://find-and-update.company-information.service.gov.uk/company/01234567"
}
```

*(Example only. Acme Civils is not a real company.)*

### How the rating works

**RED: do not appoint without investigating**

- Status is liquidation, administration, receivership, voluntary arrangement, insolvency proceedings or dissolved
- Active proposal to strike off
- Any corporate insolvency notice in The Gazette within the look-back period (e.g. a petition to wind up)

**AMBER: ask questions**

- Accounts or confirmation statement overdue
- Previous insolvency history
- Less than 2 years old
- 2 or more director resignations in the last 12 months, or all listed directors have resigned
- 2 or more new secured charges in the last 12 months
- Pays suppliers in more than 60 days on average, or pays more than 20% of invoices after 60 days

**GREEN:** none of the above found.

A GREEN rating means public records show no warning signs. It does **not** guarantee a company's financial health. Use it alongside credit checks, references and your own pre-qualification process.

### How to use it

1. Paste your companies into **Companies to check**, one per line. Companies House numbers give the most reliable match. Registered names work too.
2. Click **Start**.
3. Download the results as Excel, CSV or JSON, or open the **Health check overview** table.

**Tip:** schedule a monthly run of your whole supplier list and send the results to email, Slack or a Google Sheet using Apify integrations. Then you'll know when a supplier's position changes.

### Pricing

You pay a small fee per company found and checked (see the Pricing tab). Companies we can't find cost nothing. Use **Maximum companies per run** to cap your spend.

### Data sources

All data comes from free, official UK public sources under the Open Government Licence v3.0:

- **Companies House** public data API: company profile, officers (counts only) and charges
- **The Gazette**: corporate insolvency notices
- **GOV.UK payment practices reporting**: published supplier payment reports

This Actor isn't affiliated with Companies House, The Gazette, or the Department for Business and Trade.

### Limitations

- Covers companies registered in England & Wales, Scotland and Northern Ireland. Sole traders and partnerships aren't on Companies House.
- Doesn't include credit scores, CCJs, Constructionline or SSIP status. Those aren't free public data.
- Turnover isn't included yet. Small companies often file abbreviated accounts without it.
- Payment practices data exists only for large companies, which are legally required to report.
- Name matching is automatic. Always check rows where `matchConfidence` is `probable` or `uncertain`.

### Feedback

Found a problem or want a feature (HSE enforcement data, turnover from filed accounts, monitoring mode)? Open an issue on the **Issues** tab.

# Actor input Schema

## `companies` (type: `array`):

One per line. Use the registered company name (e.g. 'Kier Construction Limited') or, more reliably, the 8-digit Companies House number.

## `includeGazette` (type: `boolean`):

Looks for winding-up petitions, administration, liquidation and other corporate insolvency notices.

## `gazetteLookbackMonths` (type: `integer`):

How far back to look for Gazette notices.

## `includePaymentPractices` (type: `boolean`):

Large companies must publish how quickly they pay suppliers. Shows average days to pay and % paid late, where the company publishes it.

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

Safety limit so a huge list doesn't run up a big bill by accident.

## `companiesHouseApiKey` (type: `string`):

Not normally needed. Only fill this in if the Actor reports a key problem. Get a free key at developer.company-information.service.gov.uk.

## Actor input object example

```json
{
  "companies": [
    "Kier Construction Limited",
    "Balfour Beatty Group Limited"
  ],
  "includeGazette": true,
  "gazetteLookbackMonths": 24,
  "includePaymentPractices": true,
  "maxCompanies": 500
}
```

# 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 = {
    "companies": [
        "Kier Construction Limited",
        "Balfour Beatty Group Limited"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("robert-white/uk-subcontractor-health-check").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": [
        "Kier Construction Limited",
        "Balfour Beatty Group Limited",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("robert-white/uk-subcontractor-health-check").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": [
    "Kier Construction Limited",
    "Balfour Beatty Group Limited"
  ]
}' |
apify call robert-white/uk-subcontractor-health-check --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,robert-white/uk-subcontractor-health-check"
        }
    }
}
```

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/OC6ZJyRxKMaFB2MCg/builds/HoGFprNcW9f3Azngi/openapi.json