Lista di blocco

La lista di blocco è la stessa di Impostazioni → Prevenzione delle frodi nella dashboard (vedi Lista di blocco e rilevamento dei duplicati). Una verifica che corrisponde a una voce attiva viene rifiutata oppure inviata a revisione manuale. Le voci sono riservate alla Sua organizzazione.

Gli endpoint si trovano sotto /api/v1/kyc/blocklist e usano una chiave API (Authorization: Bearer ck_live_…) con l'ambito kyc:manage. Vedi Autenticazione.

I valori bloccati non vengono mai restituiti: l'API restituisce il tipo di voce, un suggerimento mascherato (un indirizzo IP o un intervallo viene restituito per intero), l'azione, il motivo, la scadenza e i contatori delle corrispondenze.

Aggiungere voci

POST /api/v1/kyc/blocklist

Blocchi un valore tipizzato:

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

Oppure blocchi ciò che una verifica esistente contiene:

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

fromRequestId deve essere una verifica della Sua organizzazione. kinds limita ciò che viene bloccato (predefinito: tutto ciò che la verifica contiene — volto, numero/i di documento, telefono, email, indirizzo IP, dispositivo). I tipi per cui la verifica non ha dati vengono saltati.

Risposta 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"
    }
  ]
}

Errori: 400 per un valore non utilizzabile o per una verifica senza nulla da bloccare, 404 quando fromRequestId non appartiene alla Sua organizzazione, 409 quando esiste già una voce attiva identica.

Elencare le voci

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

Restituisce { "data": [ … ], "total": 12 }. Le voci scadute sono nascoste, a meno che non si usi includeExpired=true. pageSize può arrivare al massimo a 200.

Rimuovere una voce

DELETE /api/v1/kyc/blocklist/:id → { "success": true }. La rimozione di una voce che non appartiene alla Sua organizzazione restituisce 404.

Ogni aggiunta e rimozione viene registrata nel registro di audit, con la chiave API come attore.

Leggere il risultato

Una verifica che corrisponde riporta una voce blocklist_match nei suoi segnali di frode (GET /api/v1/kyc/requests/:id/fraud-signals), con details.kind (il tipo) e details.action, mai il valore. I suoi trigger di revisione o le sue cause di squalifica contengono blocklist_match, e le regole di politiche e workflow possono verificare fraud.blocklistMatch e fraud.blocklistKinds.