Batch

Submit a batch of up to 500 companies for async enrichment

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:

POST /v1/batch
{"company_numbers": ["00445790", "03547512", "SC123456"]}

Example immediate response:

{
  "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
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

Request body

company_numbersstring[] 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.

Example request

{
  "company_numbers": [
    "00445790",
    "03547512",
    "SC123456"
  ]
}

Response

Batch accepted and queued - use batch_id to poll for results

batch_idstring required

UUID of this batch job. Poll GET /v1/batch/{batch_id} for results.

statusstring

Initial job status - always 'queued' on submission.

total_companiesinteger required

Number of company numbers accepted into this batch.

estimated_wait_secondsinteger required

Rough upper-bound estimate in seconds. In practice most batches complete faster if the cache hit rate is high.

Example response

{
  "batch_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "estimated_wait_seconds": 30,
  "status": "queued",
  "total_companies": 250
}

Changes

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