---
title: "Bulk enrich up to 50 companies in one request"
method: POST
path: "/v1/enrich"
tags: ["Enrich"]
---

# Bulk enrich up to 50 companies in one request

`POST /v1/enrich`

## Request

- Base URL: `https://api.registrum.co.uk`
- URL: `https://api.registrum.co.uk/v1/enrich`
- Auth: API key in header `X-API-Key`

Enrich up to 50 UK companies in a single request.

Accepts a JSON body with a list of company numbers and returns an enriched profile
for each one. Results are fetched in parallel and served from the 30-day cache
where available.

**Partial success** - each item in the response has its own `status` field. If one
company number is invalid or not found, the rest still succeed. Inspect each item
individually.

**Credits** - this endpoint charges `credits_used = N` where N is the number of
company numbers in the request, regardless of cache hits or errors.

**Example request:**
```json
POST /v1/enrich
{"company_numbers": ["00445790", "03547512"]}
```

**Example response (one success, one not found):**
```json
{
  "status": "success",
  "credits_used": 2,
  "data": [
    {"company_number": "00445790", "status": "success", "data": {...}},
    {"company_number": "99999999", "status": "error", "error": "Company 99999999 not found"}
  ]
}
```

---

**Cache behaviour:** Companies already in cache are returned instantly at no upstream cost.
Cache TTL is 30 days (same as `GET /v1/company/{n}`).

## Request body

- EnrichRequest: Request body for the bulk enrichment endpoint.
  - `company_numbers` string[], required: List of Companies House company numbers to enrich (1–50 per request). Numeric-only numbers are automatically zero-padded to 8 digits.

## Response `200`

Bulk enrichment results returned (partial success is possible)

- EnrichEnvelope: Response envelope for POST /v1/enrich.
  - `status` string: 'success' or 'error'
  - `data` EnrichItem[], nullable: One result per requested company, in request order
    - `company_number` string, required: The company number as supplied (after normalisation)
    - `status` string, required: 'success' or 'error' for this individual company
    - `data` object, nullable: Enriched company profile (null on error)
    - `cached` boolean: True if this result was served from cache
    - `cache_age_seconds` integer, nullable: Seconds since last fetch (null if not cached)
    - `error` string, nullable: Error detail (null on success)
  - `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`: No valid company numbers provided, or more than 50 requested
- `401`: Missing or invalid API key
- `422`: Validation error in request body

---

[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)