Bulk verification

Bulk verification allows you to verify multiple IDs in a single execution flow using the SDK.

It is designed for small to medium batches, where throughput, retry behaviour, and controlled concurrency matter more than raw request volume. While the API accepts individual verification requests at high rates, upstream registries may react poorly to aggressive parallelism. The SDK provides a pool-based execution model to mitigate this.

Bulk helpers build directly on:

• Verify an ID › verification semantics and response structure.
• Verify and decide › decision helpers and interpretation rules.

They don't replace single verification flows. They provide a controlled execution model for running many of them efficiently.

When to use bulk verification

Bulk verification is appropriate when you need to:

• process batches of IDs from imports or backfills
• re-verify previously stored identifiers
• run periodic checks with bounded concurrency
• tolerate partial failure without aborting the whole job

For single-ID checks or latency-sensitive paths, use the standard verification flow described in Verify and decide.

Execution model

Bulk verification uses an internal worker pool with:

• bounded concurrency
• automatic retries with exponential back-off
• respect for upstream rate limits
• optional suppression of request-level errors

Each ID is verified independently. Failures do not prevent other items in the batch from completing.

The engine still performs verification one ID at a time. The SDK only controls how requests are scheduled and retried.

Verifying multiple IDs

1
import { createVerifyVatClient, Verifier } from '@verifyvat/sdk'
2

3
const client = createVerifyVatClient()
4
const verifier = new Verifier(client)
5

6
const results = await verifier.verifyManyIds({
7
    a: { id: '09446231', country: 'GB' },
8
    b: { id: '914778271', type: 'no_orgnr' },
9
    c: '5493000IBP32UQZ0KL24',
10
})

1
from verifyvat_sdk import VerifyVatClient, Verifier
2

3
client = VerifyVatClient()
4
verifier = Verifier(client)
5

6
results = verifier.verify_many_ids(items={
7
    "a": {"id": "09446231", "country": "GB"},
8
    "b": {"id": "914778271", "type": "no_orgnr"},
9
    "c": "5493000IBP32UQZ0KL24",
10
})
11
client.close()

Each entry in results has the shape { input, verification }, repeating the input parameters and containing the same verification output you would receive from a direct call.

Handling partial failure

Bulk verification is intentionally tolerant. Request-level failures, such as timeouts or temporary network errors, are isolated to the affected items. Other IDs in the batch continue processing.

suppress-errors mode is enabled by default for batch verifications, so request-level failures do not raise exceptions. Instead, the SDK returns synthetic, tainted results via the request-error issue. This allows pipelines to complete deterministically even under degraded conditions.

Decision logic can then be applied uniformly, as described in Verify and decide.

Choosing batch size

There is no fixed optimal batch size.

As a general guideline:

• keep batches small enough to allow retries to complete quickly
• avoid large spikes of parallel requests against the same registry
• prefer multiple smaller batches over a single large one

If you need to process very large datasets, consider orchestrating batches at the application level rather than increasing concurrency.

Interpreting results

Each verification result returned by the bulk helper can be interpreted using the same SDK helpers as a single verification.

You can apply describeVerification to each result and use the same decision signals, policies, and routing logic.

See Verify and decide for details on interpretation and decision-making.