UK Company Filing & Insolvency Delta

Monitor official Companies House records and receive evidence-backed corporate changes instead of repeated raw snapshots.

What it monitors

• company status, name, registered office, and SIC classifications;
• new filing-history transactions;
• officer appointments, removals, and material field changes;
• charges created or changed, including observable satisfaction/release status;
• insolvency appearance and case changes.

Only the official Companies House Public Data API is used. There is no browser, proxy, AI, CAPTCHA service, or private endpoint.

First run

The first successful run creates a free baseline. Existing records are saved for comparison and are not reported as new changes. Keep the same monitorKey on scheduled runs.

{ "companyNumbers": ["03782379"], "monitorKey": "supplier-risk" }

Output

The default dataset contains:

• baseline — counts and a clear first-run explanation;
• change — stable event ID, company identity, change type, changed fields, previous/current values, timestamp, and official evidence URL;
• diagnostic — blocked, failed, or bounded-limit outcomes.

Missing public values remain null. A 404 for charges or insolvency after a successful company profile is legitimate optional-resource absence—not a source failure. Filing transaction IDs identify filings. Charges prefer charge_code, falling back to their unique self-resource identity.

Billing proposal

Provisional PPE event: company-checked at $0.01 per successful recurring company check. Baselines, failed companies, blocked companies, retries, duplicate inputs, diagnostics, and duplicate event recovery are not charged. This unit reflects the recurring monitoring value and remains well above estimated infrastructure cost. Store pricing is not configured in this local build.

Limits

Defaults: 100 companies, five concurrent acquisitions, 100 records/page, ten pages/resource, 15-second transaction timeout, 5 MB/response, and a 550-request run budget. Companies House permits 600 requests per five minutes. Highly active baselines can reach a configured page bound; the summary reports this explicitly.

See docs/ARCHITECTURE.md, docs/PREMORTEM.md, docs/OWNER_RUNBOOK.md, and docs/LIVE_VALIDATION.md.

Who this Actor is for

Operations, monitoring, research, and data teams that need monitor official companies house profiles, filings, officers, charges and insolvency resources. It is designed for scheduled Apify, API, webhook, integration, and MCP-compatible workflows—not for unsupported professional conclusions.

Input reference

• companyNumbers (required): Eight-digit Companies House numbers, including valid two-letter prefixes such as SC, NI, OC, or FC.
• monitorKey: A stable private name for this watchlist. Changing it creates a separate baseline.
• maxCompanies: Stops the run before checking more than this many unique company numbers.
• enableAdvancedLimit: Advanced mode. Large watchlists may span multiple rate-limit windows and should be validated gradually.
• maxConcurrency: Number of companies acquired concurrently while output remains deterministically ordered.
• requestTimeoutSecs: Maximum total time for headers and body streaming of one official API request.
• maxRequestRetries: Retries only temporary 429, timeout, and server failures with bounded backoff.
• maxResponseBytes: Aborts a response while streaming if it exceeds this memory and bandwidth safety limit.
• maxPagesPerResource: Hard pagination bound for filings, officers, and charges for each company.
• pageSize: Requested page size for supported Companies House list resources.

Representative input (replace placeholders and use only sources you are authorized to access):

{
  "companyNumbers": [
    "Example Company"
  ],
  "monitorKey": "default",
  "maxCompanies": 250,
  "enableAdvancedLimit": false,
  "maxConcurrency": 5,
  "requestTimeoutSecs": 15,
  "maxRequestRetries": 1,
  "maxResponseBytes": 5000000,
  "maxPagesPerResource": 2,
  "pageSize": 100
}

Output reference

• recordType: Structured output field.
• eventId: Structured output field.
• stableId: Structured output field.
• companyNumber: Structured output field.
• companyName: Structured output field.
• changeType: Structured output field.
• entityId: Structured output field.
• changedFields: Structured output field.
• previousValue: Structured output field.
• currentValue: Structured output field.
• sourceUrl: Structured output field.
• sourceResource: Structured output field.
• filingsSaved: Structured output field.
• officersSaved: Structured output field.
• chargesSaved: Structured output field.
• insolvencyCasesSaved: Structured output field.
• message: Structured output field.
• code: Structured output field.
• retryable: Structured output field.
• observedAt: Structured output field.

The first complete run creates an expected baseline where the product uses state. Later comparable runs emit only the documented observations or changes. Dataset records retain deterministic identity and source evidence where the contract requires it.

Limitations and known semantics

• Only the documented source, input forms, fields, identities, and completeness rules are supported.
• An empty, partial, blocked, timed-out, or malformed upstream response is never silently reported as a successful empty result.
• Absence or removal is reported only with the exact observational wording and completeness evidence documented by this Actor; it is not proof of a real-world deletion or status unless the source explicitly says so.
• Upstream publication schedules, schemas, coverage, terms, and availability can change.

Errors and troubleshooting

Check the run status and OUTPUT summary before consuming Dataset rows. For invalid input, correct the named field. For retryable source failures, preserve the monitor key/state and retry later. For schema or completeness failures, do not reset state or infer changes; report the run ID and non-secret diagnostics to support.

API, integrations, and MCP

Run the Actor through the Apify API, Schedule, webhook, or supported integration. Read structured records from the default Dataset and the run summary from the default Key-value store. MCP/agent consumers must preserve source, status, uncertainty, and limitation fields and must not convert observational outputs into unsupported claims.

Privacy and legal notes

Submit only data necessary for the documented workflow and only sources you are authorized to access. Do not include credentials, sensitive personal data, or private URLs unless the Actor explicitly documents secure support for them. Outputs are factual automation evidence, not legal, financial, safety, employment, regulatory, or compliance advice. You remain responsible for source rights, downstream use, retention, and professional review.