# Block and allow lists

Block or allow an email, phone, IP address or CIDR range, device (`installation`), your user ID (`vendor_data`) or document country. A blocked value declines a verification that presents it (`LIST_BLOCK`; a workflow can send it to review instead); an allowed value skips the velocity, IP-country and risky-contact holds. The same lists are on the dashboard's Blocklist page, with CSV import and export.

```shell
curl -X POST https://api-verify.secuveri.com/v1/lists \
  -H "x-api-key: $SECUVERI_API_KEY" \
  -H "content-type: application/json" \
  -d '{"kind":"block","type":"email","value":"fraud@example.com","reason":"chargeback","expires_at":"2027-06-30T00:00:00Z"}'
```

Values are normalized first: emails lower-cased, phones written as E.164, IPs and ranges normalized, countries upper-cased. Emails, phones, devices and user IDs are kept only as a keyed fingerprint, so `GET /v1/lists` answers with a masked `hint`, never the value. `POST /v1/lists/bulk` takes up to 1000 entries as `{"entries": [...]}` and reports each one as `created`, `reactivated`, `exists`, `duplicate` or `invalid`. Re-adding an expired entry reactivates it with the requested expiry; an active entry stays unchanged. The response includes a separate `reactivated` count; `DELETE /v1/lists/{id}` removes one. Reading needs the `lists:read` scope, changing `lists:write`; keys made before scopes existed may do both. Every change is in the audit log.

| Status | Meaning |
| --- | --- |
| 200 / 201 | Already listed (the existing entry) / added |
| 400 | Invalid value, or an expiry that is not in the future |
| 401 | Missing or unknown API key |
| 403 | The key lacks lists:read or lists:write, or its IP allowlist refuses the caller |
| 404 | No such entry (DELETE) |
| 429 | More than 300 list calls in a minute |

To block a rejected person automatically, turn on Block on reject in the workflow's Identity Document step: when a reviewer rejects a verification, its email, phone, device and `vendor_data` are added to the blocklist.