# UK Companies House Scraper & Lookup (official API) (`gastings/companies-house-lookup`) Actor

Look up UK companies by number or name via the official Companies House API. Returns company details with accounts and confirmation-statement dates, charges and insolvency summaries, plus optional filing history and officers/PSC. Results are company-level by default. Pay per company, no start fee.

- **URL**: https://apify.com/gastings/companies-house-lookup.md
- **Developed by:** [Oleh Hastov](https://apify.com/gastings) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 company profile returneds

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

## Companies House Scraper & Lookup (official API)

**Pass in UK company numbers or names and get back complete, current register records: accounts dates, confirmation statement, charges, insolvency, filings, all from the official Companies House API. Company-level by default, pay per company, no minimum run cost.**

Built for KYC/onboarding checks, supplier and customer screening, CRM enrichment, lead qualification and AI agents that need a reliable answer to "who is this UK company and is it in good standing?".

### What you get for each company

| Field group | Included | Details |
|---|---|---|
| Identity | always | number, name, status (+ status detail), type, jurisdiction, incorporated/dissolved dates, SIC codes, previous names |
| Registered address | always | structured fields plus a one-line version; "in dispute" flag |
| Accounts | always | **next due, overdue flag, last made-up-to, last accounts type, reference date** |
| Confirmation statement | always | next due, overdue flag, last made-up-to |
| Charges & insolvency | default on | outstanding / satisfied / part-satisfied counts, charge details (status, dates, persons entitled), insolvency cases and practitioners; fetched only for companies that have them |
| Recent filings | opt-in | last *N* filings with date, category, type and description |
| Officers & PSC | opt-in | counts always; names, roles and dates only when you ask; **never** date of birth or home address |
| Links | always | the public Companies House page and the API URL |

Every input produces exactly one row, with `status` = `ok`, `not_found`, `ambiguous` (name search without a confident match) or `error`. A run never "succeeds" with an empty dataset: if nothing resolved, the run fails with the reason.

### Why this one

- **Official API.** No breakage when the Companies House website changes, and the accounts, charges and insolvency fields are filled in.
- **Names are resolved with care.** Each name is searched, scored (0 to 1) and returned with the top five candidates. Legal forms are understood ("Vodafone Group" finds VODAFONE GROUP PUBLIC LIMITED COMPANY rather than a subsidiary; "BP plc" = BP P.L.C.), an exact legal name wins outright, and when two different companies tie on a name the row is flagged `ambiguous` with both listed. `match.reason` says why.
- **Fair pricing.** You pay per company returned; not-found and ambiguous rows are free; there is no minimum run cost, and the start event is $0.00005 (five thousandths of a cent).
- **Agent-ready.** List inputs, small typed JSON, fast (about 1 s per company by number, 1.5 to 2 s with a name search and filings; 98 companies in 2 m 41 s), works from the Apify MCP server.
- **Personal data off by default.** Officer and PSC lists are opt-in, and even then DOB and home addresses are never returned.

### Input

```json
{
  "companyNumbers": ["00445790", "09446231"],
  "companyNames": ["Octopus Energy"],
  "includeChargesAndInsolvency": true,
  "includeFilings": false,
  "maxFilings": 10,
  "includeOfficers": false,
  "includePsc": false
}
```

- `companyNumbers`: 8-character Companies House numbers; shorter numeric values are zero-padded (445790 → 00445790).
- `companyNames`: free-text names; best match ≥ 0.72 confidence becomes a profile row, otherwise an `ambiguous` row with candidates.
- `apiKey` (optional, stored encrypted): bring your own Companies House key to use your own rate limit.

### Output example (real row, abridged)

```json
{
  "input": { "company_number": "00445790", "company_name": null, "raw": "00445790" },
  "status": "ok",
  "company_number": "00445790",
  "company_name": "TESCO PLC",
  "company_status": "active",
  "company_type": "plc",
  "jurisdiction": "england-wales",
  "incorporated_on": "1947-11-27",
  "sic_codes": ["47110"],
  "previous_names": [
    { "name": "TESCO STORES (HOLDINGS) PUBLIC LIMITED COMPANY", "effective_from": "1981-12-14", "ceased_on": "1983-08-25" }
  ],
  "registered_address_line": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, AL7 1GA, United Kingdom",
  "registered_address_in_dispute": false,
  "accounts": { "next_due": "2027-08-26", "overdue": false, "next_made_up_to": "2027-02-26", "last_made_up_to": "2026-02-28", "last_type": "group", "reference_date": "26/02" },
  "confirmation_statement": { "next_due": "2027-07-02", "overdue": false, "last_made_up_to": "2026-06-18", "next_made_up_to": "2027-06-18" },
  "has_charges": false,
  "charges": { "total": 0, "outstanding": 0, "satisfied": 0, "part_satisfied": 0, "items": [] },
  "has_insolvency_history": false,
  "insolvency": { "cases": [], "status": [] },
  "filings": { "total": 8372, "items": [ { "date": "2026-09-16", "category": "capital", "type": "SH03", "description": "capital-return-purchase-own-shares", "pages": 4 } ] },
  "links": {
    "companies_house": "https://find-and-update.company-information.service.gov.uk/company/00445790",
    "api_profile": "https://api.company-information.service.gov.uk/company/00445790"
  },
  "section_errors": null,
  "fetched_at": "2026-10-27T10:18:00+00:00"
}
```

A name input adds a `match` object with the query, the chosen number and name, a confidence score and the top five candidates (number, name, status, incorporation date, address snippet), so you can audit every resolution.

### Pricing

| Event | Price | When |
|---|---|---|
| Company profile | $0.003 | per company resolved to a live record |
| Charges & insolvency summary | $0.001 | per company, when enabled (default on) |
| Recent filings | $0.001 | per company, when enabled |
| Officers / PSC | $0.002 | per company, when enabled |
| Name search | $0.001 | per name searched |
| Actor start | $0.00005 | per run |

Typical cost: **$0.004 per company** with the defaults, i.e. $4 per 1,000, and nothing for not-found rows. Set a maximum total charge on the run to cap spend; the actor stops cleanly when it is reached.

### Limits and good practice

- Companies House allows 600 requests per 5 minutes per key. With the defaults this actor makes 1 to 3 requests per company, so about 200 to 500 companies every 5 minutes; larger lists simply take longer. Bring your own key for a dedicated limit.
- Data is the public register as published by Companies House and is reused in accordance with its terms; the register contains personal data about officers and PSCs, which this actor returns only on request and in reduced form. You are responsible for your own lawful basis when you process it.
- No headless browser, no proxies, no scraping of the website: runs are cheap and stable.

### Support

Open an issue on this page; issues are answered within 12 hours on working days. Feature requests welcome: a "changes since last run" monitor and bulk exports are on the roadmap.

### Changelog

- 0.1: first release. Profile, accounts, confirmation statement, charges, insolvency, filings, officers/PSC opt-in, name resolution with confidence.

# Actor input Schema

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

Companies House numbers to look up (8 characters; leading zeros added automatically, e.g. 445790 → 00445790). Scottish/NI prefixes such as SC123456 are accepted.

## `companyNames` (type: `array`):

Free-text company names. Each is searched on Companies House and the best match is returned with a confidence score and the top candidates; matches below 0.72 confidence are reported as 'ambiguous' and not charged as a profile.

## `includeChargesAndInsolvency` (type: `boolean`):

Adds outstanding/satisfied charge counts with details and any insolvency cases. Fetched only for companies that have them (no wasted requests). One small event per company.

## `includeFilings` (type: `boolean`):

Adds the most recent filings (date, type, description). One small event per company.

## `maxFilings` (type: `integer`):

How many recent filings to return when includeFilings is on.

## `includeOfficers` (type: `boolean`):

Off by default: officer names are personal data. When on, returns name, role, appointment/resignation dates, occupation, nationality and country of residence, never date of birth or home address. Active/resigned counts are returned regardless.

## `includePsc` (type: `boolean`):

Off by default (personal data). When on, returns PSC names, kinds, natures of control and notification dates.

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

Bring your own key to use your own rate limit (600 requests per 5 minutes). Leave empty to use the actor's key. Stored encrypted.

## Actor input object example

```json
{
  "companyNumbers": [
    "00445790",
    "09446231",
    "09263424"
  ],
  "companyNames": [],
  "includeChargesAndInsolvency": true,
  "includeFilings": false,
  "maxFilings": 10,
  "includeOfficers": false,
  "includePsc": false
}
```

# Actor output Schema

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

All rows of the default dataset as JSON: one object per input with identity, status, accounts and confirmation-statement dates, charges, insolvency, optional filings / officers / PSC, and the name-match audit (query, confidence, candidates).

## `companiesCsv` (type: `string`):

The same rows as CSV, flattened for spreadsheets.

## `runSummary` (type: `string`):

Counters for the run: inputs, rows by status, requests, retries, errors by category, seconds.

# 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 = {
    "companyNumbers": [
        "00445790",
        "09446231",
        "09263424"
    ],
    "companyNames": []
};

// Run the Actor and wait for it to finish
const run = await client.actor("gastings/companies-house-lookup").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 = {
    "companyNumbers": [
        "00445790",
        "09446231",
        "09263424",
    ],
    "companyNames": [],
}

# Run the Actor and wait for it to finish
run = client.actor("gastings/companies-house-lookup").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 '{
  "companyNumbers": [
    "00445790",
    "09446231",
    "09263424"
  ],
  "companyNames": []
}' |
apify call gastings/companies-house-lookup --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,gastings/companies-house-lookup"
        }
    }
}
```

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/yvrTSeeqOqusJOb4F/builds/gGUQgp7e5cJsIFxxe/openapi.json