# UK Companies House Companies, Officers and Filings (`automatic/companies-house-scraper`) Actor

Search UK companies and export profiles, officers and filing metadata from public Companies House pages. No document downloads or PSC data.

- **URL**: https://apify.com/automatic/companies-house-scraper.md
- **Developed by:** [Philip Kirkbride](https://apify.com/automatic) (community)
- **Categories:** Lead generation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 rows

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 Companies, Officers and Filings

Search UK companies by name or keyword and export company profiles, with optional officers and filing-history metadata. Uses anonymous public Companies House pages by default. It does not download documents, retrieve PSCs, or verify the accuracy of information filed with Companies House.

Default input searches `tesco` and saves up to 10 company profiles. No key or account is required. For direct lookups use `mode: "companies"` and `companyNumbers: ["00445790"]`; official overview URLs are also accepted. `status` accepts active, dissolved or all. Search collects up to maxCompanies companies before applying the status filter, so filtered runs may return fewer companies.

Enable includeOfficers or includeFilings for additional rows, bounded separately by maxOfficersPerCompany and maxFilingsPerCompany. Output rowType is company, officer or filing; each row has companyNumber and a canonical source url. Dates use ISO 8601. Fields absent from the source are null. Filing category is null on HTML pages; filingType contains the displayed code. Document links are supplied without downloading the document.

An optional secret apiKey switches all requests to the official Companies House REST API. Obtain a free API key through the Companies House developer hub. API SIC descriptions may be null; filing descriptions are official API description identifiers. The actor never logs the key.

Privacy: no dates of birth (including month/year), no individual officer personal or correspondence addresses, and no individual PSC rows. All PSC rows are omitted. Company registered office addresses are included.

Results save incrementally by company and officer/filing page. Blocked or unavailable targets appear in the final status. Saved rows allow partial success; an all-failed run with no rows fails plainly. Empty search results require two requests. The timeout reserves 20 seconds for shutdown. Search pagination is bounded by maxCompanies; the source may impose additional result limits. No CAPTCHA solving, login or paid API is used.

Run locally: install requirements.txt and run `python -m src`. Offline tests: `python -m unittest discover -s tests` after installing requirements-dev.txt. This is a repo-only actor; no production deployment or price has been configured.

### Output example

```json
{"rowType":"company","companyNumber":"00445790","url":"https://find-and-update.company-information.service.gov.uk/company/00445790","name":"TESCO PLC","status":"Active"}
```

The default memory is 512 MB. If start-event billing is configured at publication, it applies per GB of memory: a default 512 MB run is one start event. This repository build sets no prices.

Occupation is unavailable on the anonymous HTML officer pages checked; it is null on that route. The optional official API returns occupation when supplied.

# Actor input Schema

## `mode` (type: `string`):

Search by name or look up company numbers.

## `query` (type: `string`):

Company name or keyword; used only in search mode.

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

Eight-character company numbers or official company overview URLs; used in companies mode.

## `status` (type: `string`):

Filter company profiles by status. Other statuses are included only with all.

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

Maximum rows of this type to collect, between 1 and 1000.

## `maxOfficersPerCompany` (type: `integer`):

Maximum rows of this type to collect, between 1 and 1000.

## `maxFilingsPerCompany` (type: `integer`):

Maximum rows of this type to collect, between 1 and 1000.

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

Opt in to these extra rows for each matching company.

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

Opt in to these extra rows for each matching company.

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

Optional free official REST API key. When provided, uses the official API instead of HTML pages.

## Actor input object example

```json
{
  "mode": "search",
  "query": "tesco",
  "status": "all",
  "maxCompanies": 10,
  "maxOfficersPerCompany": 10,
  "maxFilingsPerCompany": 10,
  "includeOfficers": false,
  "includeFilings": 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 = {
    "query": "tesco"
};

// Run the Actor and wait for it to finish
const run = await client.actor("automatic/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 = { "query": "tesco" }

# Run the Actor and wait for it to finish
run = client.actor("automatic/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 '{
  "query": "tesco"
}' |
apify call automatic/companies-house-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,automatic/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/3SX9S2Odt3KYIOCTF/builds/QzLOToH4dTDdXPA5c/openapi.json