buriedsignals/anomaly/companies-house-companies

Query Companies House companies

meta.yaml is the executable contract. Use only released operations.

<!-- BEGIN GENERATED OPERATION STATUS -->

Current catalogue release status

meta.yaml is authoritative. Execute only operations listed as Released below; other sections in this playbook may document provider or unreleased adapter scope.

Released

• gb/companies-house/companies:search-companies — Search official Companies House company summaries by term with offset pagination.
• gb/companies-house/companies:get-company — Retrieve official basic company information by exact Companies House company number.
• gb/companies-house/companies:companies — Company profiles, or every company an advanced search returns for a registered-office location, as companies-contract rows.
• gb/companies-house/companies:company-officers — A company's officers as company_officers rows.
• gb/companies-house/companies:officer-appointments — One officer's appointments across companies as company_officers rows.
• gb/companies-house/companies:company-controllers — A company's persons with significant control as company_controllers rows.

<!-- END GENERATED OPERATION STATUS -->

Authentication and quota

Provide a Live REST API key through the execution context. catalogue sends the key as the HTTP Basic username with an empty password and keeps it out of prompts. Companies House publishes a limit of 600 requests per five minutes; exceeding it returns 429. A 401 means unauthorised, not quota.

Workflow

1. Assess the full request and inspect the operation:

``bash catalogue data assess "<complete question>" --json catalogue data show gb/companies-house/companies:search-companies ``

1. Search candidates with a small page, then retrieve the exact number:

``bash catalogue query gb/companies-house/companies --operation search-companies \ --input '{"q":"BP","items_per_page":5,"start_index":0}' catalogue query gb/companies-house/companies --operation get-company \ --input '{"company_number":"00102498"}' ``

1. Preserve company number exactly, status, type, dates, registered address,

official profile URL, page metadata, and observation date.

Boundaries and cautions

• Search rank and name are candidate evidence; resolve with the company number.
• Leading zeros and letter prefixes are meaningful.
• Basic profile status does not prove current commercial activity or status on

a historical date.

• Filings, charges, insolvency, registers, disqualifications, and PSC

statements are documented provider scope but not released here.

• Register data is filed information and can be corrected or updated.

Fill the companies contract

companies, company-officers, officer-appointments and company-controllers return rows of domains/companies.yaml. Write each to CSV and run the companies detectors with python -m anomaly.oneshot --tables companies=... --tables company_officers=... --tables company_controllers=.... Endpoints follow the Public Data API specification (https://developer-specs.company-information.service.gov.uk/companies-house-public-data-api/reference, read 2026-10-27). No key was configured when these operations were written, so they are tested offline against the documented response shapes only.

catalogue query gb/companies-house/companies --operation companies \
  --input '{"location":"10 Queen Street Place","limit":2000}'
catalogue query gb/companies-house/companies --operation officer-appointments \
  --input '{"officer_id":"<id from company-officers>"}'

Advanced search returns at most 5,000 companies per request (size), and location matches the registered-office address text; an address count is only as complete as that search. PSCs carry no register-wide identifier, so the same person under two spellings counts twice in prolific_officer.

Read the API reference and the query guide for response vocabulary, pagination, no-result recovery, and follow-up verification.

Bundled resources

• references/api-reference.md — official endpoint, profile, quota, auth,

licensing, response mapping, and errors.

• references/query-guide.md — identity resolution and historical cautions.
• scripts/verify.py with assets/verification-cases.json — credentialed checks.
• evals/evals.json — agent-behavior cases.

python3 scripts/verify.py --list
python3 scripts/verify.py