# UK Companies House Scraper: Directors & PSCs (`danthedataman/uk-company-register-ledger`) Actor Scrape UK Companies House profiles, directors, PSCs (beneficial owners), filings and charges. Search live records, filter monthly bulk data by SIC code or monitor new companies. - **URL**: https://apify.com/danthedataman/uk-company-register-ledger.md - **Developed by:** [Eli J](https://apify.com/danthedataman) (community) - **Categories:** Business, Lead generation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $0.72 / 1,000 company records This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. 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 Company Register Ledger Collect UK Companies House company profiles, officers, persons with significant control (PSCs), filing history and charges. Look up company numbers and register URLs, search by name or advanced filters, filter an official monthly snapshot, or monitor companies that have not appeared in your earlier runs. No Companies House API key or login is required. This independent Actor reads the anonymous public register and official bulk downloads. It is not affiliated with Companies House. ### Get started Paste company numbers into **companyNumbers** and start the run. Download the dataset as JSON, JSONL, CSV or Excel, or consume it with the Apify API. ```json {"companyNumbers":["15982284"],"maxResults":1,"includeOfficers":true,"includePSCs":true,"includeFilingHistory":true,"includeCharges":true} ``` ### Input Omitted selectors and empty arrays do not cause a lookup. An empty JSON object returns no rows with guidance. Live enrichment is enabled when its toggle is omitted; bulk enrichment is disabled when omitted. Filters within an array use OR; different filters use AND. In live mode, any advanced field starts an additional register-wide search whose results join the numbers, URLs and keywords. The advanced fields also filter all live candidates. To filter a direct list without adding a search, use activeOnly, newCompaniesOnly or minGrade. The company-row cap applies across all live selectors. | Field | Type | Default | What it does | | --- | --- | --- | --- | | `mode` | string | live | Live public register or official monthly bulk snapshot. | | `companyNumbers` | array | \[] | Exact eight-character alphanumeric company numbers, preserving leading zeros and society suffixes; at most 5000. | | `startUrls` | array | \[] | Company, keyword search or advanced-search register URLs. | | `searchQueries` | array | \[] | Company-name keywords; follows result continuations. | | `sicCodes` | array | \[] | Exact SIC codes for live advanced search. | | `companyTypes` | array | \[] | Source company type codes, e.g. ltd, plc, llp. | | `companyStatus` | array | \[] | Live status codes, e.g. active, dissolved. | | `sicCodePrefixes` | array | \[] | Bulk SIC prefixes, OR within this filter. | | `sicKeywords` | array | \[] | Bulk SIC description substrings, case-insensitive OR. | | `companyStatuses` | array | \[] | Bulk status equality, case-insensitive OR; empty means every status. | | `companyCategories` | array | \[] | Bulk legal category equality, case-insensitive OR. | | `postCodePrefixes` | array | \[] | Bulk postcode prefixes, case-insensitive OR. | | `postTowns` | array | \[] | Bulk post town equality, case-insensitive OR. | | `counties` | array | \[] | Bulk county substrings, case-insensitive OR. | | `countries` | array | \[] | Bulk country substrings, case-insensitive OR. | | `location` | string | empty | Live registered office address text. | | `companyNameIncludes` | string | empty | Live name substring to include. | | `companyNameExcludes` | string | empty | Live name substring to exclude. | | `snapshotMonth` | string | empty | Bulk month YYYY-MM; empty selects latest official snapshot. | | `nameContains` | string | empty | Bulk company name substring, case-insensitive. | | `incorporatedFrom` | string | empty | Live inclusive earliest incorporation date. Use YYYY-MM-DD. | | `incorporatedTo` | string | empty | Live inclusive latest incorporation date. Use YYYY-MM-DD. | | `dissolvedFrom` | string | empty | Live inclusive earliest dissolution date. Use YYYY-MM-DD. | | `dissolvedTo` | string | empty | Live inclusive latest dissolution date. Use YYYY-MM-DD. | | `incorporatedSince` | string | empty | Bulk inclusive earliest incorporation date. Use YYYY-MM-DD. | | `incorporatedBefore` | string | empty | Bulk inclusive latest incorporation date. Use YYYY-MM-DD. | | `includeOfficers` | boolean | true in live; false in bulk | Fetch every available officer page; live enabled when omitted, bulk disabled when omitted. | | `includePSCs` | boolean | true in live; false in bulk | Fetch every PSC page, corporate details and statements; live enabled when omitted, bulk disabled when omitted. | | `includeFilingHistory` | boolean | true in live; false in bulk | Fetch all available filing-history pages and stable document links; live enabled when omitted, bulk disabled when omitted. | | `includeCharges` | boolean | true in live; false in bulk | Fetch all charge pages and particulars; live enabled when omitted, bulk disabled when omitted. | | `emitOfficerRecords` | boolean | false | Also emit free flat officer leads with company context; forces officer fetch. | | `monitoringMode` | boolean | false | Only emit previously unseen companies, using the Actor's named monitor store; serialize runs sharing a monitor scope. | | `newCompaniesOnly` | boolean | false | Only companies incorporated less than 90 days ago. | | `newestFirst` | boolean | false | Live advanced search by incorporation date descending, company number descending for same-day ties; recursively partitions date windows. | | `activeOnly` | boolean | false | Only companies with Active status. | | `minGrade` | string | D | Keep this grade and better (A, B, C, D); D includes all. Heuristic, not a credit rating. | | `maxResults` | integer | 100; `0` means all matches | Maximum company rows across inputs; 0 means all matching rows. Officer rows do not consume this cap. | | `maxConcurrency` | integer | 5 | Maximum concurrent HTTP requests, with a shared two-requests-per-second pace. | | `maxRetriesPerRequest` | integer | 3 | Classified request attempts, including the first. | | `logEveryNRows` | integer | 100000 | Bulk progress interval in scanned CSV rows. | | `proxyConfiguration` | object | direct | Direct anonymous egress when absent; optional Apify proxy settings. Use datacenter first; residential only when necessary. | ### Examples Company and search URLs can be mixed: ```json {"startUrls":[{"url":"https://find-and-update.company-information.service.gov.uk/company/15982284"},{"url":"https://find-and-update.company-information.service.gov.uk/search/companies?q=software"}],"maxResults":10} ``` Keyword search follows result pages: ```json {"searchQueries":["green energy"],"maxResults":25,"emitOfficerRecords":true} ``` Advanced search with an incorporation window: ```json {"sicCodes":["62012"],"location":"London","companyStatus":["active"],"incorporatedFrom":"2026-10-01","incorporatedTo":"2026-10-07","newestFirst":true,"maxResults":100} ``` Newest-first search partitions incorporation windows and follows every page in each resulting window. It sorts incorporation dates descending and company numbers descending within the same date. It cannot recover results hidden by the source's 10,000-result cap for a single day. The affected search stops at that day and is recorded in ERRORS; independent selectors continue. Narrow the filters or use bulk mode. A monthly snapshot, without live enrichment: ```json {"mode":"bulk","snapshotMonth":"2026-10","sicCodePrefixes":["62"],"sicKeywords":["software"],"companyStatuses":["Active"],"postTowns":["LONDON"],"maxResults":100} ``` Omit **snapshotMonth** for the latest snapshot, or select a published historical month. Downloads are processed one ZIP part at a time, with the CSV streamed directly from the archive. The scan stops at the requested delivered-company cap; `maxResults: 0` scans all parts and returns every match. The official snapshot is monthly and can omit companies outside that export. Add **includeOfficers**, **includePSCs**, **includeFilingHistory** or **includeCharges** to enrich bulk matches from the live register. The original structured snapshot address and accounts metadata remain; live fields carry the retrieval timestamp and **snapshotDate** identifies the discovery snapshot. To monitor newly seen companies, schedule a run: ```json {"companyNameIncludes":"software","incorporatedFrom":"2026-10-01","monitoringMode":true,"newCompaniesOnly":true,"maxResults":100} ``` Monitor state is held in the named `uk-company-register-ledger-monitor` key-value store, scoped to selectors and filters. Changing an incorporation window (including dates in search URLs), snapshot month, result cap, sort order or enrichment toggles retains that scope. The first run emits all eligible unseen companies; later runs emit only unseen company numbers. Updating an existing company's officers or filings does not make that company new. Run one monitor job per scope at a time to avoid concurrent delivery races. ### Output Company rows use **recordType: company**. Flat officer leads use **recordType: officer** and include every officer field plus companyName, companyNumber, companyStatus and companyUrl. Only company rows generate the Actor's **company** event; officer leads generate no additional Actor event. The Pricing tab governs the actual run bill. Illustrative company row: ```json { "recordType":"company", "companyNumber":"15982284", "companyName":"JOLLY GAMES LTD", "companyStatus":"Active", "companyType":"Private limited Company", "incorporatedOn":"2024-09-27", "registeredOfficeAddress":"5 Brayford Square, London, United Kingdom, E1 0SG", "sicCodes":[{"code":"47910","description":"Retail sale via mail order houses or via Internet"}], "officers":[{"name":"FISCHER, Jurij","role":"Director","status":"Active","appointedOn":"2025-10-03","identityVerificationDue":"2026-10-22"}], "pscs":[{"name":"Mr Jurij Fischer","status":"Active","kind":"individual","natureOfControlCodes":["ownership-of-shares-75-to-100-percent"]}], "pscStatements":[], "pscExemptReason":null, "filings":[{"date":"2025-10-10","type":"CERTNM","documentId":"MzQ4NDQzMTQ4OGFkaXF6a2N4","documentUrl":"https://find-and-update.company-information.service.gov.uk/company/15982284/filing-history/MzQ4NDQzMTQ4OGFkaXF6a2N4/document?format=pdf&download=0","pages":3}], "charges":[], "sourceTruncated":[], "sourceUrl":"https://find-and-update.company-information.service.gov.uk/company/15982284", "snapshotDate":null, "scrapedAt":"2026-10-07T00:00:00Z" } ``` The example uses held Companies House values to illustrate a subset of the fields; it is not a current-run receipt. | Data | Included values | | --- | --- | | Profile | Name, number, status/type, incorporation/dissolution dates, office address, SIC codes/descriptions, previous names, charges/insolvency flags | | Accounts and confirmation statements | Next/last dates, due dates and overdue flags; bulk also includes accounting reference day/month and category, annual returns | | Officers | Name, identifier/appointments URL, role/status, DOB month/year as displayed, appointment/resignation dates, nationality/residence, correspondence address, corporate registration, verification status/from/due where displayed | | PSCs | People/corporate entities, status, notified/ceased/withdrawn dates, DOB month/year, nationality/residence/address, legal form/law/registration, nature-of-control text and machine-readable source codes, verification details | | Statements and exemption | PSC statements are separate from people; source exemption explanation is preserved | | Filings | Filing date/type/description, document ID, stable original-document redirect URL and page count | | Charges | Description/code/status, created/delivered/satisfied dates, entitled persons, particulars and register totals | | Bulk-specific data | Structured address, countryOfOrigin, accounts, returns, mortgages, confirmationStatement, up to ten previous names, apiUrl, snapshotDate | | Derived values | Company age in years and days, active/new-company flags, industry from the first SIC description, officer/director/active PSC counts, primary officer, leadScore, riskScore, riskGrade | | Provenance | sourceUrl, scrapedAt (UTC), snapshotDate for bulk discovery, sourceTruncated, registerSectionsUnavailable | **leadScore** and **riskScore** are transparent 0–100 heuristics: 60 points for Active status, 20 for neither filing deadline being overdue, and 20 for being at least 730 days old. A = 90–100, B = 70–89, C = 50–69, D = 0–49. Higher means stronger on those three signals. **scoreScale** states the interpretation. These are not credit ratings, financial forecasts or independent verification of filed information. Resolved assurance companies, charities, investment companies with variable capital, protected cell companies, registered/industrial societies, royal charter companies and UK establishments may have reduced register sections. Unpublished fields and arrays are null. **registerSectionsUnavailable** explicitly lists unavailable sections (officers, psc, filing_history, charges); available requested sections are still read. These resolved profiles generate a normal company event. Requested officer, PSC, filing and charge continuations are followed to exhaustion. An unreadable required page or identity mismatch omits that company and records its reason in ERRORS. Arrays are null when their family is not requested; an empty array means a successfully read empty answer. Missing source fields are null. Counts from the register and extracted counts are separate. A legacy PSC page may omit status; its derived active count is then null. Public-company exemptions can correctly produce an empty PSC list. Abbreviated charge particulars are flagged in sourceTruncated, with each charge's sourceUrl linking to its detail page. In bulk rows, the source SIC literal **None Supplied** means no supplied SIC code: sicCodes and sicCodeList are empty, and sicCodesSourceNote preserves that exact literal. The source note is null when the CSV supplies codes or leaves the SIC cells blank. Original document URLs point to the register's redirect endpoint rather than expiring signed storage URLs. The Actor does not download or parse PDFs. Register data can change or be corrected after a run, and Companies House states that it does not check the accuracy of information filed. ### Limits and errors Live search is bounded by what the public register exposes. Advanced searches exceeding 10,000 matches are divided into incorporation-date windows. A single day exceeding the cap needs narrower filters or bulk mode. Bulk has monthly freshness, with live enrichment optional. Source errors and unresolvable inputs are stored under **ERRORS**, never as dataset rows. Valid empty results succeed with guidance; a call where all attempts fail is marked failed. **Full scans.** The measured full seven-part monthly scan with no matching rows or live enrichment took 410.897 seconds with a 1024 MB allocation. A full monthly scan can exceed a 300-second timeout; the default timeout is 1800 seconds. Live enrichment of matching companies adds time. The primary path uses anonymous HTTP, a conservative shared two-request-per-second pace and bounded classified retries. After retry and fresh-session exhaustion for a block, network failure or missing data, a separate browser service reads the page, and the result goes through the same parser and validation. Browser-service usage is not added to your bill; run-start and company charges apply as usual. A run gets at most 8 fallback calls, failed calls included, and 110 seconds of fallback time, within the time left before the run's timeout. A fallback call that fails or is refused goes to **ERRORS** and is not charged as a company. Fallback reads observe the same shared pace and cooldown. HTTP 404 is a missing input and does not start a fallback read; HTTP 403 or a malformed source answer retries with a fresh session; HTTP 429 observes at least a five-minute cooldown and any longer Retry-After. A maximum-charge result stops the work loop before another source read. ### Use your data Export from Apify storage, start runs through the Apify API, and use Apify Schedules or webhooks for recurring jobs. Start with a small result cap and inspect the dataset before a large extraction. Companies House is the source. The public service footer provides Open Government Licence attribution except where otherwise stated; follow field-specific reuse conditions and the register's personal-data guidance. Public officer and PSC information can be personal data. Use it only for purposes you are entitled to pursue. ### Support Open an issue with the run ID, input and ERRORS record. Do not include credentials. Support owner: danthedataman. ### Local checks Install requirements.txt into a Python virtual environment and run `python -m unittest discover -s tests -v`. Tests stand in for the browser service; none opens a browser. The production Dockerfile pins `apify/actor-python:3.13` by digest and installs requirements.txt with the versions in constraints.txt; Playwright is not installed. # Changelog This Actor's version history is a separate document: https://apify.com/danthedataman/uk-company-register-ledger/changelog.md # Actor input Schema ## `mode` (type: `string`): Live public register or official monthly bulk snapshot. ## `companyNumbers` (type: `array`): Exact eight-character company numbers; at most 5000. ## `startUrls` (type: `array`): Company, keyword search or advanced-search register URLs. ## `searchQueries` (type: `array`): Company-name keywords; follows result continuations. ## `sicCodes` (type: `array`): Exact SIC codes for live advanced search. In live mode, this also starts an additional register-wide advanced search combined with other selectors and filters all live candidates. ## `companyTypes` (type: `array`): Source company type codes, e.g. ltd, plc, llp. In live mode, this also starts an additional register-wide advanced search combined with other selectors and filters all live candidates. ## `companyStatus` (type: `array`): Live status codes, e.g. active, dissolved. In live mode, this also starts an additional register-wide advanced search combined with other selectors and filters all live candidates. ## `sicCodePrefixes` (type: `array`): Bulk SIC prefixes, OR within this filter. ## `sicKeywords` (type: `array`): Bulk SIC description substrings, case-insensitive OR. ## `companyStatuses` (type: `array`): Bulk status equality, case-insensitive OR; empty means every status. ## `companyCategories` (type: `array`): Bulk legal category equality, case-insensitive OR. ## `postCodePrefixes` (type: `array`): Bulk postcode prefixes, case-insensitive OR. ## `postTowns` (type: `array`): Bulk post town equality, case-insensitive OR. ## `counties` (type: `array`): Bulk county substrings, case-insensitive OR. ## `countries` (type: `array`): Bulk country substrings, case-insensitive OR. ## `location` (type: `string`): Live registered office address text. In live mode, this also starts an additional register-wide advanced search combined with other selectors and filters all live candidates. ## `companyNameIncludes` (type: `string`): Live name substring to include. In live mode, this also starts an additional register-wide advanced search combined with other selectors and filters all live candidates. ## `companyNameExcludes` (type: `string`): Live name substring to exclude. In live mode, this also starts an additional register-wide advanced search combined with other selectors and filters all live candidates. ## `snapshotMonth` (type: `string`): Bulk month YYYY-MM; empty selects latest official snapshot. ## `nameContains` (type: `string`): Bulk company name substring, case-insensitive. ## `incorporatedFrom` (type: `string`): Live inclusive earliest incorporation date. Use YYYY-MM-DD. In live mode, this also starts an additional register-wide advanced search combined with other selectors and filters all live candidates. ## `incorporatedTo` (type: `string`): Live inclusive latest incorporation date. Use YYYY-MM-DD. In live mode, this also starts an additional register-wide advanced search combined with other selectors and filters all live candidates. ## `dissolvedFrom` (type: `string`): Live inclusive earliest dissolution date. Use YYYY-MM-DD. In live mode, this also starts an additional register-wide advanced search combined with other selectors and filters all live candidates. ## `dissolvedTo` (type: `string`): Live inclusive latest dissolution date. Use YYYY-MM-DD. In live mode, this also starts an additional register-wide advanced search combined with other selectors and filters all live candidates. ## `incorporatedSince` (type: `string`): Bulk inclusive earliest incorporation date. Use YYYY-MM-DD. ## `incorporatedBefore` (type: `string`): Bulk inclusive latest incorporation date. Use YYYY-MM-DD. ## `includeOfficers` (type: `boolean`): Fetch every available officer page; live enabled when omitted, bulk disabled when omitted. ## `includePSCs` (type: `boolean`): Fetch every PSC page, corporate details and statements; live enabled when omitted, bulk disabled when omitted. ## `includeFilingHistory` (type: `boolean`): Fetch all available filing-history pages and stable document links; live enabled when omitted, bulk disabled when omitted. ## `includeCharges` (type: `boolean`): Fetch all charge pages and particulars; live enabled when omitted, bulk disabled when omitted. ## `emitOfficerRecords` (type: `boolean`): Also emit free flat officer leads with company context; forces officer fetch. ## `monitoringMode` (type: `boolean`): Only emit previously unseen companies, using the Actor's named monitor store; serialize runs sharing a monitor scope. ## `newCompaniesOnly` (type: `boolean`): Only companies incorporated less than 90 days ago. ## `newestFirst` (type: `boolean`): Live advanced search by incorporation date descending, company number descending for same-day ties; recursively partitions date windows. ## `activeOnly` (type: `boolean`): Only companies with Active status. ## `minGrade` (type: `string`): Keep this grade and better (A, B, C, D); D includes all. Heuristic, not a credit rating. ## `maxResults` (type: `integer`): Maximum company rows across inputs; 0 means all matching rows. Officer rows do not consume this cap. ## `maxConcurrency` (type: `integer`): Maximum concurrent HTTP requests, with a shared two-requests-per-second pace. ## `maxRetriesPerRequest` (type: `integer`): Classified request attempts, including the first. ## `logEveryNRows` (type: `integer`): Bulk progress interval in scanned CSV rows. ## `proxyConfiguration` (type: `object`): Direct anonymous egress when absent; optional Apify proxy settings. Use datacenter first; residential only when necessary. ## Actor input object example ```json { "companyNumbers": [ "15982284" ], "includeOfficers": true, "includePSCs": true, "includeFilingHistory": true, "includeCharges": true, "maxResults": 1 } ``` # Actor output Schema ## `results` (type: `string`): No description ## `errors` (type: `string`): Handled request failures, when present; never result rows. # 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": [ "15982284" ], "includeOfficers": true, "includePSCs": true, "includeFilingHistory": true, "includeCharges": true, "maxResults": 1 }; // Run the Actor and wait for it to finish const run = await client.actor("danthedataman/uk-company-register-ledger").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": ["15982284"], "includeOfficers": True, "includePSCs": True, "includeFilingHistory": True, "includeCharges": True, "maxResults": 1, } # Run the Actor and wait for it to finish run = client.actor("danthedataman/uk-company-register-ledger").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": [ "15982284" ], "includeOfficers": true, "includePSCs": true, "includeFilingHistory": true, "includeCharges": true, "maxResults": 1 }' | apify call danthedataman/uk-company-register-ledger --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,danthedataman/uk-company-register-ledger" } } } ``` 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 ` 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/9CbEzADQ2sXrcZxDL/builds/VCCeamEYWSWZ8GpSe/openapi.json