CirclesCheck · CSV batch screening
A customer list.
A review for every row.
Screen a CSV of individuals and businesses, inspect the rows that need attention, and keep the saved evidence for each completed check.
Three fictional records. No customer data or screening results are included.
Follow the list through review, evidence, and its next check →01 · Prepare the list
Start with the fields you know.
Use the header below. Name is required; a birth date and country help the reviewer compare identities. Use individual or business as the type. A business does not need a birth date. Include a stable customer_ref to save completed live checks to your customer portfolio; keep that reference for future uploads.
| customer_ref | name | type | date_of_birth | country |
|---|---|---|---|---|
| sample-customer-001 | Alex Sample | individual | 1980-01-15 | GB |
| sample-customer-002 | Sam Sample | individual | 1992-06-20 | GB |
| sample-customer-003 | Sample Payments Ltd | business | — | GB |
Before uploading
Keep dates in YYYY-MM-DD format and use consistent country values, such as GB. Remove accidental duplicate rows; each successfully saved live check uses the allowance.
File limits
Upload a .csv file with 1–1,000 data rows and a maximum size of 5 MB. Start with a small representative list before expanding to your portfolio.
02 · Test the integration
Upload the file. Keep the row results.
The batch API accepts a multipart file field. Replace the placeholder with a sandbox key from your account. Sandbox output is simulated; it does not establish live source coverage or consume live screening quota.
curl https://api.circlescheck.com/api/v1/screenings/batch \
-H 'Authorization: Bearer cc_test_your_api_key' \
-F 'file=@sample-screening-batch.csv'Batch screening uses the combined sanctions and PEP workflow. Keep API keys on your server. When your team is ready to evaluate live data, use a live key and review the recorded source inventory.
Read the public batch API contract →03 · Resolve the unfinished work
A partial batch still needs attention.
A successful HTTP response can contain failed rows. Check the batch status and every item in results. A completed row with no candidates is a point-in-time screening result; a failed row has no completed result.
Illustrative response to the optional error-example CSV; not a live result.
{
"status": "partial",
"totalRows": 3,
"totalScreened": 1,
"results": [
{
"row": 1,
"name": "Alex Sample",
"status": "completed",
"screeningId": "00000000-0000-4000-8000-000000000001",
"matchCount": 0
},
{
"row": 2,
"name": "",
"status": "failed",
"error": "A name between 1 and 500 characters is required"
},
{
"row": 3,
"name": "Sam Sample",
"status": "failed",
"error": "Birth date must be a valid YYYY-MM-DD date"
}
]
}Completed rows
Open the returned screening UUID to inspect candidate evidence and record reviewer decisions. Successfully saved live rows count once toward the monthly allowance.
Invalid or unavailable rows
Correct invalid names, types, or dates. Retry unavailable rows with backoff, preferably in a smaller batch. Failed rows are not charged; avoid rerunning completed rows unnecessarily.
Keep the batch reference
Save the batch ID, input file, row results, and screening IDs together so you can identify exactly what still needs review.
Keep the list under review.
Select completed live rows and save them to your customer portfolio using stable references. Then explicitly choose daily or weekly monitoring on a paid plan. Saving customers does not re-run the completed checks or enroll them automatically.
The completed batch check becomes the starting record for new monitoring entries. Existing entries keep their cadence and paused state. Open the customer's history to retrieve earlier decisions; new findings still need their own review.
Plan recurring customer monitoring →An illustrative first month
100 + 400 = 500
100 initial screenings plus four monitoring scans of the same 100 customers uses 500 successful screenings. Add new onboarding checks and other screening activity to that budget.
See the evidence your team can export →Evaluate the batch with your team.
Test the request shape in sandbox, then assess live matching against your representative cases. Paid plans add recurring monitoring within their screening allowance.
Prepared by CirclesCheck · Updated . Product evaluation guidance; independent regulatory review is not claimed.