# GovData Labs — UK Companies House Enrichment (`govdatalabs/govdata-labs-companies-house-enrichment`) Actor

GovData Labs enriches UK companies and lists new incorporations from the official Companies House API.

- **URL**: https://apify.com/govdatalabs/govdata-labs-companies-house-enrichment.md
- **Developed by:** [GovData Labs](https://apify.com/govdatalabs) (community)
- **Categories:** Business, Lead generation, Automation
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

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

## GovData Labs — UK Companies House Enrichment

Two jobs on the official Companies House REST API:

- **Enrich** a list of company numbers or names. Each output row carries the profile, registered address, SIC codes, status, incorporation date, accounts and confirmation-statement due dates, officers, persons with significant control, and a charges summary. Turn any of those sections off.
- **New incorporations** for a date range, optional SIC codes, and an optional location, using the advanced search endpoint. The streaming API is available when you already have a timepoint and want to follow the firehose forward.

For developers, lenders, sales teams, and compliance tools that need a flat UK company record without paging the Companies House website.

You supply the API key. This Actor does not create one.

### What you get

One record per company:

- `company_number`, `company_name`, `normalized_name`, `match_confidence`, `match_method`
- `company_status`, `company_type`, `incorporation_date`, `jurisdiction`, `sic_codes`
- `registered_address`
- `accounts_next_due`, `accounts_overdue`
- `confirmation_statement_next_due`, `confirmation_statement_overdue`
- `has_charges`, `has_insolvency_history`
- `officer_count`, `active_officer_count`, `officers`
- `psc_count`, `persons_with_significant_control`
- `charges_total`, `charges_outstanding`, `charges_satisfied`, `charges`
- `source_url` on the public company page, and `fetched_at`

Officers, PSCs, and charges are arrays on that same record. The Output tab has an officers view that unwinds them. Sections you turn off are `null` and are not requested, which saves quota.

Name search picks the best fuzzy match and returns up to three companies when the scores are within 0.03 of each other. Active companies get a small score boost. Anything under the threshold (default 0.84) is listed in the run summary as unmatched and is not billed as a result.

### Pricing

Pay per event. You pay only for what a run returns:

| Event | Price | When |
| --- | ---: | --- |
| `actor-start` | $0.010 | Once per valid run |
| `company-result` | $0.020 | Each output row, whether it came from enrichment or the incorporations feed |
| `change-detected` | $0.005 | Each new or changed row after a baseline snapshot |

The default enrichment cap is 25 companies, about $0.51. One thousand full enrichments are about 5,000 API calls. The client stays at 500 requests per 5 minutes so a shared key still has room under the official 600 / 5 minutes limit. That run is about 50 minutes at 512 MB, roughly 0.42 compute units of platform usage, billed separately by Apify.

A thousand incorporation rows from advanced search are usually 10 to 20 requests. Same event price, much less compute.

### Example input

Enrichment:

```json
{
  "mode": "enrich",
  "companyNumbers": ["00445790"],
  "companyNames": ["Northwind Analytics"],
  "apiKey": "YOUR_KEY",
  "includeOfficers": true,
  "includePersonsWithSignificantControl": true,
  "includeCharges": true,
  "maxResults": 25
}
```

Incorporations:

```json
{
  "mode": "incorporations",
  "apiKey": "YOUR_KEY",
  "incorporatedFrom": "2026-10-01",
  "incorporatedTo": "2026-10-31",
  "sicCodes": ["62012"],
  "location": "London",
  "enrichIncorporations": false,
  "maxResults": 100
}
```

Stream follow-up (not a historical backfill):

```json
{
  "mode": "incorporations",
  "incorporationSource": "stream",
  "streamTimepoint": 424242,
  "apiKey": "YOUR_KEY",
  "maxResults": 50
}
```

The run output includes `nextTimepoint` for the next poll.

### Example output

Shape produced from the public API. This fixture is synthetic except for the field names, which match the live API.

```json
{
  "company_number": "12345678",
  "company_name": "NORTHWIND ANALYTICS LTD",
  "company_status": "active",
  "company_type": "ltd",
  "incorporation_date": "2024-03-01",
  "sic_codes": ["62012"],
  "registered_address": "1 High Street, London, SW1A 1AA",
  "accounts_next_due": "2026-12-31",
  "accounts_overdue": false,
  "confirmation_statement_next_due": "2026-03-15",
  "officer_count": 1,
  "charges_outstanding": 1,
  "officers": [
    { "name": "SMITH, Jane", "role": "director", "appointed_on": "2024-03-01", "resigned_on": null }
  ],
  "source_url": "https://find-and-update.company-information.service.gov.uk/company/12345678",
  "fetched_at": "2026-10-31T00:00:00.000Z"
}
```

### Limits

- Official quota: 600 requests per 5 minutes per API key. This Actor defaults to 500.
- 2,000 output rows per run. Related lists are capped at 50 items each (configurable up to 100).
- Advanced search is the way to backfill a date range. The stream starts at `streamTimepoint` and stops after `maxStreamEvents` (default 2,000) so it cannot replay the whole register.
- HTTP 429 and 5xx are retried with backoff. HTTP 401 means the key was rejected.

### API key

Create a free key at [Companies House developer applications](https://developer.company-information.service.gov.uk/manage-applications) and paste it into the `apiKey` input. It is stored as a secret input and is not logged.

### Data source and licence

Companies House REST API, `https://api.company-information.service.gov.uk`, and the streaming host `https://stream.companieshouse.gov.uk`.

Contains public sector information licensed under the [Open Government Licence v3.0](https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/). © Crown copyright.

### Disclaimer

Data comes from official public sources and may lag the registrar. It is not a legal determination of company status, filing obligations, or who controls the company. Confirm anything material on the Companies House register.

# Changelog

This Actor's version history is a separate document: https://apify.com/govdatalabs/govdata-labs-companies-house-enrichment/changelog.md

# Actor input Schema

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

enrich looks up companies you list. incorporations lists companies incorporated in a date range.

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

Companies House numbers. Digits are padded to 8 characters. Scottish and other prefixed numbers such as SC123456 are kept.

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

Names to search. The best fuzzy match above the threshold is enriched. Up to three close matches are returned when scores are nearly tied.

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

Your REST API key from https://developer.company-information.service.gov.uk/manage-applications. You can also set COMPANIES_HOUSE_API_KEY. The key is not logged.

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

Start date YYYY-MM-DD for the incorporations feed. Defaults to 7 days before today.

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

End date YYYY-MM-DD, inclusive. Defaults to today.

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

Optional 4 or 5 digit SIC codes for the incorporations feed.

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

Optional location string passed to Companies House advanced search, for example London or Manchester.

## `incorporationSource` (type: `string`):

advanced-search backfills a date range. stream follows the Companies House streaming API from streamTimepoint and is meant for forward polling, not history.

## `streamTimepoint` (type: `integer`):

Required for stream mode. Use the nextTimepoint from the previous run's output.

## `enrichIncorporations` (type: `boolean`):

Off by default. When on, each new company also loads officers, PSCs, and charges. That uses more of the 600 requests / 5 minutes quota.

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

Load the officers list during enrichment.

## `includePersonsWithSignificantControl` (type: `boolean`):

Load the PSC list during enrichment.

## `includeCharges` (type: `boolean`):

Load the charges summary during enrichment.

## `nameMatchThreshold` (type: `number`):

Minimum fuzzy score for a name search. Active companies get a small boost.

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

Cap on output rows. Enrichment defaults to 25 because each company can take several API calls. Each row is billed as company-result.

## `maxSectionItems` (type: `integer`):

Cap on related records stored on each company.

## `maxRequestsPerFiveMinutes` (type: `integer`):

Companies House allows 600 requests per 5 minutes per key. The default of 500 leaves headroom if the key is shared.

## `maxStreamEvents` (type: `integer`):

Stop reading the stream after this many events even if fewer companies matched.

## `onlyChangesSinceLastRun` (type: `boolean`):

The first run stores a baseline and bills company-result only. Later runs emit new or changed profiles and also bill change-detected.

## `snapshotStoreName` (type: `string`):

Named key-value store for the company snapshot and the stream timepoint.

## Actor input object example

```json
{
  "mode": "enrich",
  "companyNumbers": [
    "00445790"
  ],
  "sicCodes": [
    "62012"
  ],
  "incorporationSource": "advanced-search",
  "enrichIncorporations": false,
  "includeOfficers": true,
  "includePersonsWithSignificantControl": true,
  "includeCharges": true,
  "nameMatchThreshold": 0.84,
  "maxResults": 25,
  "maxSectionItems": 50,
  "maxRequestsPerFiveMinutes": 500,
  "maxStreamEvents": 2000,
  "onlyChangesSinceLastRun": false,
  "snapshotStoreName": "companies-house-snapshots"
}
```

# Actor output Schema

## `results` (type: `string`):

Company rows written to the default dataset.

## `resultCount` (type: `string`):

No description

## `unmatchedCount` (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 = {
    "companyNumbers": [
        "00445790"
    ],
    "sicCodes": [
        "62012"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("govdatalabs/govdata-labs-companies-house-enrichment").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"],
    "sicCodes": ["62012"],
}

# Run the Actor and wait for it to finish
run = client.actor("govdatalabs/govdata-labs-companies-house-enrichment").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"
  ],
  "sicCodes": [
    "62012"
  ]
}' |
apify call govdatalabs/govdata-labs-companies-house-enrichment --silent --output-dataset

```

## MCP server setup

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

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/7IOcIQ1T7nMeNZBRj/builds/qfBhlj0uhKolAl0vd/openapi.json