Batches

Batches create one Check per record while preserving a shared bulk-job status. Use them for lookbacks, migrations, and scheduled portfolio work that does not need an immediate per-request response.

Create a Batch

POST /v1/check_batches accepts up to 1,000 records. Each record contains up to 100 typed subjects and identifies either an existing applicant_id or an external_id for reconciliation.

{
  "use_case": "lookback",
  "mode": "async",
  "datasets": ["sanctions", "pep", "regulatory_enforcement"],
  "records": [
    {
      "applicant_id": "7f9ee48f-4b03-4b51-93c8-629872f067cc",
      "external_id": "portfolio-row-1",
      "subjects": [
        {
          "type": "company",
          "role": "customer",
          "name": "Example Holdings Ltd",
          "country": "GB"
        }
      ]
    }
  ]
}

Async is the default. Use a stable idempotency key for job retries.

Convert CSV safely

CSV rows represent subjects, not necessarily Checks. Group rows by applicant_id or your external record ID before creating the Batch. This lets one payment or customer record include several parties without producing unrelated Checks.

Validate the complete file before submission:

• every row has a group identifier;
• each group resolves to one Applicant;
• subject type and role values are recognized;
• type-specific identifiers are in the correct columns;
• a group does not exceed the per-record subject limit.

Track and download

List jobs with GET /v1/check_batches, inspect one at GET /v1/check_batches/{batch_id}, and download results from GET /v1/check_batches/{batch_id}/download.

Use format=json for machine ingestion and format=csv for operator workbooks. A completed Batch can contain record-level errors; inspect its counts and error details rather than treating job completion as universal success.