Batch

Poll an async batch job for status and results

Poll for the status and results of a previously submitted batch job.

This endpoint is free - polling does not consume API credits.

Poll every 2–5 seconds until status reaches a terminal state: complete, partial, failed, or quota_exceeded.

The results array grows as companies are enriched. errors accumulates any failures. Once status is terminal, results and errors are final.

Suggested polling interval:

  • Small batches (≤50): every 5 seconds
  • Medium batches (51–200): every 10 seconds
  • Large batches (201–500): every 15–30 seconds

Example response (in-progress):

{
  "batch_id": "3fa85f64-...",
  "status": "processing",
  "total_companies": 100,
  "completed_companies": 30,
  "credits_charged": 30,
  "results": [...],
  "errors": {},
  "created_at": "2026-03-17T10:00:00Z",
  "expires_at": "2026-03-24T10:00:00Z"
}
get/v1/batch/{batch_id}

Request

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

Path parameters

batch_idstring required

The batch job's ID, as returned by POST /v1/batch when the job was submitted.

Example:bat_9c14e7d2

Response

Batch job status and partial/full results

batch_idstring required

UUID of this batch job.

statusstring required

Current processing state:

  • queued - waiting to start
  • processing - actively being enriched
  • complete - all companies successfully enriched
  • partial - finished with some errors (see errors)
  • quota_exceeded - your monthly quota ran out mid-batch; remaining companies are in errors
  • failed - all companies failed (upstream issue)
total_companiesinteger required

Total number of companies in this batch.

completed_companiesinteger required

Number of companies processed so far (successes + errors).

credits_chargedinteger required

Credits consumed so far. Final value once status is terminal.

resultsobject[]

Enriched profiles for successfully processed companies. Each item has company_number, status: 'success', and data (the enriched profile). Order matches the original request.

errorsobject

Map of company_number → error message for companies that could not be enriched. Empty if all succeeded.

created_atstring required

ISO 8601 timestamp when the batch was submitted.

expires_atstring required

ISO 8601 timestamp when this job and its results will be automatically deleted (7 days after creation).

Example response

{
  "batch_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "completed_companies": 3,
  "created_at": "2026-03-17T10:00:00Z",
  "credits_charged": 3,
  "errors": {},
  "expires_at": "2026-03-24T10:00:00Z",
  "results": [
    {
      "company_number": "00445790",
      "data": {
        "company_name": "TESCO PLC",
        "company_status": "active"
      },
      "status": "success"
    }
  ],
  "status": "complete",
  "total_companies": 3
}

Changes

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