Verifiche riutilizzate

I richiedenti che hanno già completato una verifica approvata — individuale oppure aziendale (KYB) — presso un'altra organizzazione Certivant possono condividerla con la Sua. Lei crea un link, il richiedente dimostra che la verifica è sua e dà il consenso, e Lei riscatta un token di condivisione monouso in una nuova verifica già approvata della Sua organizzazione. I dati e i file dei documenti vengono copiati nei Suoi record e nel Suo storage.

Gli endpoint si trovano sotto /api/v1/kyc/reuse e usano una chiave API (Authorization: Bearer ck_live_…). Servono la funzione del piano Verifiche riutilizzate e l'attivazione di Accetta verifiche riutilizzate (persone fisiche) e/o Accetta verifiche aziendali riutilizzate (aziende) in Impostazioni → KYC; i due interruttori sono gestiti, datati e prezzati separatamente. Vedi Autenticazione.

Flusso

sequenceDiagram
  participant You as Your system
  participant C as Certivant
  participant A as Applicant
  You->>C: POST /reuse/invitations
  C-->>You: inviteUrl
  You->>A: send inviteUrl
  A->>C: verification ID + emailed code
  A->>C: consent ("Share my verified identity with you")
  C-->>A: redirect to redirectUrl?certivant_share=krs_…
  A->>You: lands on your page with the token
  You->>C: POST /reuse/redeem { shareToken }
  C-->>You: new approved verification

Crea un invito

POST /api/v1/kyc/reuse/invitations — ambito kyc:write.

{
  "id": "clx…",
  "inviteUrl": "https://app.certivant.com/reuse/kri_…",
  "inviteExpiresAt": "2026-10-24T13:00:00.000Z",
  "shareTtlMinutes": 30
}

Segua un invito

GET /api/v1/kyc/reuse/invitations/:id — ambito kyc:read. La risposta contiene anche type (INDIVIDUAL oppure BUSINESS). status può essere invited, code_sent, verified, consented (un token è in attesa), redeemed, expired oppure revoked. Quando è riscattato, requestId è la nuova verifica. Il token di condivisione non viene mai restituito qui; Le arriva tramite il reindirizzamento del richiedente.

Riscatta un token di condivisione

POST /api/v1/kyc/reuse/redeem — ambito kyc:write.

{ "shareToken": "krs_…" }

{
  "requestId": "clx…",
  "applicantId": "clx…",
  "status": "APPROVED",
  "type": "INDIVIDUAL",
  "externalRef": "crm-7",
  "reused": true,
  "verifiedAt": "2026-09-30T15:12:00.000Z",
  "sourceAgeDays": 24,
  "documentsCopied": 2,
  "chargedCents": 0
}

Regole:

• Un token è monouso, scade al termine della sua durata e funziona solo per l'organizzazione che ha creato il link. Qualsiasi altro chiamante riceve 404 invalid_token.
• La chiamata crea una verifica già approvata, con copie dei dati del richiedente, dei campi estratti dai documenti e dei file dei documenti (nella Sua posizione di storage). Se la Sua organizzazione non conserva documenti dopo una decisione, non viene copiato alcun file.
• Per una condivisione aziendale (type: "BUSINESS" nella risposta) la nuova verifica è una richiesta BUSINESS che contiene anche la scheda dell'azienda e il risultato del registro, gli amministratori e i titolari effettivi (senza i collegamenti alle verifiche UBO della fonte), l'identità verificata del rappresentante e la sua corrispondenza con gli amministratori, e il documento di autorizzazione, se esiste. Lo legga con gli endpoint KYB abituali (GET /v1/kyc/requests/:id/kyb).
• La nuova verifica registra la chiave API che l'ha riscattata. Se quella chiave è limitata ai workflow, per essa vengono eseguiti solo quei workflow (vedi Limitazione ai workflow).
• Si attivano i Suoi webhook abituali: un evento kyc.request.approved con data.reason: "reused_verification".
• Se una copia non riesce, il token viene restituito (fino alla scadenza) e non resta nulla.

Errori

Residenza

Entrambe le organizzazioni devono avere la stessa regione di storage, la stessa regione del database e la stessa residenza per l'elaborazione IA (una regione non impostata corrisponde solo a un'altra regione non impostata). Altrimenti la condivisione viene rifiutata con residency_mismatch — nulla viene copiato oltre un confine regionale.

Su un modulo pubblico

Quando la Sua organizzazione accetta verifiche riutilizzate di un tipo, un modulo KYC pubblico (persona fisica) o un modulo KYB (azienda) propone "Già verificato con Certivant?" all'inizio. Il richiedente dimostra la propria titolarità (codice inviato via email) e dà il consenso esattamente come sopra; il modulo viene precompilato dalla verifica condivisa (può rivedere e correggere tutto; non vengono richiesti documenti), e l'invio viene registrato sulla nuova verifica riutilizzata già approvata. I moduli combinati KYC + KYB, i link di invito (?kyc=) e i moduli che non sono di verifica non offrono questa opzione.

Gli endpoint del modulo stesso (pubblici, senza chiave API) sono, come riferimento per quando incorpora un modulo da sé:

Un modulo protetto da una chiave segreta deve inviarla nell'header X-Form-Key a ogni chiamata. Una condivisione creata per un modulo può essere riscattata solo dall'invio di quel modulo — non con POST /reuse/redeem (404 invalid_token) — e la nuova verifica viene attribuita al modulo.

Fatturazione

Gratuita per impostazione predefinita. Un prezzo Verifica riutilizzata (persone fisiche) e un prezzo Verifica aziendale riutilizzata (aziende) nei Prezzi di fatturazione (o in una tariffa personalizzata per cliente) vengono addebitati all'organizzazione ricevente una volta per ogni condivisione riscattata; la chiamata è idempotente per condivisione.

Audit

Il registro di audit dell'organizzazione ricevente registra reuse.invitation_created, reuse.consent_received e reuse.redeemed. L'organizzazione di origine registra reuse.consent_recorded e reuse.shared. L'identità dell'organizzazione di origine non viene mai esposta a Lei.