List blocklist entries
The risk.blocklist.list operation: GET /api/v1/risk/blocklist in the REST API and the risk_blocklist_list tool in the MCP server.
/api/v1/risk/blocklistLists the brand's blocklist in the mode of the request, newest first: emails, card fingerprints (the
processor's), IP ranges and countries whose payments the risk rules refuse. Filter by kind, and by value
with it (an email in any case, a bare IP address for its /24). Paginate with limit (1–100, default 10) and
starting_after. Entries a rejected risk review added say so (source: review, evaluationId).
At a glance
- REST:
GET /api/v1/risk/blocklist - MCP tool:
risk_blocklist_list - Operation ID:
risk.blocklist.list - Scope: Brand
- Permission:
customers:read - Risk tier:
read - Dry run: Not supported
- Idempotency: Not needed (read only)
- Modes: Test and live
- Pagination:
limit(at most 100) andstarting_after - Authentication: API key with the
customers:readscope - Since: M9
Request
Query parameters
| Field | Type | Required | Description |
|---|---|---|---|
kind | one of email, card_fingerprint, ip_range, country | No | Entries of one kind. |
value | string | No | The entry for one value (with kind; written as you like). |
limit | integer (1 to 100) | No | |
starting_after | rbl_… ID | No | The next_cursor of the previous page. |
Response
200 OK with a JSON object, a page of the list (newest first):
| Field | Type | Description |
|---|---|---|
object | "list" | |
data | array of object | |
data[].id | rbl_… ID | |
data[].object | "risk_blocklist_entry" | |
data[].livemode | boolean | |
data[].brandId | brd_… ID | |
data[].kind | one of email, card_fingerprint, ip_range, country | |
data[].value | string | |
data[].reason | string or null | |
data[].source | one of operator, review | |
data[].evaluationId | rsk_… ID or null | |
data[].createdBy | string | |
data[].createdAt | date-time | |
has_more | boolean | |
next_cursor | rbl_… ID or null |
Examples
The blocked emails
GET /api/v1/risk/blocklist?kind=email
Authorization: Bearer or_test_…
Response (200):
{
"object": "list",
"data": [
{
"id": "rbl_01m4ttwd3veh9apbewxheq5xr2",
"object": "risk_blocklist_entry",
"livemode": true,
"brandId": "brd_01m4ttwd3veh9apbewxheq5xh5",
"kind": "email",
"value": "card.tester@example.com",
"reason": "Tried six cards in ten minutes",
"source": "operator",
"evaluationId": null,
"createdBy": "usr_01m4ttwd3veh9apbewxheq5xh6",
"createdAt": "2026-10-20T09:00:00.000Z"
}
],
"has_more": false,
"next_cursor": null
}
Is this card blocked?
GET /api/v1/risk/blocklist?kind=card_fingerprint&value=Xo1abC9dEf2GhI3j
Authorization: Bearer or_test_…
Response (200):
{
"object": "list",
"data": [
{
"id": "rbl_01m4ttwd3veh9apbewxheq5xr3",
"object": "risk_blocklist_entry",
"livemode": true,
"brandId": "brd_01m4ttwd3veh9apbewxheq5xh5",
"kind": "card_fingerprint",
"value": "Xo1abC9dEf2GhI3j",
"reason": "Risk review rsk_01m4ttwd3veh9apbewxheq5xr1 rejected: The cardholder doesn't know the customer.",
"source": "review",
"evaluationId": "rsk_01m4ttwd3veh9apbewxheq5xr1",
"createdBy": "usr_01m4ttwd3veh9apbewxheq5xh6",
"createdAt": "2026-10-20T09:00:00.000Z"
}
],
"has_more": false,
"next_cursor": null
}
Errors
| Code | HTTP status | When | What to do |
|---|---|---|---|
validation_failed | 400 | A filter or pagination value is invalid. | Fix the fields listed in details.issues and send the request again. |
permission_denied | 403 | You can't see this brand's customers. | Ask an organization owner or admin for a role or scope that allows this action. |
It can also return these common errors: api_version_unsupported, authentication_required, api_key_invalid, scope_required, resource_not_found, dry_run_not_supported, rate_limited, internal_error.