# UK Companies House Scraper (`hexadatalabs/uk-companies-house-scraper`) Actor

Use this when you need UK companies from the official Companies House register: new incorporations, companies by name, SIC code, location, status or type, with registered address, SIC codes, accounts dates and officers (directors). Uses your free Companies House API key. Pay per result.

- **URL**: https://apify.com/hexadatalabs/uk-companies-house-scraper.md
- **Developed by:** [Hexadata](https://apify.com/hexadatalabs) (community)
- **Categories:** Lead generation, Other
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 company (result)s

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 Companies House Scraper

**UK Companies House Scraper** returns companies from the official UK register (Companies House) as clean JSON: new incorporations, companies by name, SIC code, location, status, type or incorporation date, with registered office address, SIC codes and, optionally, the company profile (accounts and confirmation-statement due dates, charges, previous names) and the officers (directors). It uses the official Companies House API with your own free API key, splits large searches automatically, runs incrementally for daily "new companies" alerts, and you **pay per result**.

### What you get

One item per company, same field names as every Hexadata Actor:

| Field | Type | Description |
| --- | --- | --- |
| `id` / `companyNumber` | string | Company number (8 characters), unique |
| `name` | string | Registered name |
| `status` | string | `active`, `dissolved`, `liquidation`, `administration`… |
| `type` / `typeLabel` | string | `ltd` / "Private limited company", `plc`, `llp`… |
| `subtype` | string | null | `community-interest-company`, `private-fund-limited-partnership` |
| `incorporatedAt` / `dissolvedAt` | string | null | `YYYY-MM-DD` |
| `address` | string | null | Registered office in one line |
| `addressLine1` / `addressLine2` / `locality` / `region` / `postalCode` / `addressCountry` | string | null | Registered office parts |
| `country` | string | `GB` |
| `sicCodes` | string\[] | UK SIC 2007 codes |
| `url` | string | Company page on find-and-update.company-information.service.gov.uk |
| `source`, `scrapedAt` | string | Attribution and extraction timestamp |

With `includeDetails: true` (one extra request per company): `jurisdiction`, `previousNames[]`, `hasCharges`, `hasInsolvencyHistory`, `hasBeenLiquidated`, `isCommunityInterestCompany`, `accountsNextDue`, `accountsLastMadeUpTo`, `accountsType`, `confirmationStatementNextDue`, `confirmationStatementLastMadeUpTo`, `registeredOfficeInDispute`, `statusDetail`.

With `includeOfficers: true` (one extra request per company): `officers[]` with `name`, `role`, `isCorporate`, `appointedOn`, `resignedOn`, `nationality`, `countryOfResidence`, `occupation`, `appointmentsUrl`, plus `activeOfficersCount` and `resignedOfficersCount`. Birth dates and correspondence addresses are never copied.

### Use cases

- **B2B sales and lead-generation teams** (accountants, banks, insurers, SaaS, office services) get every company incorporated yesterday in their SIC codes or region, with the director's name, before anyone else contacts them.
- **Fintech, KYC and credit teams** verify company number, status, type, incorporation date, accounts due dates and insolvency flags in bulk against the official register.
- **Market and competitive analysts** count and list all active companies in a SIC code or town, or all companies dissolved in a period.
- **Recruiters and investors** track newly formed companies in a sector (`sicCodes` + `incorporatedFrom`) and the people behind them.
- **AI agents and RAG pipelines** call the Actor as an MCP tool ("which software companies were incorporated in Manchester this week?") and get structured answers from the official source.

### Input

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `apiKey` | secret string | required | Your free Companies House REST API key (see below). |
| `searchQueries` | string\[] | `[]` (prefill `["software"]`) | Words the company name must contain; one search per line. |
| `companyNameExcludes` | string | – | Words the name must not contain. |
| `sicCodes` | string\[] | `[]` | UK SIC 2007 codes (`62012`, `41100`, `56101`…). |
| `location` | string | – (prefill `London`) | Registered-office town, county or postcode area. |
| `companyStatus` | select | `active` | `active`, `any`, `dissolved`, `liquidation`, `administration`… |
| `companyTypes` | string\[] | `[]` | `ltd`, `plc`, `llp`, `limited-partnership`, `private-limited-guarant-nsc`… |
| `incorporatedFrom` / `incorporatedTo` | date | – | Incorporation-date bounds. With no other filter, the last 7 days are used. |
| `onlyNewSinceLastRun` | boolean | `false` | For schedules: only companies incorporated since the previous run that were not delivered before (named store `hexadata-uk-companies-house`). |
| `maxResults` | integer | `100` | Hard cap on results and cost. |
| `includeDetails` | boolean | `false` | Company profile, one extra request per company. |
| `includeOfficers` | boolean | `false` | Officers, one extra request per company. |
| `includeRaw` | boolean | `false` | Attach the original search hit. |
| `proxyConfiguration` | object | off | Not needed. |

**Getting your free API key** (2 minutes): sign in or register at [developer.company-information.service.gov.uk](https://developer.company-information.service.gov.uk/get-started) (GOV.UK One Login), open *Manage applications → Create an application* (environment **Live**), then *Create new key* of type **REST** with no IP restriction, and paste the key into `apiKey`. Each key allows 600 requests per 5 minutes; the Actor paces itself under that limit and waits when the API answers 429.

**How large searches work:** the Companies House advanced search pages up to 10,000 results per query. When a search has more matches, the Actor splits its incorporation-date range in halves until each part fits, so "every active company with SIC 62020" is just a matter of `maxResults` and time (about 2 requests per second).

Invalid input (missing key, bad SIC code, malformed date) stops the run before the first request, so it costs nothing.

### Output example

Two real items from the runs saved in `tests/` (2026-10-27). A new incorporation with `includeDetails` and `includeOfficers` (`sicCodes: ["62012"]`, `incorporatedFrom: "2026-10-20"`):

```json
{
  "id": "17530171",
  "companyNumber": "17530171",
  "name": "SAAD INNOVATION LAB LTD",
  "status": "active",
  "type": "ltd",
  "typeLabel": "Private limited company",
  "subtype": null,
  "incorporatedAt": "2026-10-20",
  "dissolvedAt": null,
  "address": "6a Durham Road, Gloucester, Gloucestershire, GL4 3AS, United Kingdom",
  "addressLine1": "6a Durham Road",
  "addressLine2": null,
  "locality": "Gloucester",
  "region": "Gloucestershire",
  "postalCode": "GL4 3AS",
  "addressCountry": "United Kingdom",
  "country": "GB",
  "sicCodes": ["62011", "62012"],
  "url": "https://find-and-update.company-information.service.gov.uk/company/17530171",
  "jurisdiction": "england-wales",
  "previousNames": [],
  "hasCharges": false,
  "hasInsolvencyHistory": false,
  "accountsNextDue": "2028-07-20",
  "confirmationStatementNextDue": "2027-11-02",
  "registeredOfficeInDispute": false,
  "officers": [
    {
      "name": "AHMAD, Mukhtar",
      "role": "director",
      "isCorporate": false,
      "appointedOn": "2026-10-20",
      "resignedOn": null,
      "nationality": "Pakistani",
      "countryOfResidence": "Pakistan",
      "occupation": null,
      "appointmentsUrl": "https://find-and-update.company-information.service.gov.uk/officers/YihfmtlLeUSmKPFVR_qdQDt-llI/appointments"
    }
  ],
  "activeOfficersCount": 1,
  "resignedOfficersCount": 0,
  "source": "Companies House (UK), public register via the Companies House API",
  "scrapedAt": "2026-10-27T22:55:04.032Z"
}
```

A plain search hit (`searchQueries: ["software"]`, `location: "London"`):

```json
{
  "id": "07438022",
  "companyNumber": "07438022",
  "name": "RICHWIND SOFTWARE DEVELOPMENT LIMITED",
  "status": "active",
  "type": "ltd",
  "typeLabel": "Private limited company",
  "incorporatedAt": "2010-11-12",
  "address": "91 Tennyson Road, Stratford, London, E15 4DJ",
  "locality": "London",
  "postalCode": "E15 4DJ",
  "country": "GB",
  "sicCodes": ["62020"],
  "url": "https://find-and-update.company-information.service.gov.uk/company/07438022",
  "source": "Companies House (UK), public register via the Companies House API",
  "scrapedAt": "2026-10-27T22:54:45.686Z"
}
```

### Pricing & cost examples

**$2.00 per 1,000 companies** plus **$1.00 per 1,000 detail requests** (one request per company for `includeDetails`, one for `includeOfficers`). Pay per event: only companies saved to the dataset and detail requests actually made are charged; duplicates and failed runs are never billed. `maxResults` is a hard cost cap and Apify platform usage is included.

- A first look: `maxResults: 50` ≈ **$0.10**.
- A daily "new companies" alert for two SIC codes with officers (about 100 companies a day) ≈ **$0.30 per day**, about $9 per month.
- Every active company in SIC 62020 in London (about 20,000) with profile ≈ **$60**.

### Use with AI agents (MCP)

Every Apify Actor is available as a tool through the [Apify MCP server](https://mcp.apify.com). Add this server to Claude, Cursor, VS Code or any MCP client (OAuth sign-in on first use, or an `Authorization: Bearer <APIFY_TOKEN>` header):

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=hexadatalabs/uk-companies-house-scraper"
    }
  }
}
```

Then ask, for example:

> "List the software companies incorporated in Manchester in the last 7 days with their directors."

The agent calls the Actor with `{"apiKey":"<your key>","sicCodes":["62012","62020"],"location":"Manchester","incorporatedFrom":"2026-10-20","includeOfficers":true}` and reads `name`, `incorporatedAt` and `officers`. The Actor description and every input field start with "Use this when…" so tool selection works without extra prompting.

#### Pay with USDC (x402, no account needed)

AI agents can pay for this Actor directly with USDC through Apify's x402 support, with no Apify account: the agent buys a prepaid token from Apify AGI with a [Coinbase Agentic Wallet](https://docs.cdp.coinbase.com/agentic-wallet/cli/welcome) (USDC on Base, minimum $1) and uses that token as a normal API token. This Actor runs with **limited permissions**, which is what makes it eligible. Current steps are in [Apify's x402 guide](https://docs.apify.com/integrations/x402):

```bash
npx -y awal auth login <email> && npx awal auth verify <code>   # one-time wallet setup; then fund it with USDC and a little ETH on Base
TOKEN=$(npx awal x402 pay 'https://agi.apify.com/protocols/x402/prepaid-tokens?amount=1&currency=usd' --max-amount 1000000 --json | jq -r .token)
curl -s -X POST "https://api.apify.com/v2/acts/hexadatalabs~uk-companies-house-scraper/run-sync-get-dataset-items" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"apiKey":"<COMPANIES_HOUSE_KEY>","searchQueries":["software"],"location":"London","maxResults":50}'
```

Cost: **$1 USDC ≈ 500 companies** at this Actor's price (detail requests cost $1.00 per 1,000 on top); the token balance is a hard spending cap, and the token expires 14 days after purchase.

### API & integrations

```bash
curl -X POST "https://api.apify.com/v2/acts/hexadatalabs~uk-companies-house-scraper/run-sync-get-dataset-items?token=<APIFY_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"apiKey":"<COMPANIES_HOUSE_KEY>","searchQueries":["software"],"location":"London","maxResults":50}'
```

```python
from apify_client import ApifyClient
client = ApifyClient("<APIFY_TOKEN>")
run = client.actor("hexadatalabs/uk-companies-house-scraper").call(run_input={
    "apiKey": "<COMPANIES_HOUSE_KEY>", "sicCodes": ["62012"], "incorporatedFrom": "2026-10-20",
    "includeDetails": True, "includeOfficers": True, "maxResults": 500,
})
for c in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(c["companyNumber"], c["name"], c["incorporatedAt"], [o["name"] for o in c.get("officers", [])])
```

```javascript
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: '<APIFY_TOKEN>' });
const run = await client.actor('hexadatalabs/uk-companies-house-scraper').call({
    apiKey: '<COMPANIES_HOUSE_KEY>', sicCodes: ['62020'], location: 'Manchester', onlyNewSinceLastRun: true, maxResults: 1000,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items.map((c) => `${c.incorporatedAt} · ${c.name} · ${c.postalCode}`).join('\n'));
```

**Schedules and webhooks:** create a daily Schedule in Apify Console with `onlyNewSinceLastRun: true` to receive each day's new incorporations, then add a webhook or integration (e-mail, Slack, Google Sheets, HubSpot, Make, Zapier) on the `ACTOR.RUN.SUCCEEDED` event.

### Limitations & legal

- **Source:** the official Companies House Public Data API (`api.company-information.service.gov.uk`), called with your own key; no HTML is scraped. Register information is Crown copyright, made available by Companies House for reuse under section 47 of the Copyright, Designs and Patents Act 1988; keep the attribution in `source`. Hexadata is not affiliated with Companies House.
- **Personal data:** officers are named individuals and are returned only with `includeOfficers: true`; their birth dates and correspondence addresses are never extracted. Use officer data only in line with UK GDPR and your lawful basis.
- **Rate limit:** 600 requests per 5 minutes per key (about 2 per second). A run with `includeDetails` and `includeOfficers` makes three requests per company, so 1,000 companies take about 25 minutes; the Actor waits automatically when the API answers 429.
- **Search semantics:** `searchQueries` and `location` use the Companies House advanced search (word match on the name, free-text match on the registered office). `location` is not a radius.
- **Result window:** 10,000 results per search; larger searches are split by incorporation date automatically, which needs the incorporation-date filter to be meaningful (dissolved-date splitting is not implemented).
- If Companies House changes its response format and three consecutive pages lack the mandatory fields, the run fails with `SITE_LAYOUT_CHANGED` and nothing is charged.

### Changelog

- **0.1.0** (2026-10-27): first release. Name, SIC, location, status, type and incorporation-date filters; automatic date splitting; optional profile and officers; incremental mode; dataset table view; MCP-ready descriptions.

### Support

Open an issue in the **Issues** tab of this Actor (or e-mail Hexadata through the Apify profile). Issues are answered within 24 hours and confirmed bugs are fixed in a `beta` build within 48 hours.

#### En español

**UK Companies House Scraper** extrae empresas del registro mercantil oficial del Reino Unido (Companies House) mediante su API y tu clave gratuita: empresas nuevas, búsqueda por nombre, código SIC, localidad, estado, tipo y fecha de constitución, con domicilio registrado y, opcionalmente, perfil (cuentas, cargas, nombres anteriores) y directores. Divide búsquedas grandes automáticamente y tiene modo incremental para alertas diarias de empresas recién constituidas. Precio: **$2.00 por cada 1,000 empresas** más **$1.00 por cada 1,000 consultas de detalle**; `maxResults` limita el costo. Datos de personas (directores) solo si se piden.

# Actor input Schema

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

Your free REST API key from https://developer.company-information.service.gov.uk/get-started (Developer Hub → your application → Keys → REST API key, Live environment, no IP restriction). Required.

## `searchQueries` (type: `array`):

Words the company name must contain, one search per line, e.g. "software", "solar", "dental". Leave empty to filter only by SIC code, location or dates.

## `companyNameExcludes` (type: `string`):

Words the company name must not contain, e.g. "holdings".

## `sicCodes` (type: `array`):

UK SIC 2007 codes (5 digits), e.g. 62012 = business and domestic software development, 62020 = IT consultancy, 41100 = development of building projects, 56101 = licensed restaurants. List: https://resources.companieshouse.gov.uk/sic/

## `location` (type: `string`):

Registered-office location as free text: a town, county or postcode area, e.g. "London", "Manchester", "Cardiff", "SW1".

## `companyStatus` (type: `string`):

Use "active" for companies currently trading, "dissolved" for closed ones, or "any".

## `companyTypes` (type: `array`):

Companies House type codes, e.g. ltd (private limited), plc, llp, limited-partnership, private-limited-guarant-nsc (limited by guarantee), charitable-incorporated-organisation, registered-overseas-entity. Empty = all types.

## `incorporatedFrom` (type: `string`):

Only companies incorporated on or after this date (YYYY-MM-DD), e.g. 2026-10-01 for new companies. With no other filter, the last 7 days are used.

## `incorporatedTo` (type: `string`):

Only companies incorporated on or before this date (YYYY-MM-DD).

## `onlyNewSinceLastRun` (type: `boolean`):

Use this on a schedule: the Actor remembers when it last ran (shared store "hexadata-uk-companies-house" in your account) and returns only companies incorporated since then that it has not delivered before. The first run saves everything that matches.

## `maxResults` (type: `integer`):

Stop after this many companies. Searches with more than 10,000 matches are split by incorporation date automatically.

## `includeDetails` (type: `boolean`):

One extra API request per company: accounts and confirmation-statement due dates, previous names, charges and insolvency flags, jurisdiction. Charged as a detail request.

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

One extra API request per company: current and resigned officers with name, role, appointment dates, nationality, country of residence and occupation (never birth dates or home addresses). Officers are named individuals; turn on only if you have a lawful basis to use them. Charged as a detail request.

## `includeRaw` (type: `boolean`):

Attach the original search hit under "raw".

## `proxyConfiguration` (type: `object`):

Not needed for the Companies House API; leave it off (your API key may be restricted to fixed IPs).

## Actor input object example

```json
{
  "searchQueries": [
    "software"
  ],
  "location": "London",
  "companyStatus": "active",
  "onlyNewSinceLastRun": false,
  "maxResults": 50,
  "includeDetails": false,
  "includeOfficers": false,
  "includeRaw": false,
  "proxyConfiguration": {
    "useApifyProxy": 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 = {
    "searchQueries": [
        "software"
    ],
    "location": "London",
    "maxResults": 50,
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("hexadatalabs/uk-companies-house-scraper").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 = {
    "searchQueries": ["software"],
    "location": "London",
    "maxResults": 50,
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("hexadatalabs/uk-companies-house-scraper").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 '{
  "searchQueries": [
    "software"
  ],
  "location": "London",
  "maxResults": 50,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call hexadatalabs/uk-companies-house-scraper --silent --output-dataset

```

## MCP server setup

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

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/uyMIhKQF2Z0mKtGbR/builds/dam1ZLGphpK9NrJA4/openapi.json