---
title: "Submit a batch of up to 500 companies for async enrichment"
method: POST
path: "/v1/batch"
tags: ["Batch"]
---

# Submit a batch of up to 500 companies for async enrichment

`POST /v1/batch`

## Request

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

Submit a list of up to 500 UK company numbers for background enrichment.

Unlike `POST /v1/enrich` (which processes up to 50 companies synchronously),
this endpoint accepts much larger lists and processes them in the background,
automatically respecting the shared Companies House API rate limit.

**How it works:**
1. Submit your list - receive a `batch_id` immediately.
2. Poll `GET /v1/batch/{batch_id}` every few seconds until `status` is terminal.
3. Read `results` for successful enrichments and `errors` for any failures.

**Status lifecycle:**
```
queued → processing → complete
                   ↘ partial          (some successes, some errors)
                   ↘ failed           (all companies errored)
                   ↘ quota_exceeded   (monthly credit limit hit mid-batch)
```

**Credits:**
1 credit is charged per company successfully processed (or attempted).
Credits are deducted as processing proceeds, not upfront.
Polling `GET /v1/batch/{batch_id}` is always free.

**Expiry:**
Job results are kept for 7 days after creation and then automatically deleted.

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

**Example immediate response:**
```json
{
  "batch_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "queued",
  "total_companies": 3,
  "estimated_wait_seconds": 10
}
```

**Poll until complete:**
```
GET /v1/batch/3fa85f64-5717-4562-b3fc-2c963f66afa6
```

## Request body

- BatchSubmitRequest: Request body for POST /v1/batch.
  - `company_numbers` string[], required: Ordered list of UK company numbers to enrich. Accepts 1–500 entries per batch. Numbers are zero-padded automatically (e.g. '445790' → '00445790'). Results are delivered in the same order.

## Response `200`

Batch accepted and queued - use batch_id to poll for results

- BatchSubmitResponse: Returned immediately after a batch job is accepted.
  - `batch_id` string, required: UUID of this batch job. Poll GET /v1/batch/{batch_id} for results.
  - `status` string: Initial job status - always 'queued' on submission.
  - `total_companies` integer, required: Number of company numbers accepted into this batch.
  - `estimated_wait_seconds` integer, required: Rough upper-bound estimate in seconds. In practice most batches complete faster if the cache hit rate is high.

## Other responses

- `400`: Empty list or list exceeds 500 companies
- `401`: Missing or invalid API key
- `422`: Validation error in request body
- `503`: Database unavailable - try again shortly

---

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