Skip to main content

Batch Processing

Batch Processing lets you submit multiple subjects for investigation in a single operation — instead of triggering individual scans one at a time. It is designed for high-volume scenarios: bulk onboarding events, periodic compliance audits, large-scale KYC runs, or vendor roster reviews.

When to Use Batch vs. Single Scans​

ScenarioRecommended Approach
Vetting a single candidate or partnerSingle scan via dashboard or API
Onboarding a new cohort of employeesBatch processing
Quarterly compliance rescan of active vendorsBatch processing
Real-time onboarding flow (one subject at a time)Single scan via API with webhook
Annual KYC review of customer portfolioBatch processing

How Batch Processing Works​

Batch jobs are submitted via the WeCheck API. Each job contains a list of subject records and returns results asynchronously via webhook as each subject is processed.

Submission flow:

  1. Construct your batch payload — an array of subject objects, each with a name and optional identifiers (public profile URLs, reference image URL)
  2. POST the payload to the batch endpoint
  3. WeCheck returns a batch_id immediately — processing begins in the background
  4. Results are delivered per subject via webhook as they complete (scan.completed event)
  5. Use the batch status endpoint to monitor overall progress if needed

Each subject in a batch is processed independently — a failure on one subject does not block or cancel the rest of the batch.

Credits & Budget Management​

Batch scans consume credits from the same pool as individual scans — one credit per subject (or per scan type, depending on your plan). For large batches, credit consumption can be significant.

Before submitting a large batch:

  • Check your available credit balance in Settings → Credits
  • If you are an Org Admin, verify that the workspace's credit threshold is set appropriately — a batch that exceeds the threshold will pause and generate a notification
  • For very large batches, consider submitting in segments to maintain visibility over credit consumption

See Credits & Billing for details on credit costs and thresholds.

Monitoring a Batch Run​

Via webhooks (recommended): Each completed subject triggers a scan.completed webhook event with the subject's result payload. This is the most efficient approach for real-time processing of results as they arrive.

Via the status endpoint: Poll GET /v1/batch/{batch_id}/status to check overall progress:

{
  "batch_id": "bat_abc123",
  "total": 250,
  "completed": 184,
  "failed": 3,
  "pending": 63,
  "status": "in_progress"
}

Via the dashboard: Active batch jobs appear in the Batch Processing section of the WeCheck dashboard with a live progress indicator.

Handling Partial Failures​

If a subject in a batch fails to process (e.g., insufficient data to perform a match, invalid input format), the job is marked as failed for that subject and processing continues for the rest of the batch. Failed subjects do not consume credits.

A scan.failed webhook event is delivered for each failed subject, including an error code and reason:

{
  "event_id": "evt_fail_99",
  "type": "scan.failed",
  "data": {
    "batch_id": "bat_abc123",
    "subject_ref": "your-internal-id-42",
    "error_code": "INSUFFICIENT_INPUT",
    "error_message": "At least one of: full name + public profile URL or reference image is required."
  }
}

Review failed subjects and resubmit them as individual scans with additional identifying information.

Best Practices​

  • Deduplicate before submitting — Remove duplicate subjects from your list before building the batch payload to avoid consuming credits on repeat checks
  • Set workspace credit thresholds — Org Admins should configure per-workspace thresholds before running large batches to prevent unexpected credit exhaustion. See Workspaces & Permissions.
  • Handle webhooks idempotently — Use the event_id field in each webhook payload to deduplicate deliveries in case of retries
  • Segment very large batches — For batches over 500 subjects, consider splitting into segments of 200–300 to maintain oversight and enable partial processing if something goes wrong
  • Review low-confidence results manually — After a batch run, filter results by confidence score and route low-confidence matches to a manual review queue before acting on them