# UK Companies House Enrichment — Officers & Filings (`actor-forge/uk-companies-house-enrichment`) Actor UK company data from the official Companies House API: profiles, officers, and filing history in one enriched row per company. Search by name, company number, or SIC code / incorporation date / location filters. - **URL**: https://apify.com/actor-forge/uk-companies-house-enrichment.md - **Developed by:** [ActorForge](https://apify.com/actor-forge) (community) - **Categories:** Lead generation, Business, Developer tools - **Stats:** 2 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $0.01 / 1,000 results This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.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/platform/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 Enrichment — Officers & Filings UK company data from the official Companies House API: profiles, officers, and filing history in one enriched row per company. Search by name, company number, or SIC code / incorporation date / location filters. Get UK company data with real depth — not just names and addresses. This Companies House scraper/API returns fully-enriched company records: registered details, SIC codes, current and resigned officers, and filing history, straight from the official Companies House register. Build lead lists by SIC code, incorporation date, status, or location (e.g. 'active scaffolding companies in Manchester incorporated since 2020'), enrich a list of company numbers in bulk, or run free-text searches. Data comes from the official API, so results are reliable and always current — no brittle scraping. ### What data does it return? Every run outputs clean, schema-validated rows like these: | companyNumber | name | status | incorporatedOn | registeredAddress | sicCodes | officers | filings | | --- | --- | --- | --- | --- | --- | --- | --- | | 12345678 | EXAMPLE SCAFFOLDING LTD | active | 2019-03-14 | 1 Example Street, Unit 4, Manchester, M1 2AB, England | 43991, 43999 | 2 active, 1 resigned (names, roles, dates) | 25 most recent (date, type, description) | | 87654321 | SAMPLE JOINERY (LEEDS) LTD | active | 2021-09-02 | 22 Demo Road, Leeds, LS1 4XY, England | 43320 | 1 active (name, role, dates) | 25 most recent (date, type, description) | ### How much does it cost? Transparent pay-per-event pricing — you only pay for what you get, and the actor **always respects your run budget**: set a maximum total charge and it stops cleanly at the cap instead of overrunning. | Event | Price | Charged | Worked example | | --- | --- | --- | --- | | `company-result` | $0.005 | per enriched company (profile + officers + filings included) | 1,000 companies = $5.00; 100 companies = $0.50 | | `apify-actor-start` | $0.00005 | per run per GB of memory (platform start fee) | One run at 0.25 GB ≈ $0.0000125 | | `apify-default-dataset-item` | $0.00001 | per dataset row (platform storage fee) | 1,000 companies ≈ $0.01 extra | ### Input options | Field | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `companyNumbers` | array | no | — | Enrich exactly these companies (e.g. 09876543). Takes priority over search terms and filters. | | `searchTerms` | array | no | — | Free-text company name search, e.g. 'plumbing manchester'. Used when no company numbers are given. | | `sicCodes` | array | no | — | Filter by Standard Industrial Classification codes, e.g. 43999 for scaffolding. Combine with status/date/location filters for targeted lead lists. | | `companyStatus` | string | no | `"any"` | Only companies in this state. 'any' disables the filter. | | `incorporatedFrom` | string | no | — | Earliest incorporation date, YYYY-MM-DD. Great for 'new companies' lead lists. | | `incorporatedTo` | string | no | — | Latest incorporation date, YYYY-MM-DD. | | `location` | string | no | — | Registered-office location filter, e.g. 'Manchester'. | | `maxResults` | integer | no | `100` | Stop after this many companies. You are charged per company: 1,000 companies = $5.00. If you set a run budget (max total charge), the actor automatically stays inside it. | | `includeOfficers` | boolean | no | `true` | Attach current and resigned officers (name, role, dates, occupation, nationality). No dates of birth or personal addresses are ever returned. | | `includeFilings` | boolean | no | `true` | Attach the 25 most recent filings (date, category, type, description). | | `apiKey` | string | no | — | Optional: bring your own free key from developer.company-information.service.gov.uk for dedicated throughput (600 requests/5 min per key). Without it, the actor's shared key is used. | ### Limits & honest notes - Official Companies House data only — UK-registered companies (England, Wales, Scotland, Northern Ireland). - Privacy by design: officers' dates of birth and personal addresses are never returned, only statutory business-register fields. - Filing history returns the 25 most recent filings per company; officers are capped at 100 per company. - Throughput is governed by the Companies House rate limit (600 requests/5 min). A fully-enriched company uses 3 requests ≈ 180 companies per 5 minutes. Add your own free API key in the input for dedicated throughput. - Companies not found (e.g. mistyped numbers) are skipped and never charged. - Respects your run budget: set a maximum total charge and the actor stops cleanly at the cap. ### Changelog - **2026-07-05** — Initial release: profile + officers + filing history enrichment, advanced search (SIC / status / dates / location), bring-your-own-key support. --- *Built and maintained by **ActorForge**. Reliability first: every actor in the portfolio is monitored by an automated nightly self-test, and breakages are typically fixed the same day.* # Actor input Schema ## `companyNumbers` (type: `array`): Enrich exactly these companies (e.g. 09876543). Takes priority over search terms and filters. ## `searchTerms` (type: `array`): Free-text company name search, e.g. 'plumbing manchester'. Used when no company numbers are given. ## `sicCodes` (type: `array`): Filter by Standard Industrial Classification codes, e.g. 43999 for scaffolding. Combine with status/date/location filters for targeted lead lists. ## `companyStatus` (type: `string`): Only companies in this state. 'any' disables the filter. ## `incorporatedFrom` (type: `string`): Earliest incorporation date, YYYY-MM-DD. Great for 'new companies' lead lists. ## `incorporatedTo` (type: `string`): Latest incorporation date, YYYY-MM-DD. ## `location` (type: `string`): Registered-office location filter, e.g. 'Manchester'. ## `maxResults` (type: `integer`): Stop after this many companies. You are charged per company: 1,000 companies = $5.00. If you set a run budget (max total charge), the actor automatically stays inside it. ## `includeOfficers` (type: `boolean`): Attach current and resigned officers (name, role, dates, occupation, nationality). No dates of birth or personal addresses are ever returned. ## `includeFilings` (type: `boolean`): Attach the 25 most recent filings (date, category, type, description). ## `apiKey` (type: `string`): Optional: bring your own free key from developer.company-information.service.gov.uk for dedicated throughput (600 requests/5 min per key). Without it, the actor's shared key is used. ## Actor input object example ```json { "companyNumbers": [], "searchTerms": [ "scaffolding london" ], "companyStatus": "any", "maxResults": 100, "includeOfficers": true, "includeFilings": true } ```` # 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 = { "companyNumbers": [], "searchTerms": [ "scaffolding london" ] }; // Run the Actor and wait for it to finish const run = await client.actor("actor-forge/uk-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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "companyNumbers": [], "searchTerms": ["scaffolding london"], } # Run the Actor and wait for it to finish run = client.actor("actor-forge/uk-companies-house-enrichment").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 '{ "companyNumbers": [], "searchTerms": [ "scaffolding london" ] }' | apify call actor-forge/uk-companies-house-enrichment --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=actor-forge/uk-companies-house-enrichment", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "UK Companies House Enrichment — Officers & Filings", "description": "UK company data from the official Companies House API: profiles, officers, and filing history in one enriched row per company. Search by name, company number, or SIC code / incorporation date / location filters.", "version": "0.1", "x-build-id": "NUrn7H2vQlxBLgCzw" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/actor-forge~uk-companies-house-enrichment/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-actor-forge-uk-companies-house-enrichment", "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/actor-forge~uk-companies-house-enrichment/runs": { "post": { "operationId": "runs-sync-actor-forge-uk-companies-house-enrichment", "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/actor-forge~uk-companies-house-enrichment/run-sync": { "post": { "operationId": "run-sync-actor-forge-uk-companies-house-enrichment", "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": { "companyNumbers": { "title": "Company numbers", "type": "array", "description": "Enrich exactly these companies (e.g. 09876543). Takes priority over search terms and filters.", "items": { "type": "string" } }, "searchTerms": { "title": "Search terms", "type": "array", "description": "Free-text company name search, e.g. 'plumbing manchester'. Used when no company numbers are given.", "items": { "type": "string" } }, "sicCodes": { "title": "SIC codes (advanced filter)", "type": "array", "description": "Filter by Standard Industrial Classification codes, e.g. 43999 for scaffolding. Combine with status/date/location filters for targeted lead lists.", "items": { "type": "string" } }, "companyStatus": { "title": "Company status (advanced filter)", "enum": [ "any", "active", "dissolved", "liquidation" ], "type": "string", "description": "Only companies in this state. 'any' disables the filter.", "default": "any" }, "incorporatedFrom": { "title": "Incorporated from (advanced filter)", "type": "string", "description": "Earliest incorporation date, YYYY-MM-DD. Great for 'new companies' lead lists." }, "incorporatedTo": { "title": "Incorporated to (advanced filter)", "type": "string", "description": "Latest incorporation date, YYYY-MM-DD." }, "location": { "title": "Location (advanced filter)", "type": "string", "description": "Registered-office location filter, e.g. 'Manchester'." }, "maxResults": { "title": "Max companies", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Stop after this many companies. You are charged per company: 1,000 companies = $5.00. If you set a run budget (max total charge), the actor automatically stays inside it.", "default": 100 }, "includeOfficers": { "title": "Include officers", "type": "boolean", "description": "Attach current and resigned officers (name, role, dates, occupation, nationality). No dates of birth or personal addresses are ever returned.", "default": true }, "includeFilings": { "title": "Include filing history", "type": "boolean", "description": "Attach the 25 most recent filings (date, category, type, description).", "default": true }, "apiKey": { "title": "Your Companies House API key (optional)", "type": "string", "description": "Optional: bring your own free key from developer.company-information.service.gov.uk for dedicated throughput (600 requests/5 min per key). Without it, the actor's shared key is used." } } }, "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 } } } } } } } } } } ```