Developer documentation
Integrate sanctions and PEP screening into your customer review workflow. Read the public API contract, test request handling in the sandbox, then evaluate live source coverage and record review decisions.
screening:write and screening:read, then create the key.Authorization: Bearer (or X-API-Key).A cc_test_ key returns simulated sandbox results. Use it to check your integration with fictional data; it does not test live source coverage or consume live screening quota. Keep API keys out of browser code.
curl https://api.circlescheck.com/api/v1/screenings \
-H 'Authorization: Bearer cc_test_your_api_key' \
-H 'Content-Type: application/json' \
-d '{"fullName":"Alex Sample","type":"individual","dateOfBirth":"1980-01-15","country":"GB","screeningType":"combined"}'When you are ready to evaluate real results, create a separate key with the Live (cc_live_*) environment in Settings → API Keys. Inspect the source inventory, compare representative cases, and review the returned evidence. The screening endpoint returns potential sanctions and PEP matches; identity-document verification is a separate workflow.
The free evaluation includes 50 live screenings per month. Successful live API checks share that allowance with manual and CSV screening. Free evaluation does not include recurring monitoring. Creating an account does not start a paid subscription.
For ongoing production work, Starter is $79.99 USD/month, billed monthly, with 1,000 screenings per month and recurring customer monitoring. Successful recurring scans use the same screening allowance.
Review the selected plan, billing interval and current price before confirming payment in checkout.
This fictional sandbox example illustrates the response envelope. Read matches from result.matches. A match is a candidate for human review; a similarity score is not the probability that the person is sanctioned. No matches is a point-in-time result for the queried scope, not a compliance guarantee.
{
"id": "00000000-0000-4000-8000-000000000001",
"status": "completed",
"query": {
"fullName": "Alex Example",
"type": "individual",
"screeningType": "combined"
},
"result": {
"riskLevel": "low",
"riskScore": 0,
"matchCount": 0,
"matches": []
},
"isTestMode": true,
"processingTimeMs": 0
}Live results include source evidence when available. Compare names, aliases, birth dates, identifiers, and jurisdictions; retain reviewer notes and source timestamps. Identity-field conflicts remain visible for review. An unavailable engine returns an error, never a clean screening result.
Paths below are relative to https://api.circlescheck.com/api/v1.
JSON: fullName, type (individual or business), optional dateOfBirth, country, nationality, screeningType, customerId. A linked customer must belong to your organization and match the queried identity. name is accepted as an alias for fullName. Returns a screening UUID and result.matches.
Retrieve the saved query, result, engine/source evidence, status, and recorded reviews.
JSON: disposition (true_positive, false_positive, under_review, dismissed), required reviewNotes explaining the decision. Use the returned match UUID, not entityId.
Download the saved screening and reviewer evidence as application/pdf. Failed screenings cannot be exported as clean reports.
multipart/form-data with a file field. CSV columns: customer_ref, name, type, date_of_birth, country. customer_ref is optional for screening and required to save a portfolio; keep it stable and unique in your organization. Maximum 1,000 rows; successful saved checks count toward your plan.
JSON: saveToPortfolio: true, optional screeningIds and customerRefs. Explicitly save selected completed live rows as customers and link their checks. Return per-row outcomes; repeated saves do not re-screen or charge again. Conflicting identities must be resolved.
JSON: confirmRecurring: true, frequency (daily or weekly), optional customerIds. Requires a current paid subscription and previously saved batch customers. New entries use the completed batch check as their starting record; existing entries retain their cadence and paused state. Subsequent successful scans use allowance.
Retrieve completed checks linked to this customer, saved review decisions, and monitoring state. Paginate with limit and offset. Prior decisions provide context; they do not automatically resolve a new candidate.
JSON: fullName, entityType (individual or business), optional dateOfBirth, country, customerId, frequency (daily or weekly). Recurring screening requires a paid plan; free evaluation is limited.
List changes flagged for review. Repeated unchanged results do not create new alerts.
JSON: url and events. Save the signing secret returned when creating the webhook; validate subsequent request signatures.
| HTTP status | Next action |
|---|---|
| 400 | Correct the payload or CSV rows before retrying. |
| 401 | Check API key validity and environment. |
| 402 | Your monthly allowance is exhausted or this action requires a current paid subscription. Review the upgradeUrl; saved customers remain available. |
| 403 | Check your role or the plan required for the workflow. |
| 404 | Confirm the record exists in your organization. |
| 409 | Complete the screening before exporting evidence, or resolve the conflicting record state. |
| 429 | Check the usage limit or Retry-After header. Upgrade or wait; do not retry in a tight loop. |
| 503 | The screening service is unavailable. Treat the check as incomplete and retry with backoff. |
Each successfully saved live entity screening counts once, including CSV rows and recurring monitoring checks. Failed checks release their quota reservation. Published plans cap included usage; an upgrade requires an explicit checkout. Review current plan limits.
Hash the exact raw request body with the webhook secret using HMAC-SHA256. Compare it with X-CirclesCheck-Signature, formatted as sha256=<hex digest>, using a constant-time comparison. Reject invalid signatures. Deduplicate deliveries using X-CirclesCheck-Delivery; return a successful HTTP status only after saving the event.
Event names include screening.completed and case.created. Avoid assuming a successful delivery means a candidate has been reviewed.
All paths require an API key or an authenticated organization session. Access varies by role and plan. The downloadable OpenAPI file contains detailed request contracts for the core workflow above and an index of the remaining public operations.
Technical examples reviewed against the application contract on October 1, 2026. Coverage and matching quality should be evaluated on your own representative cases.
Get help evaluating your integration