--- title: "Map connected companies via shared directors" method: GET path: "/v1/company/{company_number}/network" tags: ["Directors"] --- # Map connected companies via shared directors `GET /v1/company/{company_number}/network` ## Request - Base URL: `https://api.registrum.co.uk` - URL: `https://api.registrum.co.uk/v1/company/{company_number}/network` - Auth: API key in header `X-API-Key` Discover all companies connected to the target through shared board members. This is the key differentiator of this API: starting from one company, you can see every other company that shares at least one current director, revealing hidden governance links and corporate group structures. - **connections** - each connected company with the list of shared director names - **connection_strength** - number of shared directors (higher = stronger link) - **truncated** - `true` if depth=2 traversal hit the 30-company cap (see below) - Results are sorted by connection strength (strongest first) Only genuine board directors contribute to connections - corporate secretaries (e.g. a company secretarial provider shared by thousands of client companies) are excluded, so a shared corporate-secretary provider never creates a phantom "connection" between otherwise unrelated companies. **Depth 1** (default): direct connections only - companies sharing a director with the target. **Depth 2**: also traverses each connected company's directors to find second-degree connections. This reveals wider networks but is upstream-intensive on cold cache. Data is cached for 30 days (cache key includes depth). If the Companies House API is down, stale cached data is returned with `cached: true`. **Plan gating:** `depth=2` requires a Pro or Enterprise plan (403 for Free/Web). `depth=1` is available on all plans. **Example:** `/v1/company/00445790/network?depth=1` shows companies connected to Tesco PLC. --- **Upstream usage:** This is the most upstream-intensive endpoint. - **Depth 1 (cold cache):** same as `/directors` - ~N+2 upstream calls, where N is the number of directors. A 10-director company uses ~12 calls; a 50-director company uses ~52 calls. After first fetch, cached for 30 days at no cost. - **Depth 2 (cold cache):** traverses each connected company's directors as well. To protect service quality for all customers, traversal is **capped at 30 connected companies** per request. Typical upstream cost: 50–200 calls. If the cap is hit, the response includes `truncated: true` and `truncated_at: 30` - this means more connections exist but were not explored. **Practical guidance:** Depth=2 on cold cache is slow by design. On a warm cache (after the first request), depth=2 is instant and free. If you need depth=2 across many companies, call `/directors` for each first to warm the cache, then request the network. At high volume, **querying more than ~8 different companies per minute at depth=1** or **more than 2–3 different companies per 5 minutes at depth=2** on cold cache will cause responses to slow while upstream capacity recovers. ## Path parameters - `company_number` string, required: The Companies House company number. 8 alphanumeric characters (e.g., `00445790` for Tesco PLC). Numeric-only numbers are automatically zero-padded. ## Query parameters - `depth` integer: Network traversal depth. `1` = companies sharing directors with the target (default). `2` = also includes companies connected to those companies (slower, more results). ## Response `200` Network map returned successfully, sorted by connection strength - NetworkEnvelope: Response envelope for GET /v1/company/{company_number}/network. - `status` string: 'success' or 'error' - `data` NetworkResponse: Network of companies connected through shared directors. - `company_number` string, required: 8-character Companies House number of the target company - `company_name` string, nullable: Registered name of the target company - `connections` NetworkConnection[]: Companies connected through shared board members, sorted by connection strength (strongest first) - `company_number` string, required: 8-character Companies House number of the connected company - `company_name` string, required: Registered name of the connected company - `company_status` string, nullable: Status: 'active', 'dissolved', etc. - `shared_directors` string[]: Names of directors shared between the target company and this connected company - `connection_strength` integer: Number of shared directors - higher means a stronger governance link - `depth` integer: Network traversal depth (1 = direct connections only, 2 = connections of connections) - `total_connections` integer: Total number of connected companies found - `total_shared_directors` integer: Total number of unique director links across all connections - `cached` boolean: True if this response was served from cache rather than fetched live - `cache_age_seconds` integer, nullable: How many seconds ago this data was fetched from Companies House (null if not cached) - `fetched_at` string, 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_source` string: '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_used` integer: Number of API credits consumed by this request - `credits_remaining` integer, nullable: API credits remaining this month (null in dev mode) ## Other responses - `400`: Invalid company number format, an empty company number (blank path segment), or an invalid depth value - `401`: Missing or invalid API key - `403`: Pro or Enterprise plan required for depth=2 - `404`: Company not found at Companies House - `422`: Validation Error - `502`: Companies House API is temporarily unavailable - `503`: Request shed to protect shared Companies House capacity; retry after the seconds given in the Retry-After header --- [API](https://skmtc.dev/registrum/apis/registrum-api.md) · [All operations](https://skmtc.dev/registrum/apis/registrum-api/llms.txt) · [OpenAPI document](https://skmtc.dev/registrum/apis/registrum-api/revisions/2bf0ecf7cc02?raw)