# UK Companies House Leads — Filing Signals & AI Outreach (`automationnation/companies-house-leads`) Actor - **URL**: https://apify.com/automationnation/companies-house-leads.md - **Developed by:** [Nathan Carter](https://apify.com/automationnation) (community) - **Categories:** Lead generation, Automation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing $8.00 / 1,000 company leads 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/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows. 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. Actors are written with capital "A". ## 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. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## UK Companies House Leads — Filing Signals & AI Outreach Turn the UK Companies House public register into a scored, AI-ready B2B lead list. Search by SIC code, location, status, and incorporation date, then get each company scored HOT/WARM/COLD based on real filing activity — funding raised, leadership changes, and how recently it was incorporated — with a personalised email, LinkedIn message, and SMS generated for every lead worth contacting. ### Why this instead of a raw Companies House scraper Most Companies House actors on Apify return the same raw record: name, address, SIC codes, officers. That data is free from the official API — the value is in knowing **which companies to actually contact, and why**. This actor derives real buying-intent signals from a company's filing history: - **FUNDING_SIGNAL** — an SH01 (allotment of shares) was filed recently → fresh capital raised, likely hiring/spending on new tools and services - **LEADERSHIP_GROWTH** — a new director or secretary was appointed recently → the business is expanding its leadership team - **LEADERSHIP_DEPARTURE** — a director or secretary resigned recently → possible restructuring, interim leadership or recruitment need - **NEW_INCORPORATION** — the company was formed recently → needs company formation services, business banking, accountancy, insurance Every lead gets a HOT/WARM/COLD score from these signals, and — if you provide an AI key — a one-sentence explanation of *why* it's a good target plus ready-to-send outreach copy grounded in the real signal (not a generic template). ### What you get per lead - Full company profile: name, number, type, status, incorporation date, SIC codes, registered location - Director name (most senior active officer) - PSC (persons with significant control) count - Filing-signal lead score + the specific signals detected - AI intent summary and likely B2B needs (optional, bring your own Anthropic or Gemini key) - Personalised email, LinkedIn message, and SMS template (optional, same AI step) ### Input | Field | Description | |---|---| | `companiesHouseApiKey` | **Required.** Free — register at [developer.companieshouse.gov.uk](https://developer.companieshouse.gov.uk) | | `sicCodes` | Comma-separated UK SIC codes to filter by, e.g. `62012,70229` | | `location` | Registered office location filter, e.g. `Manchester` | | `companyStatus` | Company status filter — defaults to `active` only | | `incorporatedFrom` / `incorporatedTo` | Date range for incorporation date | | `maxResults` | How many companies to process (free trial capped at 8) | | `signalWindowDays` | How far back to look for funding/leadership/incorporation signals (default 180 days) | | `anthropicApiKey` / `geminiApiKey` | Optional — enables AI intent analysis and outreach generation | | `yourName`, `yourBusiness`, `yourService`, `yourEmail`, `yourPhone` | Optional — personalises the generated outreach | Delivery options: email (SMTP, CSV attachment), webhook (JSON or CSV, bulk or per-record), Slack summary, HubSpot contact push. ### How it works 1. Searches the official Companies House Advanced Search API against your filters 2. For each match, fetches the company profile, officers, filing history, and PSC list 3. Derives signals from the filing history and scores the lead 4. For non-COLD leads with an AI key set, generates an intent summary and 3 outreach messages in a single LLM call 5. Saves one record per company to the dataset, with optional delivery to email/webhook/Slack/HubSpot ### Notes - All data comes from the official UK government Companies House API — no scraping, no blocking, no CAPTCHAs. - Rate-limited internally to stay under Companies House's 600 requests/5 minutes cap, so large runs won't hit 429s. - AI is optional. Without a key, you still get the full company data and filing-signal lead score — just no AI summary or outreach copy. # Actor input Schema ## `companiesHouseApiKey` (type: `string`): Free UK government API key. Register at developer.companieshouse.gov.uk — required, this is the actor's core data source. ## `sicCodes` (type: `string`): Filter by UK SIC industry codes, e.g. "62012,70229" for IT consultancy + management consultancy. Leave blank for all industries. ## `location` (type: `string`): Filter by registered office location, e.g. "Manchester" or "London". Leave blank for all UK. ## `companyStatus` (type: `array`): Only include companies with this status. Active is almost always what you want for lead generation. ## `incorporatedFrom` (type: `string`): Only include companies incorporated on or after this date. Leave blank for no lower bound. ## `incorporatedTo` (type: `string`): Only include companies incorporated on or before this date. Leave blank for no upper bound. ## `maxResults` (type: `integer`): Maximum number of companies to process. Free trial is capped at 8 regardless of this value. ## `signalWindowDays` (type: `integer`): How far back to look for funding filings (SH01), leadership changes, and "newly incorporated" status when scoring leads. ## `anthropicApiKey` (type: `string`): Enables AI intent analysis and outreach message generation. Tried before Gemini if both are set. ## `geminiApiKey` (type: `string`): Free-tier alternative to Anthropic for AI intent analysis and outreach generation. ## `yourName` (type: `string`): Used to personalise generated outreach messages. ## `yourBusiness` (type: `string`): Used to personalise generated outreach messages. ## `yourService` (type: `string`): What you offer — used to write relevant outreach messages. ## `yourEmail` (type: `string`): Included in generated outreach templates. ## `yourPhone` (type: `string`): Included in generated outreach templates. ## `deliverEmail` (type: `boolean`): Email the results as a CSV attachment via SMTP. ## `smtpHost` (type: `string`): Required if email delivery is enabled. ## `smtpPort` (type: `integer`): Usually 587 (STARTTLS) or 465 (SSL). ## `smtpUser` (type: `string`): Required if email delivery is enabled. ## `smtpPass` (type: `string`): Required if email delivery is enabled. ## `toEmail` (type: `string`): Recipient email address for CSV delivery. ## `fromEmail` (type: `string`): Defaults to the SMTP username if left blank. ## `deliverWebhook` (type: `boolean`): POST results to a webhook URL (Zapier, Make, your own CRM, etc.) ## `webhookUrl` (type: `string`): Required if webhook delivery is enabled. ## `webhookFormat` (type: `string`): JSON payload or CSV body. ## `webhookPerRecord` (type: `boolean`): Required by Zapier catch hooks and most CRMs — sends one POST per lead instead of one bulk POST. ## `deliverSlack` (type: `boolean`): Post a summary of the top leads to a Slack channel. ## `slackWebhookUrl` (type: `string`): Required if Slack delivery is enabled. ## `slackChannel` (type: `string`): Optional — overrides the webhook's default channel. ## `deliverHubSpot` (type: `boolean`): Create HubSpot contacts for each lead. ## `hubspotToken` (type: `string`): Required if HubSpot delivery is enabled. ## Actor input object example ```json { "sicCodes": "", "location": "", "companyStatus": [ "active" ], "incorporatedFrom": "", "incorporatedTo": "", "maxResults": 25, "signalWindowDays": 180, "yourName": "", "yourBusiness": "", "yourService": "", "yourEmail": "", "yourPhone": "", "deliverEmail": false, "smtpHost": "", "smtpPort": 587, "smtpUser": "", "toEmail": "", "fromEmail": "", "deliverWebhook": false, "webhookUrl": "", "webhookFormat": "json", "webhookPerRecord": false, "deliverSlack": false, "slackWebhookUrl": "", "slackChannel": "", "deliverHubSpot": false } ```` # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = {}; // Run the Actor and wait for it to finish const run = await client.actor("automationnation/companies-house-leads").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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = {} # Run the Actor and wait for it to finish run = client.actor("automationnation/companies-house-leads").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{}' | apify call automationnation/companies-house-leads --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=automationnation/companies-house-leads", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "UK Companies House Leads — Filing Signals & AI Outreach", "version": "0.1", "x-build-id": "WEchNQ9JCtvvgF9d3" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/automationnation~companies-house-leads/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-automationnation-companies-house-leads", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/automationnation~companies-house-leads/runs": { "post": { "operationId": "runs-sync-automationnation-companies-house-leads", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/automationnation~companies-house-leads/run-sync": { "post": { "operationId": "run-sync-automationnation-companies-house-leads", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "companiesHouseApiKey": { "title": "Companies House API Key (free)", "type": "string", "description": "Free UK government API key. Register at developer.companieshouse.gov.uk — required, this is the actor's core data source." }, "sicCodes": { "title": "SIC codes (comma-separated)", "type": "string", "description": "Filter by UK SIC industry codes, e.g. \"62012,70229\" for IT consultancy + management consultancy. Leave blank for all industries.", "default": "" }, "location": { "title": "Location", "type": "string", "description": "Filter by registered office location, e.g. \"Manchester\" or \"London\". Leave blank for all UK.", "default": "" }, "companyStatus": { "title": "Company status", "type": "array", "description": "Only include companies with this status. Active is almost always what you want for lead generation.", "items": { "type": "string", "enum": [ "active", "dissolved", "liquidation", "receivership", "administration" ] }, "default": [ "active" ] }, "incorporatedFrom": { "title": "Incorporated from (YYYY-MM-DD)", "type": "string", "description": "Only include companies incorporated on or after this date. Leave blank for no lower bound.", "default": "" }, "incorporatedTo": { "title": "Incorporated to (YYYY-MM-DD)", "type": "string", "description": "Only include companies incorporated on or before this date. Leave blank for no upper bound.", "default": "" }, "maxResults": { "title": "Max results", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Maximum number of companies to process. Free trial is capped at 8 regardless of this value.", "default": 25 }, "signalWindowDays": { "title": "Filing signal window (days)", "minimum": 30, "maximum": 730, "type": "integer", "description": "How far back to look for funding filings (SH01), leadership changes, and \"newly incorporated\" status when scoring leads.", "default": 180 }, "anthropicApiKey": { "title": "Anthropic API key (optional)", "type": "string", "description": "Enables AI intent analysis and outreach message generation. Tried before Gemini if both are set." }, "geminiApiKey": { "title": "Google Gemini API key (optional)", "type": "string", "description": "Free-tier alternative to Anthropic for AI intent analysis and outreach generation." }, "yourName": { "title": "Your name", "type": "string", "description": "Used to personalise generated outreach messages.", "default": "" }, "yourBusiness": { "title": "Your business name", "type": "string", "description": "Used to personalise generated outreach messages.", "default": "" }, "yourService": { "title": "Your service", "type": "string", "description": "What you offer — used to write relevant outreach messages.", "default": "" }, "yourEmail": { "title": "Your email", "type": "string", "description": "Included in generated outreach templates.", "default": "" }, "yourPhone": { "title": "Your phone", "type": "string", "description": "Included in generated outreach templates.", "default": "" }, "deliverEmail": { "title": "Deliver via email (CSV)", "type": "boolean", "description": "Email the results as a CSV attachment via SMTP.", "default": false }, "smtpHost": { "title": "SMTP host", "type": "string", "description": "Required if email delivery is enabled.", "default": "" }, "smtpPort": { "title": "SMTP port", "type": "integer", "description": "Usually 587 (STARTTLS) or 465 (SSL).", "default": 587 }, "smtpUser": { "title": "SMTP username", "type": "string", "description": "Required if email delivery is enabled.", "default": "" }, "smtpPass": { "title": "SMTP password", "type": "string", "description": "Required if email delivery is enabled." }, "toEmail": { "title": "Send results to", "type": "string", "description": "Recipient email address for CSV delivery.", "default": "" }, "fromEmail": { "title": "From email", "type": "string", "description": "Defaults to the SMTP username if left blank.", "default": "" }, "deliverWebhook": { "title": "Deliver via webhook", "type": "boolean", "description": "POST results to a webhook URL (Zapier, Make, your own CRM, etc.)", "default": false }, "webhookUrl": { "title": "Webhook URL", "type": "string", "description": "Required if webhook delivery is enabled.", "default": "" }, "webhookFormat": { "title": "Webhook payload format", "enum": [ "json", "csv" ], "type": "string", "description": "JSON payload or CSV body.", "default": "json" }, "webhookPerRecord": { "title": "Send one webhook call per lead", "type": "boolean", "description": "Required by Zapier catch hooks and most CRMs — sends one POST per lead instead of one bulk POST.", "default": false }, "deliverSlack": { "title": "Deliver Slack summary", "type": "boolean", "description": "Post a summary of the top leads to a Slack channel.", "default": false }, "slackWebhookUrl": { "title": "Slack webhook URL", "type": "string", "description": "Required if Slack delivery is enabled.", "default": "" }, "slackChannel": { "title": "Slack channel", "type": "string", "description": "Optional — overrides the webhook's default channel.", "default": "" }, "deliverHubSpot": { "title": "Push to HubSpot", "type": "boolean", "description": "Create HubSpot contacts for each lead.", "default": false }, "hubspotToken": { "title": "HubSpot private app token", "type": "string", "description": "Required if HubSpot delivery is enabled." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```