Skip to main content
Batch scoring is the high-volume flavor of Qscore: instead of requesting one credit report at a time, you submit a batch of subjects (Chilean RUTs today) and CBPay generates a full Qscore report for each one asynchronously. When the batch finishes you receive one webhook and one email with the counters — never one notification per subject. Use it to re-score an existing portfolio (monthly refresh of your debtors), to run a one-time due-diligence sweep over a list of suppliers, or to backfill scores after onboarding a new book of business. For one-off checks on a single subject, keep using the individual report.

​
How it works

The batch is accepted immediately (202) and processed by a background worker. Each item goes through the same pipeline as an individual report — including the on-demand bureau fetch — so a batch score is identical to the score you would get one by one, with the same deterministic model (1–999, bands A–E, SC when the subject has no data).

​
Step by step

1

Create the batch

Send POST /v1/qscore/batches with the subjects as a JSON array or as CSV text (subjects_csv). Every request needs an idempotency_key: a replay with the same key returns the original batch with idempotency_hit: true and never duplicates the batch or its charges.Invalid rows are rejected at creation time and reported in rejected_items — the batch only processes the valid ones. A doc_id that fails the country check digit yields invalid_doc_id; the same doc_id twice inside one batch yields duplicate_in_batch (reported with its normalized form). An unrecognized subject_type is not an error: the row is accepted and the type is inferred as described below.
The estimate above assumes a configured fee of 4.00 USDT per person report and 2.50 USDT per company report: 3 × 4.00 + 1 × 2.50 = 14.50. Your estimate reflects the fees configured for your account.
An idempotent replay returns 200 (not 202) with the original batch and idempotency_hit: true; the rejected_items / rejected_count detail is only included in the original creation response.
2

Wait for the completion signal

The worker processes items one by one. You do not need to poll: when the batch reaches a final state you get exactly one risk_batch_completed webhook and one completion email with the counters and a link to your account.Reports inside a batch never emit the individual risk_report_ready webhook or per-report emails — the batch is the signal. If you still want to poll, GET /v1/qscore/batches/{id} returns the live counters (processed_items, succeeded_items, failed_items).
3

Read the results

Per-item results are available as JSON (paginated) or as a CSV export ready for Excel.
For a failed item, score is null and the row carries error_code / error_message instead:
The CSV export (GET /v1/qscore/batches/{id}/results.csv) streams every row with a UTF-8 BOM so Excel opens it correctly, and includes the public verify_code of each report. Every cell is sanitized against CSV formula injection. You can download it at any time, including while the batch is still processing — rows for items still pending have empty score/band/verify_code fields:
Visible CSV headers follow the account locale; the example above shows the raw cell keys.Each report_id is a full individual report: you can download its PDF with the standard report download endpoint, and anyone can verify its authenticity at https://business.cbpayapp.com/verify/qscore/{verify_code}.

​
List and search your batches

GET /v1/qscore/batches returns your batches paginated, with optional from/to date filters (YYYY-MM-DD, organization timezone, both inclusive — an invalid date yields 400 invalid_range):
Pagination is page + page_size (default 50, maximum 200).

​
Batch and item statuses

Batch (GET /v1/qscore/batches/{id}): Item (GET /v1/qscore/batches/{id}/items):

​
Billing

Each item charges the standalone fee configured for your account (risk_report_person or risk_report_company) when the worker processes it. estimated_fee_usdt in the creation response is the upfront estimate for the valid items.
  • Idempotent charges: every item is charged with a deterministic billing reference derived from the batch and the item, so a worker restart never double-charges an item.
  • Automatic refunds: an item that ends failed gets its fee refunded in the same run. You only pay for reports that were actually generated.
  • Charges and refunds appear in your statement like any other Qscore fee.

​
Errors

​
Webhook: risk_batch_completed

Exactly one webhook per batch, delivered to the subscriptions of the owning account when the batch reaches a final state. Subscribe with event type risk_batch_completed (see webhooks). The event type travels in the X-Webhook-Event header and the body is the flat payload:
The webhook carries counters only — never scores or documents. Fetch the results with GET /v1/qscore/batches/{id}/items or the CSV export. The completion email follows the same data-minimization rule: counters and a link, nothing else.

​
FAQ

It depends on the size and on how fresh the bureau data is for each subject. Each item is a full report (including the on-demand bureau fetch), so plan for a few seconds per item; a 1,000-subject batch typically finishes in well under an hour. You do not need to wait online — the webhook tells you when it is done.
No. The worker runs the exact same pipeline as an individual report, with the same deterministic model version. Scoring the same subject individually or inside a batch yields the same result at the same point in time.
Split it into several batches of up to 5,000 each, with a distinct idempotency_key per batch. Batches are processed independently and each sends its own completion webhook.
Yes. Declare subject_type per row or let the API infer it from the Chilean RUT series. Each item is billed with the fee that matches its type.
Processing is crash-safe: the worker resumes the batch where it left off, and the deterministic billing reference guarantees an item is never charged twice.
Not in this version. A batch that is already processing runs to completion; items that fail are refunded automatically.
Only your account — any other account gets 404 not_found. Batches are never visible across organizations. The individual reports generated by a batch are regular Qscore reports, so they show up in the same places as any other report (including your organization’s admin view of reports).
Last modified on August 18, 2026