Blocklist API

The blocklist is the same list as Settings → Fraud prevention in the dashboard (see Blocklist and duplicate detection). A verification that matches an active entry is rejected or sent to manual review. Entries are private to your organization.

Endpoints live under /api/v1/kyc/blocklist and use an API key (Authorization: Bearer ck_live_…) with the scope kyc:manage. See Authentication.

Blocked values are never returned: the API gives back the entry type, a masked hint (an IP address or range is returned in full), the action, reason, expiry and match counters.

Add entries

POST /api/v1/kyc/blocklist

Block a typed value:

{
  "kind": "email",
  "value": "fraud@example.com",
  "action": "reject",
  "reason": "Chargeback ring",
  "expiresAt": "2027-01-01T00:00:00.000Z"
}

Or block what an existing verification carries:

{
  "fromRequestId": "clx…",
  "kinds": ["face", "device", "ip"],
  "action": "escalate"
}

fromRequestId must be a verification of your organization. kinds limits what is blocked (default: everything the verification has: face, document number(s), phone, email, IP address, device). Kinds the verification has no data for are skipped.

Response 201:

{
  "data": [
    {
      "id": "clx…",
      "kind": "email",
      "valueHint": "f•••@e•••.com",
      "action": "reject",
      "reason": "Chargeback ring",
      "createdByName": null,
      "sourceRequestId": null,
      "expiresAt": "2027-01-01T00:00:00.000Z",
      "expired": false,
      "matchCount": 0,
      "lastMatchedAt": null,
      "createdAt": "2026-10-24T15:00:00.000Z"
    }
  ]
}

Errors: 400 for an unusable value or a verification with nothing to block, 404 when fromRequestId isn't yours, 409 when an identical active entry already exists.

List entries

GET /api/v1/kyc/blocklist?kind=email&includeExpired=false&page=1&pageSize=50

Returns { "data": [ … ], "total": 12 }. Expired entries are hidden unless includeExpired=true. pageSize is at most 200.

Remove an entry

DELETE /api/v1/kyc/blocklist/:id → { "success": true }. Removing an entry that isn't yours returns 404.

Every add and removal is recorded in the audit log with the API key as the actor.

Reading the result

A verification that matches carries a blocklist_match entry in its fraud signals (GET /api/v1/kyc/requests/:id/fraud-signals), with details.kind (the type) and details.action, never the value. Its review triggers or disqualifiers contain blocklist_match, and policy and workflow rules can test fraud.blocklistMatch and fraud.blocklistKinds.