> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clausum.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Blocklists

> Dynamic deny and flag lists for pay-in and payout assess

Blocklists are organization-scoped lists that influence every assessment. When a transaction matches an active entry, Clausum adds a signal or hard-declines with `decision: "decline"`.

## Entry types (pay-in)

| `list_type`          | Matches against                   |
| -------------------- | --------------------------------- |
| `email`              | Exact email address               |
| `email_domain`       | Email domain (e.g. `example.com`) |
| `ip_address`         | Single IP                         |
| `ip_range`           | CIDR range                        |
| `device_fingerprint` | Device fingerprint                |
| `card_bin`           | First 6 digits of the card        |
| `card_hash`          | Hashed card number                |
| `country`            | ISO country code                  |
| `phone`              | Phone number                      |
| `customer_id`        | Your internal customer id         |

## Payout-specific types

For [payout assess](/guides/payout-assessment), add entries with payout scope:

| `list_type`      | Matches against                    |
| ---------------- | ---------------------------------- |
| `clabe`          | Mexican CLABE                      |
| `iban`           | IBAN                               |
| `account_hash`   | Hashed account number              |
| `swift_bic`      | SWIFT / BIC                        |
| `beneficiary_id` | Your stable beneficiary identifier |

Shared types (`email`, `ip_address`, `country`, `customer_id`) can apply to both flows when configured correctly.

## Flow scope

Each entry has **`flow_scope`**:

| Value    | Applies during               |
| -------- | ---------------------------- |
| `payin`  | Checkout / card capture only |
| `payout` | Disbursements only           |
| `all`    | Both pay-in and payout       |

Configure scope in **Dashboard → Protección → Blocklists** when creating or editing an entry. Payout assess ignores payin-only entries and vice versa.

## Severity

| Severity | Effect on assessment                   |
| -------- | -------------------------------------- |
| `block`  | Hard decline (`risk_score` = 100)      |
| `flag`   | Adds significant weight                |
| `review` | Adds moderate weight, routes to review |

## Managing entries

Blocklist CRUD uses a **dashboard session JWT** (signed-in user), not partner API keys.

<CodeGroup>
  ```bash Add entry theme={null}
  curl -X POST "$CLAUSUM_API_BASE/api/v1/blocklists" \
    -H "Authorization: Bearer $DASHBOARD_JWT" \
    -H "Content-Type: application/json" \
    -d '{
      "list_type": "clabe",
      "value": "012180001234567890",
      "severity": "block",
      "flow_scope": "payout",
      "reason": "Confirmed mule account"
    }'
  ```

  ```bash List entries theme={null}
  curl "$CLAUSUM_API_BASE/api/v1/blocklists?list_type=email&severity=block" \
    -H "Authorization: Bearer $DASHBOARD_JWT"
  ```

  ```bash Deactivate entry theme={null}
  curl -X PATCH "$CLAUSUM_API_BASE/api/v1/blocklists" \
    -H "Authorization: Bearer $DASHBOARD_JWT" \
    -H "Content-Type: application/json" \
    -d '{ "id": "8f3c...e21", "is_active": false }'
  ```
</CodeGroup>

<Note>
  Adding entries requires `admin`, `analyst`, or `compliance_officer`. Deleting entries requires `admin`.
</Note>

## Automatic population

When you call [`report-fraud`](/guides/report-fraud), Clausum auto-blocklists the email (`block`), card BIN (`flag`), and IP (`block`) — tagged `source: "fraud_report"` and linked to the case.

## Expiring entries

Set `expires_at` for temporary blocks (e.g. 24-hour velocity ban):

```json theme={null}
{
  "list_type": "ip_address",
  "value": "201.150.10.22",
  "severity": "block",
  "flow_scope": "all",
  "reason": "Card-testing burst",
  "expires_at": "2026-06-01T00:00:00Z"
}
```

## Normalization

Values are normalized on write: emails lowercased, countries uppercased. Duplicates (same org + type + value + scope) return **409 Conflict**.