Enrich a list of UK companies safely

The current public API does not expose a bulk entity endpoint. Enrichment is therefore client-side iteration over GET /entity/{company_number}. That boundary matters: a batch is your orchestration layer, not a hidden API feature.

Use bounded concurrency

Start with a small concurrency value and tune it from observed quota and upstream behaviour. The example defaults to four in-flight requests, preserves input order, and starts a new lookup only when a slot becomes free. It does not fire every company number at once.

ROTULI_API_KEY=uk_live_... \
  node examples/bulk-enrichment.mjs 00445790 00013664 00102498

Retry only transient failures

The included RotuliClient retries network errors and HTTP 429, 502, 503, and 504 with bounded exponential backoff. It honours a numeric Retry-After value when one is supplied. Invalid input and not-found responses are returned as individual results instead of being retried.

An upstream_capacity response is distinct from your own rate limit: the shared registry is under pressure. Retry only after its requested interval and keep it visible in the job outcome. The API error reference describes the response codes and retry semantics.

Preserve outcome per company

A batch should not become all-or-nothing because one number is malformed, not found, or temporarily unavailable. Emit an object per input number, then decide which failures should be replayed later.

{
  "companyNumber": "00445790",
  "ok": true,
  "entity": { "company_number": "00445790", "sources_checked": [], "sources_failed": {} }
}

// A per-company failure stays in the result stream:
{ "companyNumber": "not-a-number", "ok": false, "error": { "status": 422 } }

Keep evidence with the enrichment

Store or pass on fetched_at, sources_checked, and sources_failed with the profile. If you request a source subset, record the requested set alongside the result; a missing source may be deliberately skipped rather than unavailable.

Set scope before sending numbers

The script accepts company numbers as arguments and reads its key only from ROTULI_API_KEY. It has no telemetry, persistence, or browser path. For a single lookup, use the company lookup guide; for a risk decision after enrichment, use risk screening.