Company

Whole company page in one request

Fetch the profile, compliance, financials, PSC and directors in one call.

Everything the standalone endpoints return, assembled concurrently and delivered in a single response. Intended for anything that renders a whole company at once - a page, a report, a dashboard - where five round trips cost five authentications and five quota decisions to answer one question.

Sections are independent. Each is fetched by the same code that serves its own endpoint, so plan gating, caching and freshness behave identically. If one fails, its key is null and section_errors says why; the rest of the bundle is unaffected. A caller that requires a section must check for null rather than assume presence.

The profile is the exception. It is always included and always fatal: a company that does not exist returns 404 here, exactly as it does on /v1/company/{number}.

section_fetched_at carries the per-section fetched_at instant. Show a reader the oldest of them - collapsing five timestamps into one overstates the freshness of whichever section was cached longest.

Credits: 1. A bundle costs exactly one call against your quota, however many sections it carries - which is the point of it.

Upstream usage: identical to calling the same sections separately - this saves our per-request overhead, not Companies House calls.

Example: /v1/company/00445790/bundle?include=profile,financials

get/v1/company/{company_number}/bundle

Request

  • Base URL: https://api.registrum.co.uk
  • URL: https://api.registrum.co.uk/v1/company/{company_number}/bundle
  • Auth: API key in header X-API-Key

Path parameters

company_numberstring required

The Companies House company number (e.g. 00445790 for Tesco PLC). Numeric-only numbers are zero-padded.

Example:00445790

Query parameters

includestring nullable

Comma-separated sections to return: profile, compliance, financials, psc, directors. Defaults to all five. profile is always included. An unrecognised name is a 400 rather than being ignored.

Example:profile,financials

Response

Bundle returned; individual sections may be null with a reason in section_errors

statusstring

'success' or 'error'

cachedboolean

True if this response was served from cache rather than fetched live

cache_age_secondsinteger nullable

How many seconds ago this data was fetched from Companies House (null if not cached)

fetched_atstring nullable

ISO 8601 instant (UTC) when this data was actually fetched from Companies House. Use this, not cache_age_seconds, to show a user when the data was last checked: an age is measured at the moment this response was produced, so anything that caches the response downstream will overstate freshness by however long it held it. This instant does not drift. Null when unknown - render nothing rather than a guessed date.

data_sourcestring

'live' - fetched from Companies House right now; 'cached' - served from local cache (data is recent, no upstream call needed); 'cached_rate_conserved' - served from cache because the CH API budget is above 70% utilisation; data may be up to 30 days old in this state

credits_usedinteger

Number of API credits consumed by this request

credits_remaininginteger nullable

API credits remaining this month (null in dev mode)

Example response

{
  "cache_age_seconds": 3421,
  "cached": true,
  "credits_remaining": 487,
  "credits_used": 1,
  "data": {
    "company_age_years": 78,
    "company_name": "TESCO PLC",
    "company_number": "00445790",
    "company_status": "active",
    "company_type": "plc"
  },
  "data_source": "cached",
  "status": "success"
}

Changes

No recorded changes to this operation across all 1 revision of this API.