Richieste KYC

Una richiesta KYC rappresenta un singolo tentativo di verificare l'identità di una persona (INDIVIDUAL) oppure l'identità di un'azienda insieme ai suoi amministratori e titolari effettivi (BUSINESS). Ogni endpoint qui sotto si trova sotto /api/v1/kyc/requests.

Tutti gli endpoint richiedono una chiave API con l'ambito pertinente. Vedi Autenticazione.

Crea una richiesta

POST /api/v1/kyc/requests    Ambito: kyc:write

Crea una nuova richiesta nello stato PENDING_UPLOAD. I dati del richiedente sono facoltativi: se non vengono passati, sarà il richiedente a inserirli tramite la sessione ospitata.

Corpo della richiesta

{
  "type": "INDIVIDUAL",
  "purpose": "Financing an iPhone 16, 24 months",
  "externalRef": "your-id-here",
  "subTenantName": "Acme Corp",
  "subTenantExternalId": "cust_8842",
  "applicant": {
    "externalRef": "your-applicant-id",
    "fullName": "Jane Doe",
    "dateOfBirth": "1990-04-12",
    "nationality": "US",
    "email": "jane@example.com",
    "phone": "+14155551234",
    "emailVerified": false,
    "phoneVerified": false,
    "metadata": { "anyKey": "anyValue" }
  }
}

Motivo della verifica

Ogni richiesta ha un motivo: perché si verifica la persona, in poche parole. Inviarlo è facoltativo, ma si consiglia un motivo preciso perché rende utile il controllo antifrode. Certivant legge il motivo e lo associa a una delle circa 110 voci di un elenco di motivi — ad esempio finanziamento di un telefono o dispositivo, piano mobile, attivazione di una SIM, prestito personale, carta di credito, noleggio auto, criptovalute, conto bancario, affitto di una casa, mutuo, firma dal notaio / atto, assicurazione, lavoro o verifica dell'età. Ogni motivo appartiene a una famiglia: Telefoni e dispositivi, Linee mobili e SIM, Prestiti e credito, Veicoli, Beni di alto valore, Movimenti di denaro e criptovalute, Apertura di conti, Affitto di una casa, Immobili e mutuo, Altro (nessun denaro in gioco) o Non chiaro.

• Si confronta solo la famiglia. La rete di prevenzione delle frodi confronta tra aziende la famiglia — mai il testo, mai il motivo specifico. Il testo stesso è memorizzato in forma cifrata, non viene mai condiviso con un'altra azienda e viaggia solo tramite HTTPS.
• Conta solo ciò che mette a rischio denaro o credito. Una richiesta entra nei modelli di frode solo se sono in gioco denaro o credito. Una firma dal notaio, un mutuo, un'assicurazione, le utenze, un impiego o le cure mediche vengono registrati ma non contano mai: chi firma un atto dal notaio e un mese dopo finanzia un telefono non viene segnalato.
• I motivi sensibili non vengono mai condivisi. Salute, questioni legali, immigrazione, gioco d'azzardo, difficoltà con i debiti, incontri, religione o donazioni, decesso o successione e beni soggetti a limiti di età sono memorizzati come «Altro».
• Sia concreto. Un motivo come KYC o verification non dice cosa sta acquistando la persona. Per impostazione predefinita la richiesta viene comunque creata, con un avviso. Se la Sua organizzazione ha attivato Rifiuta i motivi vaghi (Impostazioni → Prevenzione delle frodi → Regole della rete antifrode), viene invece rifiutata con 422.
• Non inserisca dati personali. Indirizzi e-mail, numeri di telefono, di carta e di documento e date vengono rimossi prima che un'IA legga il motivo — non li scriva.

La risposta di creazione indica come è stato interpretato il motivo:

Gli stessi campi sono restituiti da POST /api/v1/kyc/forms/:formId/send. Per un quadro completo, consulti Rete antifrode.

Il motivo viene scelto in quest'ordine: il purpose che invia, poi la motivazione predefinita del modulo (si imposta nell'editor dei moduli), poi «New customer verification», sempre memorizzato in inglese con esattamente questo testo. Le integrazioni che non inviano alcun motivo, come i plugin di firma elettronica, non ricevono quindi mai un errore. La motivazione predefinita non viene mai rifiutata (nemmeno con Rifiuta i motivi vaghi), non genera alcun avviso e non comporta denaro a rischio, quindi non alimenta gli schemi della rete antifrode.

Risposta (201)

{
  "id": "req_01J...",
  "status": "PENDING_UPLOAD",
  "type": "INDIVIDUAL",
  "externalRef": "your-id-here",
  "subTenantName": "Acme Corp",
  "subTenantExternalId": "cust_8842",
  "pendingDocTypes": ["GOVERNMENT_ID", "SELFIE"],
  "purposeQuality": "informative",
  "applicant": { ... },
  "createdAt": "2026-05-27T10:00:00.000Z"
}

pendingDocTypes riflette le impostazioni KYC della Sua organizzazione: ciò che è richiesto dipende dall'attivazione del controllo di vivacità, della prova di residenza, ecc.

purposeQuality vale informative, generic o unusable. Quando il motivo richiede la Sua attenzione, viene aggiunto un array warnings con purpose_too_generic, purpose_unusable e/o purpose_contains_personal_data.

Errori

• 400 VALIDATION_ERROR — il corpo non ha superato la validazione Zod. error.fields elenca ogni percorso non valido.
• 403 FORBIDDEN — la chiave non ha kyc:write, oppure (error.reason = "form_not_allowed") la chiave è limitata a moduli specifici e la richiesta non ha formId oppure ne indica un altro.
• 404 NOT_FOUND — formId non è un modulo della Sua organizzazione.
• 409 CONFLICT — il Suo externalRef è già usato da un'altra richiesta di questa organizzazione. Usi un riferimento diverso oppure cerchi la richiesta esistente.
• 422 — la Sua organizzazione rifiuta i motivi vaghi (Rifiuta i motivi vaghi) e purpose è troppo generico o inutilizzabile. Indichi cosa viene acquistato o finanziato. Restituito anche da POST /api/v1/kyc/forms/:formId/send.

Elenca le richieste

GET /api/v1/kyc/requests    Ambito: kyc:read

Parametri di query

Risposta

{
  "data": [
    { "id": "req_...", "status": "APPROVED", "type": "INDIVIDUAL", "createdAt": "...", "applicant": {...} },
    ...
  ],
  "pagination": {
    "total": 248,
    "page": 1,
    "limit": 20,
    "pages": 13
  }
}

Ottieni una singola richiesta

GET /api/v1/kyc/requests/:id    Ambito: kyc:read

Restituisce la verifica completa — il richiedente, ogni documento caricato (con i campi estratti tramite OCR), ogni controllo automatico, il dettaglio completo del rischio, i segnali di frode e il registro di audit. È tutto ciò che mostra la schermata di dettaglio della dashboard, quindi può costruire una Sua interfaccia di revisione senza mai far accedere il personale a Certivant.

Risposta

{
  "id": "req_...",
  "status": "ESCALATED",
  "type": "INDIVIDUAL",
  "externalRef": "user-9281",
  "subTenantName": null,
  "subTenantExternalId": null,
  "reviewedBy": null,
  "reviewNote": null,
  "completedAt": null,
  "createdAt": "2026-05-27T10:00:00.000Z",
  "updatedAt": "2026-05-27T10:03:12.000Z",

  "applicant": {
    "id": "app_...",
    "fullName": "Alex Singh",
    "dateOfBirth": "1988-11-03T00:00:00.000Z",
    "nationality": "GBR",
    "email": "alex@example.com",
    "emailVerified": true,
    "phone": "+447700900100",
    "phoneVerified": false,
    "metadata": {}
  },

  "documents": [
    {
      "id": "doc_...",
      "documentType": "id_card",
      "side": "front",
      "status": "done",
      "mimeType": "image/jpeg",
      "fileSize": 412938,
      "parsedData": {
        "fullName": "Alex Singh",
        "dateOfBirth": "1988-11-03",
        "documentNumber": "D1234567",
        "expiryDate": "2030-01-15",
        "nationality": "GBR",
        "issuingCountry": "GBR",
        "address": "12 High St, London"
      },
      "createdAt": "2026-05-27T10:01:00.000Z"
    }
  ],

  "checks": [
    { "id": "chk_1", "checkType": "ocr",        "provider": "aws_textract", "status": "passed", "score": 0.95, "startedAt": "...", "finishedAt": "..." },
    { "id": "chk_2", "checkType": "face_match", "provider": "azure_face",   "status": "passed", "score": 0.88 },
    { "id": "chk_3", "checkType": "liveness",   "provider": "azure_face",   "status": "passed", "score": 0.92 },
    { "id": "chk_4", "checkType": "sanctions",  "provider": "ofac",         "status": "failed", "score": 0.0 }
  ],

  "riskScore": {
    "overallScore": 62,
    "decision": "escalate",
    "autoDecision": true,
    "factors": [
      { "factor": "document_authenticity", "impact": 1.0, "description": "Barcode + metadata valid" }
    ],
    "rejectionReasons": [],
    "verdictMeta": {
      "factorVerdicts": [
        { "id": "1.1", "section": "Identity Document", "label": "Document authenticity", "weight": 15, "state": "pass", "evidence": ["barcode_valid"] },
        { "id": "4.2", "section": "Screening",         "label": "Sanctions / PEP",       "weight": 20, "state": "fail", "evidence": ["ofac_possible_match"] }
      ],
      "disqualifiers": [],
      "reviewTriggers": ["sanctions_possible_match"],
      "effectiveThresholdApprove": 80
    }
  },

  "fraudSignals": [
    { "signalType": "device_reuse", "severity": "low", "details": { "matchedFingerprint": "..." } }
  ],

  "auditLogs": [
    { "id": "log_1", "actorType": "api",    "actorId": "kyk_prod_ab",  "eventType": "request.created",   "payload": {}, "createdAt": "..." },
    { "id": "log_2", "actorType": "system", "actorId": "orchestrator", "eventType": "request.escalated", "payload": { "reason": "sanctions" }, "createdAt": "..." }
  ]
}

Riferimento dei campi

Errori

• 404 NOT_FOUND — nessuna richiesta con quell'ID in questa organizzazione. Le richieste appartengono alle organizzazioni: non può leggere i dati di un'altra organizzazione nemmeno con una chiave valida.

Mostrare una verifica nella propria app

La risposta di dettaglio è pensata per essere visualizzata direttamente — una sola chiamata fornisce tutto ciò che mostra la dashboard, così i Suoi revisori non devono mai accedere a Certivant:

Invia per l'elaborazione

POST /api/v1/kyc/requests/:id/submit    Ambito: kyc:submit

Immette una richiesta PENDING_UPLOAD nella pipeline di elaborazione automatica. La richiesta deve avere tutti i documenti obbligatori caricati (pendingDocTypes è vuoto) prima di poter essere inviata.

Risposta

{
  "id": "req_...",
  "status": "PROCESSING",
  "message": "Request submitted; you will receive a webhook when processing completes."
}

Errori

• 400 BAD_REQUEST — pendingDocTypes non è vuoto. Carichi prima i documenti mancanti.
• 409 CONFLICT — la richiesta non è in PENDING_UPLOAD. È possibile inviarla una sola volta.

Decisione manuale (richieste inoltrate)

POST /api/v1/kyc/requests/:id/decision    Ambito: kyc:manage

Sovrascrive una richiesta ESCALATED con una decisione umana. Questo endpoint è pensato per gli strumenti interni — la maggior parte delle decisioni viene presa tramite la dashboard.

Corpo della richiesta

{ "decision": "APPROVED", "note": "Confirmed identity against internal CRM record" }

Risposta

{ "id": "req_...", "status": "APPROVED", "decision": "APPROVED", "reviewNote": "..." }

Errori

• 409 CONFLICT — la richiesta non è nello stato ESCALATED. Non si può sovrascrivere un'approvazione automatica.

Reinvia una richiesta rifiutata

POST /api/v1/kyc/requests/:id/resubmit    Ambito: kyc:write

Riporta una richiesta REJECTED allo stato PENDING_UPLOAD, in modo che il richiedente possa riprovare. I documenti precedenti vengono cancellati; il richiedente ne carica di nuovi.

Risposta

{ "id": "req_...", "status": "PENDING_UPLOAD" }

Errori

• 409 CONFLICT — la richiesta non è nello stato REJECTED. Si possono reinviare solo le richieste rifiutate; quelle annullate o approvate no.

Elimina una richiesta

DELETE /api/v1/kyc/requests/:id    Ambito: kyc:write

Elimina in modo permanente la richiesta e tutto ciò che vi è collegato: la cancellazione coinvolge a cascata documenti, controlli e punteggi di rischio della richiesta, rimuove dallo storage le immagini/i PDF dei documenti caricati, ed elimina il record del richiedente quando nessun'altra richiesta vi fa riferimento. Usi questa operazione per soddisfare la richiesta di cancellazione di un cliente o per eliminare una verifica di prova.

Risposta

{
  "success": true,
  "documentsDeleted": 3,
  "applicantDeleted": true
}

• documentsDeleted — quanti file memorizzati sono stati rimossi.
• applicantDeleted — se il richiedente è stato ripulito perché orfano (false se ha ancora altre richieste).

Errori

• 404 NOT_FOUND — nessuna richiesta con quell'ID nella Sua organizzazione.

Comunicare l'esito

POST /api/v1/kyc/requests/:id/outcome    Ambito: kyc:write

Facoltativo. Comunichi a Certivant se l'acquisto o il credito per cui è stata fatta la verifica è stato davvero consegnato o annullato. Lo chiami quando la richiesta è stata decisa.

Corpo della richiesta

{ "fulfilled": true }

Risposta

{ "id": "req_...", "fulfilled": true, "recorded": true }

recorded: false significa che la richiesta non è ancora nella rete antifrode (ad esempio perché non ha chiavi di identità). Non si perde nulla: può inviare l'esito più tardi. Può anche richiamare l'endpoint in qualsiasi momento per modificare la risposta.

Errori

• 404 NOT_FOUND — nessuna richiesta con questo id in questa organizzazione.
• 409 CONFLICT — la richiesta non è ancora stata decisa. Il suo stato deve essere APPROVED, REJECTED, ESCALATED o PENDING_SECOND_REVIEW.

Ottieni i segnali di frode

GET /api/v1/kyc/requests/:id/fraud-signals    Ambito: kyc:read

Restituisce i segnali di frode legati al dispositivo, alla rete e al comportamento raccolti durante la verifica.

Risposta

[
  {
    "signalType": "device_reused",
    "severity": "medium",
    "details": { "previousRequestIds": ["req_..."], "matchedFingerprint": "..." }
  },
  {
    "signalType": "vpn_detected",
    "severity": "low",
    "details": { "asn": 13335, "isp": "Cloudflare" }
  }
]

La gravità è low, medium oppure high. I segnali di gravità alta inoltrano automaticamente la richiesta a una revisione manuale.

Monitoraggio AML continuo

Una verifica approvata può essere ricontrollata alla ricerca di nuovi riscontri in liste sanzioni, PEP (persone politicamente esposte) e notizie negative (adverse media) (vedi Monitoraggio continuo). Il monitoraggio è una funzione del piano e viene fatturato per persona monitorata all'anno.

POST restituisce 409 per una verifica non approvata, 403 quando il piano non include il monitoraggio e 402 quando non c'è credito per una persona oltre la quota inclusa.

I nuovi riscontri arrivano come webhook kyc.monitoring.alert (vedi Eventi webhook): data.monitoring contiene alertType (sanctions_match, pep_match, adverse_media, sanctions_unverifiable), severity e, per un PEP, pepTier — 1 capi di stato e ministri … 4 familiari e stretti collaboratori — oppure adverseMedia: true. data.sanctions.listsChecked indica le liste controllate; i fornitori dei servizi di screening non vengono mai nominati.

La verifica stessa riporta gli stessi pepTier / adverseMedia in data.sanctions nel webhook della decisione.

Elimina un richiedente (cancellazione GDPR)

DELETE /api/v1/kyc/applicants/:applicantId    Ambito: kyc:manage

Elimina in modo permanente un richiedente e ogni richiesta a lui collegata. È l'endpoint per il diritto alla cancellazione previsto dall'articolo 17 del GDPR. Il registro di audit conserva un segnaposto (tombstone) con la data e l'ora della cancellazione, ma nessun dato personale.

Risposta

{ "success": true, "deletedRequestIds": ["req_...", "req_..."] }