Inizia
Integrazione / SDK
Verifica degli utenti
Verifica aziendale
Monitoraggio delle transazioni
Changelogcurl -X POST 'https://verification.didit.me/v3/session/' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"workflow_id": "11111111-2222-3333-4444-555555555555",
"vendor_data": "user-123",
"callback": "https://example.com/verification/callback",
"callback_method": "both",
"metadata": {"user_type": "premium", "account_id": "ABC123"},
"language": "en",
"contact_details": {
"email": "john.doe@example.com",
"send_notification_emails": true,
"email_lang": "en",
"phone": "+14155552671"
},
"expected_details": {
"first_name": "John",
"last_name": "Doe",
"date_of_birth": "1990-05-15",
"id_country": "USA",
"expected_document_types": ["P", "ID"]
}
}'from didit import Didit
# Reads DIDIT_API_KEY.
client = Didit()
result = client.sessions.create(
workflow_id="11111111-2222-3333-4444-555555555555",
vendor_data="user-123",
callback="https://example.com/verification/callback",
callback_method="both",
metadata={"user_type": "premium", "account_id": "ABC123"},
language="en",
contact_details={
"email": "john.doe@example.com",
"send_notification_emails": True,
"email_lang": "en",
"phone": "+14155552671",
},
expected_details={
"first_name": "John",
"last_name": "Doe",
"date_of_birth": "1990-05-15",
"nationality": "USA",
"id_country": "USA",
"expected_document_types": ["P", "ID"],
},
)
print(result)import Didit from "@didit-protocol/sdk-node";
// Reads DIDIT_API_KEY.
const didit = new Didit();
const result = await didit.sessions.create({
workflow_id: "11111111-2222-3333-4444-555555555555",
vendor_data: "user-123",
callback: "https://example.com/verification/callback",
callback_method: "both",
metadata: { user_type: "premium", account_id: "ABC123" },
language: "en",
contact_details: {
email: "john.doe@example.com",
send_notification_emails: true,
email_lang: "en",
phone: "+14155552671",
},
expected_details: {
first_name: "John",
last_name: "Doe",
date_of_birth: "1990-05-15",
nationality: "USA",
id_country: "USA",
expected_document_types: ["P", "ID"],
},
});
console.log(result);ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()
result, err := client.Sessions.Create(ctx, didit.SessionsCreateParams{
WorkflowID: "11111111-2222-3333-4444-555555555555",
VendorData: didit.String("user-123"),
Callback: didit.String("https://example.com/verification/callback"),
CallbackMethod: didit.Some(didit.SessionsCreateParamsCallbackMethod("both")),
Metadata: didit.Some[any](map[string]any{"user_type": "premium", "account_id": "ABC123"}),
Language: didit.Some(didit.SessionsCreateParamsLanguage("en")),
ContactDetails: didit.Some(didit.SessionsCreateParamsContactDetails{
Email: didit.String("john.doe@example.com"),
SendNotificationEmails: didit.Bool(true),
EmailLang: didit.Some(didit.SessionsCreateParamsContactDetailsEmailLang("en")),
Phone: didit.String("+14155552671"),
}),
ExpectedDetails: didit.Some(didit.SessionsCreateParamsExpectedDetails{
FirstName: didit.String("John"),
LastName: didit.String("Doe"),
DateOfBirth: didit.String("1990-05-15"),
Nationality: didit.String("USA"),
IDCountry: didit.String("USA"),
ExpectedDocumentTypes: didit.Some([]didit.SessionsCreateParamsExpectedDetailsExpectedDocumentTypes{"P", "ID"}),
}),
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", result)import java.time.LocalDate;
import java.util.List;
import java.util.Map;
import me.didit.Didit;
import me.didit.types.SessionsCreateParams;
// Reads DIDIT_API_KEY.
Didit client = new Didit();
var result = client.sessions().create(SessionsCreateParams.builder()
.workflowId("11111111-2222-3333-4444-555555555555")
.vendorData("user-123")
.callback("https://example.com/verification/callback")
.callbackMethod(SessionsCreateParams.CallbackMethod.of("both"))
.metadata(Map.of("user_type", "premium", "account_id", "ABC123"))
.language(SessionsCreateParams.Language.of("en"))
.contactDetails(SessionsCreateParams.ContactDetails.builder()
.email("john.doe@example.com")
.sendNotificationEmails(true)
.emailLang(SessionsCreateParams.ContactDetails.EmailLang.of("en"))
.phone("+14155552671")
.build())
.expectedDetails(SessionsCreateParams.ExpectedDetails.builder()
.firstName("John")
.lastName("Doe")
.dateOfBirth(LocalDate.parse("1990-05-15"))
.nationality("USA")
.idCountry("USA")
.expectedDocumentTypes(List.of(SessionsCreateParams.ExpectedDetails.ExpectedDocumentTypes.of("P"), SessionsCreateParams.ExpectedDetails.ExpectedDocumentTypes.of("ID")))
.build())
.build());
System.out.println(result);<?php
require 'vendor/autoload.php';
use Didit\DiditClient;
// Reads DIDIT_API_KEY.
$didit = new DiditClient();
$result = $didit->sessions->create([
'workflow_id' => '11111111-2222-3333-4444-555555555555',
'vendor_data' => 'user-123',
'callback' => 'https://example.com/verification/callback',
'callback_method' => 'both',
'metadata' => ['user_type' => 'premium', 'account_id' => 'ABC123'],
'language' => 'en',
'contact_details' => [
'email' => 'john.doe@example.com',
'send_notification_emails' => true,
'email_lang' => 'en',
'phone' => '+14155552671',
],
'expected_details' => [
'first_name' => 'John',
'last_name' => 'Doe',
'date_of_birth' => '1990-05-15',
'nationality' => 'USA',
'id_country' => 'USA',
'expected_document_types' => ['P', 'ID'],
],
]);
print_r($result->toArray());require "didit"
# Reads DIDIT_API_KEY.
didit = Didit::Client.new
result = didit.sessions.create(
workflow_id: "11111111-2222-3333-4444-555555555555",
vendor_data: "user-123",
callback: "https://example.com/verification/callback",
callback_method: "both",
metadata: { user_type: "premium", account_id: "ABC123" },
language: "en",
contact_details: {
email: "john.doe@example.com",
send_notification_emails: true,
email_lang: "en",
phone: "+14155552671",
},
expected_details: {
first_name: "John",
last_name: "Doe",
date_of_birth: "1990-05-15",
nationality: "USA",
id_country: "USA",
expected_document_types: ["P", "ID"],
}
)
puts result.to_husing System;
using System.Collections.Generic;
using System.Text.Json;
using Didit;
// Reads DIDIT_API_KEY.
using var client = new DiditClient();
var result = await client.Sessions.CreateAsync(new SessionsCreateParams
{
WorkflowId = "11111111-2222-3333-4444-555555555555",
VendorData = "user-123",
Callback = "https://example.com/verification/callback",
CallbackMethod = new SessionsCreateParamsCallbackMethod("both"),
Metadata = new Dictionary<string, object> { ["user_type"] = "premium", ["account_id"] = "ABC123" },
Language = new SessionsCreateParamsLanguage("en"),
ContactDetails = new SessionsCreateParamsContactDetails
{
Email = "john.doe@example.com",
SendNotificationEmails = true,
EmailLang = new SessionsCreateParamsContactDetailsEmailLang("en"),
Phone = "+14155552671",
},
ExpectedDetails = new SessionsCreateParamsExpectedDetails
{
FirstName = "John",
LastName = "Doe",
DateOfBirth = "1990-05-15",
Nationality = "USA",
IdCountry = "USA",
ExpectedDocumentTypes = new SessionsCreateParamsExpectedDetailsExpectedDocumentTypes[] { "P", "ID" },
},
});
Console.WriteLine(JsonSerializer.Serialize(result));{
"session_id": "11111111-2222-3333-4444-555555555555",
"session_number": 43762,
"session_token": "3FaJ9wLqX2Mz",
"url": "https://verify.didit.me/en/session/3FaJ9wLqX2Mz",
"vendor_data": "user-123",
"metadata": {
"user_type": "premium",
"account_id": "ABC123"
},
"status": "Not Started",
"workflow_id": "11111111-2222-3333-4444-555555555555",
"workflow_version": 3,
"callback": "https://example.com/verification/callback"
}Crea sessione API: avvia verifica KYC o KYB
POST /v3/session/ di Didit avvia una verifica KYC o KYB. Endpoint unificato, prezzi a consumo, inferenza in meno di 2s, $10 di credito al mese.
curl -X POST 'https://verification.didit.me/v3/session/' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"workflow_id": "11111111-2222-3333-4444-555555555555",
"vendor_data": "user-123",
"callback": "https://example.com/verification/callback",
"callback_method": "both",
"metadata": {"user_type": "premium", "account_id": "ABC123"},
"language": "en",
"contact_details": {
"email": "john.doe@example.com",
"send_notification_emails": true,
"email_lang": "en",
"phone": "+14155552671"
},
"expected_details": {
"first_name": "John",
"last_name": "Doe",
"date_of_birth": "1990-05-15",
"id_country": "USA",
"expected_document_types": ["P", "ID"]
}
}'from didit import Didit
# Reads DIDIT_API_KEY.
client = Didit()
result = client.sessions.create(
workflow_id="11111111-2222-3333-4444-555555555555",
vendor_data="user-123",
callback="https://example.com/verification/callback",
callback_method="both",
metadata={"user_type": "premium", "account_id": "ABC123"},
language="en",
contact_details={
"email": "john.doe@example.com",
"send_notification_emails": True,
"email_lang": "en",
"phone": "+14155552671",
},
expected_details={
"first_name": "John",
"last_name": "Doe",
"date_of_birth": "1990-05-15",
"nationality": "USA",
"id_country": "USA",
"expected_document_types": ["P", "ID"],
},
)
print(result)import Didit from "@didit-protocol/sdk-node";
// Reads DIDIT_API_KEY.
const didit = new Didit();
const result = await didit.sessions.create({
workflow_id: "11111111-2222-3333-4444-555555555555",
vendor_data: "user-123",
callback: "https://example.com/verification/callback",
callback_method: "both",
metadata: { user_type: "premium", account_id: "ABC123" },
language: "en",
contact_details: {
email: "john.doe@example.com",
send_notification_emails: true,
email_lang: "en",
phone: "+14155552671",
},
expected_details: {
first_name: "John",
last_name: "Doe",
date_of_birth: "1990-05-15",
nationality: "USA",
id_country: "USA",
expected_document_types: ["P", "ID"],
},
});
console.log(result);ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()
result, err := client.Sessions.Create(ctx, didit.SessionsCreateParams{
WorkflowID: "11111111-2222-3333-4444-555555555555",
VendorData: didit.String("user-123"),
Callback: didit.String("https://example.com/verification/callback"),
CallbackMethod: didit.Some(didit.SessionsCreateParamsCallbackMethod("both")),
Metadata: didit.Some[any](map[string]any{"user_type": "premium", "account_id": "ABC123"}),
Language: didit.Some(didit.SessionsCreateParamsLanguage("en")),
ContactDetails: didit.Some(didit.SessionsCreateParamsContactDetails{
Email: didit.String("john.doe@example.com"),
SendNotificationEmails: didit.Bool(true),
EmailLang: didit.Some(didit.SessionsCreateParamsContactDetailsEmailLang("en")),
Phone: didit.String("+14155552671"),
}),
ExpectedDetails: didit.Some(didit.SessionsCreateParamsExpectedDetails{
FirstName: didit.String("John"),
LastName: didit.String("Doe"),
DateOfBirth: didit.String("1990-05-15"),
Nationality: didit.String("USA"),
IDCountry: didit.String("USA"),
ExpectedDocumentTypes: didit.Some([]didit.SessionsCreateParamsExpectedDetailsExpectedDocumentTypes{"P", "ID"}),
}),
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", result)import java.time.LocalDate;
import java.util.List;
import java.util.Map;
import me.didit.Didit;
import me.didit.types.SessionsCreateParams;
// Reads DIDIT_API_KEY.
Didit client = new Didit();
var result = client.sessions().create(SessionsCreateParams.builder()
.workflowId("11111111-2222-3333-4444-555555555555")
.vendorData("user-123")
.callback("https://example.com/verification/callback")
.callbackMethod(SessionsCreateParams.CallbackMethod.of("both"))
.metadata(Map.of("user_type", "premium", "account_id", "ABC123"))
.language(SessionsCreateParams.Language.of("en"))
.contactDetails(SessionsCreateParams.ContactDetails.builder()
.email("john.doe@example.com")
.sendNotificationEmails(true)
.emailLang(SessionsCreateParams.ContactDetails.EmailLang.of("en"))
.phone("+14155552671")
.build())
.expectedDetails(SessionsCreateParams.ExpectedDetails.builder()
.firstName("John")
.lastName("Doe")
.dateOfBirth(LocalDate.parse("1990-05-15"))
.nationality("USA")
.idCountry("USA")
.expectedDocumentTypes(List.of(SessionsCreateParams.ExpectedDetails.ExpectedDocumentTypes.of("P"), SessionsCreateParams.ExpectedDetails.ExpectedDocumentTypes.of("ID")))
.build())
.build());
System.out.println(result);<?php
require 'vendor/autoload.php';
use Didit\DiditClient;
// Reads DIDIT_API_KEY.
$didit = new DiditClient();
$result = $didit->sessions->create([
'workflow_id' => '11111111-2222-3333-4444-555555555555',
'vendor_data' => 'user-123',
'callback' => 'https://example.com/verification/callback',
'callback_method' => 'both',
'metadata' => ['user_type' => 'premium', 'account_id' => 'ABC123'],
'language' => 'en',
'contact_details' => [
'email' => 'john.doe@example.com',
'send_notification_emails' => true,
'email_lang' => 'en',
'phone' => '+14155552671',
],
'expected_details' => [
'first_name' => 'John',
'last_name' => 'Doe',
'date_of_birth' => '1990-05-15',
'nationality' => 'USA',
'id_country' => 'USA',
'expected_document_types' => ['P', 'ID'],
],
]);
print_r($result->toArray());require "didit"
# Reads DIDIT_API_KEY.
didit = Didit::Client.new
result = didit.sessions.create(
workflow_id: "11111111-2222-3333-4444-555555555555",
vendor_data: "user-123",
callback: "https://example.com/verification/callback",
callback_method: "both",
metadata: { user_type: "premium", account_id: "ABC123" },
language: "en",
contact_details: {
email: "john.doe@example.com",
send_notification_emails: true,
email_lang: "en",
phone: "+14155552671",
},
expected_details: {
first_name: "John",
last_name: "Doe",
date_of_birth: "1990-05-15",
nationality: "USA",
id_country: "USA",
expected_document_types: ["P", "ID"],
}
)
puts result.to_husing System;
using System.Collections.Generic;
using System.Text.Json;
using Didit;
// Reads DIDIT_API_KEY.
using var client = new DiditClient();
var result = await client.Sessions.CreateAsync(new SessionsCreateParams
{
WorkflowId = "11111111-2222-3333-4444-555555555555",
VendorData = "user-123",
Callback = "https://example.com/verification/callback",
CallbackMethod = new SessionsCreateParamsCallbackMethod("both"),
Metadata = new Dictionary<string, object> { ["user_type"] = "premium", ["account_id"] = "ABC123" },
Language = new SessionsCreateParamsLanguage("en"),
ContactDetails = new SessionsCreateParamsContactDetails
{
Email = "john.doe@example.com",
SendNotificationEmails = true,
EmailLang = new SessionsCreateParamsContactDetailsEmailLang("en"),
Phone = "+14155552671",
},
ExpectedDetails = new SessionsCreateParamsExpectedDetails
{
FirstName = "John",
LastName = "Doe",
DateOfBirth = "1990-05-15",
Nationality = "USA",
IdCountry = "USA",
ExpectedDocumentTypes = new SessionsCreateParamsExpectedDetailsExpectedDocumentTypes[] { "P", "ID" },
},
});
Console.WriteLine(JsonSerializer.Serialize(result));{
"session_id": "11111111-2222-3333-4444-555555555555",
"session_number": 43762,
"session_token": "3FaJ9wLqX2Mz",
"url": "https://verify.didit.me/en/session/3FaJ9wLqX2Mz",
"vendor_data": "user-123",
"metadata": {
"user_type": "premium",
"account_id": "ABC123"
},
"status": "Not Started",
"workflow_id": "11111111-2222-3333-4444-555555555555",
"workflow_version": 3,
"callback": "https://example.com/verification/callback"
}Supporto KYC e KYB
Un unico endpoint crea sia sessioni di Verifica degli utenti sia sessioni di Verifica aziendale. Il tipo di workflow determina il tipo di sessione:- Passa un
workflow_iddi un Workflow KYC → viene creata una sessione di Verifica degli utenti (KYC). Rispostasession_kind: "user". - Passa un
workflow_iddi un workflow KYB → viene creata una sessione di Verifica aziendale (KYB). Rispostasession_kind: "business".
Esempi
- Verifica degli utenti (KYC)
- Verifica aziendale (KYB)
curl -X POST https://verification.didit.me/v3/session/ \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflow_id": "YOUR_KYC_WORKFLOW_ID",
"vendor_data": "user-42",
"callback": "https://yourapp.com/callback"
}'
{
"session_id": "4c5c7f3a-1f82-4f3b-8d8e-1a8d2d2f9b7a",
"session_kind": "user",
"session_number": 1024,
"session_token": "...",
"url": "https://verify.didit.me/session/...",
"status": "Not Started",
"workflow_id": "YOUR_KYC_WORKFLOW_ID",
"vendor_data": "user-42"
}
curl -X POST https://verification.didit.me/v3/session/ \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflow_id": "YOUR_KYB_WORKFLOW_ID",
"vendor_data": "biz-acme-001",
"callback": "https://yourapp.com/callback"
}'
{
"session_id": "bs-01HJX1...",
"session_kind": "business",
"session_number": 89,
"session_token": "...",
"url": "https://verify.didit.me/session/...",
"status": "Not Started",
"workflow_id": "YOUR_KYB_WORKFLOW_ID",
"vendor_data": "biz-acme-001"
}
Documenti di firma elettronica
Quando il workflow include un passaggio di Firma elettronica che usa i documenti della sessione (signature_documents_source impostato su session o both), invia i documenti in sign.documents. Ogni documento è il file in base64, quindi Didit non deve mai recuperarlo da un URL.
{
"workflow_id": "YOUR_WORKFLOW_ID",
"vendor_data": "user-42",
"sign": {
"documents": [
{
"title": "Loan agreement",
"file_name": "loan-agreement.pdf",
"content_base64": "JVBERi0xLjcKJc...",
"fields": [
{ "key": "borrower_signature", "type": "signature", "label": "Borrower signature", "page": 3, "x": 0.1, "y": 0.78, "width": 0.32, "height": 0.06 },
{ "key": "date_signed", "type": "date_signed", "label": "Date", "page": 3, "x": 0.6, "y": 0.8, "width": 0.2, "height": 0.03, "date_format": "DD/MM/YYYY" },
{ "key": "loan_amount", "type": "data", "label": "Loan amount", "page": 1, "x": 0.34, "y": 0.31, "width": 0.3, "height": 0.03, "prefill": "api.loan_amount" },
{ "key": "initials", "type": "initials", "anchor": { "text": "[[initials]]", "occurrence": "all", "offset_x": 0, "offset_y": -0.005, "width": 0.12, "height": 0.04 } }
]
}
],
"field_values": { "loan_amount": "12,000 EUR" }
}
}
| Campo | Regole |
|---|---|
title | Mostrato al firmatario. Da 1 a 255 caratteri. Predefinito su file_name. |
file_name | Obbligatorio. Termina con .pdf o .docx. Da 1 a 255 caratteri. |
content_base64 | Obbligatorio. Un PDF può avere fino a 20 MB e 100 pagine, senza password, script o file allegati. Un file Word può avere fino a 20 MB e viene convertito in PDF durante l’esecuzione della richiesta, in un massimo di 25 secondi; il PDF ha poi gli stessi limiti. Fino a 5 file Word per sessione. |
fields | Facoltativo. Fino a 200 campi da posizionare sul documento, nella forma del campo senza id. Ogni campo richiede una key e un type, e una posizione (page, x, y, width e height) oppure una anchor. role ha come predefinito il firmatario dello step, mentre required e label derivano dal tipo di campo. Didit imposta position in base a dove si trova il campo. Pagine e posizioni si riferiscono al PDF, o al PDF convertito per un file Word. |
fields, il firmatario legge il documento e lo accetta.
Posiziona i campi tramite testo di ancoraggio
Invece di una posizione, un campo può avere unanchor: un testo nel documento che indica dove va il campo. Le ancore sono adatte ai documenti che generi per ogni sessione, per esempio da un modello Word. Per i documenti del workflow, posiziona i campi nella console.
Proprietà anchor | Regole |
|---|---|
text | Da 1 a 64 caratteri, cercati nel testo del documento. Per un file Word, nel PDF convertito. |
occurrence | first (predefinito) posiziona un solo campo alla prima corrispondenza. all posiziona un campo per ogni corrispondenza, e le chiavi dopo la prima ricevono _2, _3 e così via. |
offset_x, offset_y | Frazioni della pagina. L’angolo in alto a sinistra del campo coincide con l’angolo in alto a sinistra del testo di ancoraggio più questi offset. |
width, height | Dimensioni del campo, come frazioni della pagina. |
400 con field_anchor_not_found e la chiave del campo. Didit non rimuove il testo di ancoraggio dal PDF, quindi scrivilo con lo stesso colore dello sfondo della pagina.
Valori dei campi
sign.field_values imposta il valore di ogni campo il cui prefill è api.<key>, sia nei documenti del workflow sia in quelli della sessione. È un oggetto con chiavi corrispondenti a questi nomi <key>. I valori sono stringhe da 1 a 500 caratteri per i campi text e data, e booleani per un checkbox.
{
"workflow_id": "YOUR_WORKFLOW_ID",
"vendor_data": "user-42",
"sign": {
"field_values": { "credit_limit": "3,000 EUR", "monthly_fee": "4.90 EUR" }
}
}
Errore (400) | Quando |
|---|---|
field_value_unknown | Una chiave che nessun campo usa. |
field_value_missing | Un campo obbligatorio il cui api.<key> non ha un valore. |
field_value_invalid | Un valore che non supera la validazione del proprio campo. |
Errori e chiamate ripetute
Una sessione accetta fino a 20 documenti e 50 MB in totale. La chiamata restituisce400 con un errore sign quando:
- Il workflow non ha un passaggio di Firma elettronica.
- Hai inviato
sign.documentse il passaggio accetta solo i documenti del workflow. - Il passaggio accetta solo i documenti della sessione e non ne hai inviati, oppure non ha documenti del workflow e non ne hai inviati.
- Un documento è troppo grande, non è base64 valido o non è un file supportato.
- Un file Word viene rifiutato con
signature_document_not_supported, oppure non può essere convertito e restituiscesignature_document_conversion_failed; in entrambi i casi è riportato ilreasonelencato in File supportati. - Un campo non è valido, la sua ancora non viene trovata (
field_anchor_not_found), oppure un valore del campo viene rifiutato.
workflow_id e vendor_data restituisce la sessione in attesa. Se questa chiamata invia sign, i suoi documenti, campi e valori dei campi devono essere identici ai primi (stesso ordine, titoli, nomi dei file, contenuto, campi e valori). Qualsiasi differenza restituisce 400 con {"sign": "signature_document_changed"}: usa un vendor_data diverso, oppure attendi che la sessione in attesa termini.
Test con scenari sandbox
In un’applicazione in modalità sandbox, passasandbox_scenario per precaricare un esito deterministico (approvazione, un rifiuto specifico o uno scenario In revisione) senza toccare i provider reali né il tuo saldo:
{
"workflow_id": "YOUR_SANDBOX_WORKFLOW_ID",
"sandbox_scenario": "decline_document_expired"
}
sandbox_scenario viene rifiutato con 400 nelle applicazioni in ambiente di produzione. Se al momento della creazione non conosci ancora l’esito, puoi impostarlo (o reimpostarlo) in seguito tramite POST /v3/session/{session_id}/sandbox/arm/, finché la sessione è ancora Not Started: il selettore dello scenario prima del flusso ospitato usa questo stesso endpoint. Consulta Sandbox e dati di test per il catalogo completo degli scenari, il registro dei valori magici e la struttura di richiesta e risposta dell’endpoint arm.
vendor_data collega la sessione a un’entità
- Per i workflow KYC: viene collegato a un’entità utente. Se l’utente non esiste, viene creato automaticamente.
- Per i workflow KYB: viene collegato a un’entità aziendale. Se è nuova, viene creata automaticamente.
Consenso biometrico in Illinois, Texas e Colorado
Il flusso ospitato e l’SDK nativo 4.10.0 o successivo possono mostrare un passaggio esplicito di consenso biometrico prima della prima acquisizione del volto, a seconda della modalità di consenso dell’applicazione e della località della persona. Due campi facoltativi alimentano questa decisione:user_state: dove vive la persona, quando lo conosci (US-IL,ILoIllinois). In modalità Auto, uno stato coperto fa sì che il flusso chieda il consenso.biometric_consent: un oggetto congiven_atetext_version, per il consenso che hai già raccolto. Il flusso non lo richiede di nuovo.
Importante: l’informativa viene fornita e il consenso viene raccolto ancora nel tuo prodotto
Create Session genera un URL di verifica e un token di sessione. Di per sé non dimostra che hai mostrato all’utente le informative o ottenuto il consenso richiesto per il tuo specifico caso d’uso.
Se avvii una sessione Didit dalla tua applicazione, dal tuo sito web, da un wrapper SDK o da un flusso white label, devi gestire lo strato legale nella tua UX prima che l’utente inizi l’acquisizione.
Checklist consigliata prima della verifica
- Comunica all’utente che la tua azienda richiede la verifica e che Didit è il fornitore di verifica / responsabile del trattamento che supporta il flusso.
- Inserisci un link alla tua informativa sulla privacy e agli eventuali termini legali del titolare del trattamento applicabili al percorso.
- Inserisci un link alla Informativa sulla privacy per la verifica di Didit e ai Termini per l’utente finale per la verifica dell’identità.
- Se il tuo workflow include l’acquisizione del documento o del selfie, il Rilevamento della vitalità o l’uso di dati biometrici, raccogli un consenso esplicito e affermativo ogni volta che la legge applicabile o la tua posizione legale lo richiedono.
- Se usi un’interfaccia personalizzata, un dominio personalizzato o un percorso solo API, mostra queste informative nel tuo prodotto prima di inviare l’utente al flusso Didit.
- Conserva una tua registrazione del testo dell’informativa o del consenso, del timestamp e dei metadati correlati, se il tuo team legale richiede una traccia di audit.
Autorizzazioni
La chiave API della tua applicazione, da Developers -> API keys nella Business Console. La chiave primaria ha accesso completo. Una chiave con nome può avere un ambito definito: nessuno, lettura o scrittura per risorsa, limitata ad alcuni workflow o a sessioni approvate, a un elenco di indirizzi IP e a una data di scadenza. 401 indica che la chiave è errata, revocata o scaduta; 403 indica che non è stata inviata alcuna chiave, che la chiave non ha accesso a questa risorsa o azione, oppure che la richiesta proviene da un indirizzo non incluso nel suo elenco IP; 404 su una route di sessione indica che la sessione non rientra nei workflow o negli stati previsti dalla chiave. Una chiave senza accesso ai media riceve gli URL di immagini, video e PDF come null, e una chiave senza permessi di scrittura sulle sessioni riceve link e token di sessione come null. Consulta https://docs.didit.me/console/api-keys.
Corpo
Identificatore stabile del workflow che definisce i passaggi di verifica che la sessione eseguirà. I workflow vengono creati e gestiti nella pagina Workflows della Console. Il valore workflow_id seleziona inoltre implicitamente se la sessione è KYC o KYB.
"11111111-2222-3333-4444-555555555555"
Un identificatore univoco per l'utente in fase di verifica, come un UUID, un'email o un ID utente interno. Questo campo è utilizzato per: (1) Raggruppamento degli utenti — le sessioni con lo stesso vendor_data vengono collegate allo stesso profilo utente nella scheda Utenti. (2) Rilevamento di duplicati cross-sessione — durante il controllo di volti, documenti, numeri di telefono, email, indirizzi IP o fingerprint dei dispositivi duplicati, le sessioni con lo stesso vendor_data vengono trattate come lo stesso utente ed escluse dalle corrispondenze. Senza vendor_data, ogni sessione viene considerata come un utente univoco e vengono mostrati tutti i potenziali duplicati. Consigliamo vivamente di fornire sempre un vendor_data per ridurre il rumore nel rilevamento dei duplicati.
"user-123"
Ambito opzionale per il rilevamento dei duplicati all'interno della tua organizzazione. I controlli dei volti duplicati confrontano questa sessione solo con altre sessioni che presentano lo stesso segmento, in modo che basi di account distinte (account personali e aziendali, o uno per ciascun sub-cliente B2B) non segnalino una persona che possiede legittimamente un account in ciascuna di esse. Omettilo per utilizzare il singolo ambito predefinito, che è quello utilizzato oggi da ogni sessione. La corrispondenza con blocklist e allowlist ignora questo campo.
64"business-accounts"
URL a cui reindirizzare l'utente al termine della verifica. Didit aggiunge automaticamente verificationSessionId e status (Approved, Declined, In Review) come parametri di query. Gli schemi URL personalizzati (es. myapp://) sono supportati per i callback su dispositivi mobili. Se omesso, viene utilizzato il callback_url predefinito del workflow. Quando l'applicazione ha domini consentiti (allowed_domains su PATCH /v3/webhook/), un callback http o https deve appartenere a una di queste origini (stesso schema, host e porta), altrimenti la richiesta non va a buon fine con 400 su callback: callback must be on one of the application's allowed domains: https://app.example.com. Gli schemi URL personalizzati sono sempre accettati.
"https://example.com/verification/callback"
Determina quale dispositivo deve gestire il reindirizzamento all'URL di callback fornito. Usa initiator per reindirizzare solo il dispositivo che ha avviato il flusso, completer per il dispositivo che lo completa, oppure both per consentire a entrambi i dispositivi di attivare il callback. Se noti che il callback non si attiva in modo affidabile, ti consigliamo di impostare questo valore su both.
initiator, completer, both "both"
JSON arbitrario memorizzato con la sessione e restituito nella risposta e nei webhook. È accettato qualsiasi valore JSON (oggetto, stringa, numero, array), ma è consigliato un oggetto JSON di coppie chiave/valore. Non viene mostrato all'utente finale. Utilizzalo per trasmettere i tuoi ID di correlazione, varianti A/B o il contesto aziendale.
{
"user_type": "premium",
"account_id": "ABC123"
}
Tag aggiunti alla sessione al momento della creazione, per nome. Fino a 10, ciascuno di massimo 50 caratteri. I nomi non distinguono tra maiuscole e minuscole e vengono memorizzati in maiuscolo. Un nome non ancora presente nell'applicazione viene creato come nuovo tag. I tag compaiono sulla sessione nella console, dove puoi filtrarli.
1050["VIP", "ONBOARDING Q4"]
Codice lingua (ISO 639-1) per l'interfaccia della procedura di verifica. Controlla la lingua mostrata all'utente finale durante la verifica. Se non fornito, la lingua del browser verrà rilevata e utilizzata automaticamente. Consulta tutte le lingue supportate qui.
en, ar, bg, bn, bs, ca, cnr, cs, da, de, el, es, et, fa, fi, fr, he, hi, hr, hu, hy, id, it, ja, ka, kk, ko, ky, lt, lv, mk, mn, ms, nl, no, pl, pt-BR, pt, ro, ru, sk, sl, so, sq, sr, sv, th, tr, uk, uz, vi, zh-CN, zh-TW, zh "en"
Informazioni di contatto dell'utente che possono essere utilizzate per le notifiche, la precompilazione dei moduli di verifica e la verifica telefonica. Sono inclusi l'indirizzo email, la lingua preferita per le comunicazioni e il numero di telefono.
Show child attributes
Show child attributes
{
"email": "john.doe@example.com",
"send_notification_emails": true,
"email_lang": "en",
"phone": "+14155552671"
}
Dettagli dell'utente previsti utilizzati per la convalida incrociata rispetto ai dati estratti dal documento d'identità dell'utente, dalla Prova di residenza e da altri passaggi di verifica. Le discrepanze vengono segnalate come avvisi nella decisione; alcuni campi (ad es. id_country, expected_document_types) modificano anche il flusso visibile all'utente. Per i workflow di Verifica aziendale (KYB) vengono utilizzati solo i campi aziendali (company_name, registry_country, registration_number) — che precompilano la ricerca nel registro delle imprese per l'utente — e tutti i campi relativi alla persona vengono ignorati.
Show child attributes
Show child attributes
{
"first_name": "John",
"last_name": "Doe",
"date_of_birth": "1990-05-15",
"nationality": "USA",
"id_country": "USA",
"expected_document_types": ["P", "ID"]
}
Immagine del volto dell'utente finale codificata in Base64 (max 2 MB; JPEG, PNG, WebP o TIFF). Utilizzata come immagine di riferimento da confrontare con l'acquisizione della vitalità quando il workflow è un workflow di Biometric Authentication con Confronto facciale abilitato, o qualsiasi workflow a grafo in cui il Confronto facciale viene eseguito prima della Verifica dell'identità (OCR). Opzionale quando l'utente specificato in vendor_data ha già un'immagine del volto memorizzata: Didit la riutilizza automaticamente, risolvendola in ordine di priorità: volto da rilevamento della vitalità approvato, foto del chip dell'ePassport, ritratto del documento d'identità, volto del profilo registrato manualmente (vengono riutilizzati solo i volti provenienti da sessioni approvate o i volti che hai registrato personalmente). Se fornita, portrait_image ha sempre la precedenza sul volto memorizzato. Se omessa e non esiste alcun volto memorizzato (o non viene inviato vendor_data), la creazione della sessione fallisce con 400. Ignorata per altri tipi di workflow.
"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="
Slug dello scenario solo per la sandbox. Accettato solo quando la chiave API appartiene a un'applicazione in modalità sandbox; rifiutato nelle applicazioni di produzione. Se impostato, il flusso di creazione inserisce i valori magici associati allo scenario nei campi di input della sessione (contact_details, expected_details), consentendo ai provider simulati di riprodurre l'esito dello scenario lungo l'effettiva pipeline del workflow. Consulta il catalogo degli scenari con GET /v1/sandbox/scenarios/ o in Sandbox e dati di test. Puoi anche preparare (o ripreparare) uno scenario dopo la creazione tramite POST /v3/session/{sessionId}/sandbox/arm/, a condizione che la sessione sia ancora Not Started. Per le verifiche senza documenti, usa lookup_partial_match, lookup_no_match o lookup_provider_error per testare il budget di tentativi configurato e il fallback. Per i wallet di identità, usa wallet_cancelled, wallet_timeout o wallet_provider_error; approve simula un wallet verificato. Tutti i wallet del catalogo possono essere testati in sandbox, inclusi gli schemi non disponibili nelle applicazioni di produzione. I tentativi simulati non vengono addebitati.
"decline_document_expired"
Dati di input di Firma elettronica per questa sessione. I documents sono i documenti da firmare, per un workflow il cui passaggio di Firma elettronica riceve i documenti dalla sessione (signature_documents_source session o both): fino a 20 documenti e 50 MB in totale. field_values compila i campi il cui prefill è api.<key>, sia sui documenti del workflow che su quelli della sessione. Creando nuovamente una sessione per gli stessi workflow_id e vendor_data viene restituita la sessione in sospeso; se tale chiamata invia sign, i relativi documenti, campi e valori devono essere identici a quelli iniziali, altrimenti qualsiasi differenza restituisce 400 con {"sign": "signature_document_changed"}. Consulta Documenti di Firma elettronica.
Show child attributes
Show child attributes
Dove risiede la persona, se noto: un codice di suddivisione ISO 3166-2 (US-IL, ES-M) o un codice o nome di uno stato USA (IL, Illinois). Uno stato la cui legislazione richiede un consenso biometrico esplicito (Illinois, Texas, Colorado) fa sì che il flusso di verifica lo richieda prima di acquisire il volto, con trigger declared_state. Un valore non riconosciuto restituisce 400. Consulta Consenso biometrico.
16"US-IL"
Consenso biometrico esplicito già raccolto dalla persona. Soddisfa il requisito, quindi il flusso di verifica non lo richiede nuovamente, e la decisione lo registra come status: "given" con trigger customer_collected. Una risposta già fornita dalla persona nel flusso non viene mai sostituita. Consulta Consenso biometrico.
Show child attributes
Show child attributes
Risposta
Sessione creata (o restituita, se esiste già una sessione non completata con gli stessi vendor_data sull'ultima versione pubblicata del workflow). La risposta è la sessione serializzata, incluso l'url della pagina di verifica ospitata a cui reindirizzare l'utente.
Identificativo univoco della sessione di verifica. Usa questo id quando chiami GET /v3/session/{sessionId}/decision/.
"11111111-2222-3333-4444-555555555555"
Numero sequenziale e di facile lettura assegnato alla sessione all'interno della tua applicazione. Utile per l'assistenza e le dashboard.
43762
Token URL-safe di 12 caratteri che autorizza l'utente finale ad accedere al flusso di verifica ospitato all'indirizzo url. Valido fino alla scadenza della sessione. Trattalo come un segreto: chiunque lo possieda può aprire il flusso di verifica per questa sessione.
"3FaJ9wLqX2Mz"
URL di verifica ospitato a cui reindirizzare l'utente finale. L'URL include il session_token e, se configurato, utilizza il tuo dominio white label. Quando la richiesta include language, l'URL contiene un segmento di percorso per la lingua — https://verify.didit.me/{language}/session/{session_token} (ad es. /es/session/...); senza language, il segmento viene omesso.
"https://verify.didit.me/session/3FaJ9wLqX2Mz"
Identificatore che hai passato nella richiesta per collegare la sessione a un utente o a un'azienda nel tuo sistema. Restituito esattamente come inviato. Null se non fornito.
"user-123"
Payload JSON arbitrario memorizzato con la sessione al momento della creazione. Viene restituito testualmente: qualunque valore JSON inviato (oggetto, stringa, numero, array) viene restituito così com'è, anche se è consigliato un oggetto JSON. Non viene mostrato all'utente finale. Sempre presente nelle risposte; null se non fornito al momento della creazione.
{
"user_type": "premium",
"account_id": "ABC123"
}
Stato attuale della sessione. Le sessioni appena create restituiscono Not Started. Se esisteva già una sessione non conclusa per lo stesso vendor_data sull'ultima versione pubblicata del workflow, lo stato restituito riflette tale sessione esistente.
Not Started, In Progress, Approved, Declined, In Review, Expired, Abandoned, Kyc Expired, Resubmitted, Awaiting User "Not Started"
URL di reindirizzamento finale a cui l'utente viene inviato dopo aver completato il flusso. Didit aggiunge ?verificationSessionId={session_id}&status={status} a questo URL. Utilizza come fallback l'URL di callback configurato nel workflow se non fornito nella richiesta; null quando nessuno dei due è impostato. Se l'applicazione ha domini consentiti e questo URL è un URL web esterno a essi (ad esempio un valore predefinito del workflow impostato prima della modifica dell'elenco), il flusso ospitato non vi reindirizza l'utente.
"https://example.com/verification/callback"
Identificatore stabile del workflow su cui viene eseguita questa sessione. Corrisponde sempre all'identificatore di gruppo stabile del workflow; anche se nella richiesta hai fatto riferimento all'UUID di una versione specifica del workflow (ricerca retrocompatibile), la risposta riporta il workflow_id stabile. Usalo per correlare la sessione con il workflow configurato nella Console.
"11111111-2222-3333-4444-555555555555"
Numero di versione della versione pubblicata del workflow a cui la sessione è stata associata al momento della creazione. Didit risolve workflow_id con l'ultima versione pubblicata del workflow quando la sessione viene creata, e la sessione continua a eseguire quella versione anche se il workflow viene ripubblicato successivamente.
3
I tag presenti sulla sessione, per nome.
["VIP", "ONBOARDING Q4"]