Companies House UK Scraper (Officers & PSC)

The UK companies register — search by name or look up company numbers, and get the full public record: status, type, incorporation date, registered office, SIC codes and previous names, plus every officer (director and secretary, current and resigned) and every person with significant control.

No login. No API key. HTTP only. This reads the public register website, not the key-gated REST API.

Record type	One per	Carries
SEARCH_SUMMARY	search run	term, register's own total, pages walked, whether the "no results" page was reached
COMPANY	company	number, name, status, type, incorporation date, registered office, SIC codes, previous names
OFFICER	appointment	name, role, status (active/resigned), appointment and resignation dates, nationality, country of residence, occupation, correspondence address, redacted date of birth
PSC	beneficial owner	name, kind, nature of control, notified/ceased dates — plus DOB and nationality for individuals, or legal form, governing law and registration number for entities
ERROR	failed input	_error code and an _errorDetail saying what to change

Things this register will mislead you about

Each is measured, and each has a scenario in tests/smoke/companieshouse-uk-scraper_traps.sh (17/17 passing).

Your spreadsheet has already broken your company numbers. A UK company number is exactly eight characters and its leading zeros are part of it — 00445790 is Tesco. Excel and Google Sheets strip those zeros the moment a column is read as a number, so the commonest way this input arrives is 445790, which the register answers with a 404 that reads as "no such company" rather than "wrong format". This Actor restores the zeros, and uppercases registrar prefixes for the same reason (sc090312 is a 404, SC090312 is NatWest Markets). A number it genuinely cannot repair is refused with a message saying so — and a well-formed number that simply is not on the register gets a different error, so you can tell a typo from an absence.

Most of the officers are not current. The register lists resigned appointments alongside serving ones by default. Tesco shows 74 officers, of which 11 are active. Read as "current management" that is wrong about 85% of the rows, so every officer carries its own appointmentStatus.

Officers are paginated 35 to a page. Reading one page returns less than half the register's answer, with no error and a perfectly plausible result. This Actor walks every page.

A date of birth is month and year only. Companies House redacts the day for individuals. This Actor keeps what was published (dateOfBirthRaw) and splits it into dateOfBirthMonth / dateOfBirthYear — it never assembles a full date, because that would assert a birthday the register deliberately withholds.

A search that matches nothing is an HTTP 200 carrying a "No results" block. Zero rows alone cannot distinguish that from the markup having moved, so the summary reports noResultsBlockSeen explicitly.

PSC records come in two disjoint shapes. An individual carries a date of birth, nationality and place of residence; a corporate entity carries governing law, legal form, place registered, registration number and country of incorporation. They share little beyond the address and nature of control, so pscKind labels which you have and fields preserves everything the register actually published for that record.

Two markup details that quietly corrupt text, both handled: the status badge is nested inside the name and role cells with no separator (a raw read gives RoleActive and names ending in …Active), and the identity-verification cell contains an inline SVG stylesheet whose CSS otherwise bleeds into the value.

Notes

The register is a public GOV.UK service. Requests are paced by default (minRequestInterval, 0.5s) and a proxy is off by default — no anti-bot layer was observed on any surface, and robots.txt is a genuine 404.

Search results carry only a name and a number; set fetchDetails to follow each hit to its profile, and includeOfficers / includePsc to pull the people. Each of those is one extra request per company, so a large search with everything enabled is a large number of requests — keep maxResults honest.