Inizia
Integrazione / SDK
Verifica degli utenti
Verifica aziendale
Monitoraggio delle transazioni
ChangelogcURL
curl -X POST 'https://verification.didit.me/v3/workflows/' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"workflow_label": "Standard KYC",
"features": [
{"feature": "OCR"},
{"feature": "LIVENESS", "config": {"face_liveness_method": "passive"}},
{"feature": "FACE_MATCH", "config": {"face_match_score_decline_threshold": 40, "face_match_score_review_threshold": 60}}
]
}'from didit import Didit
# Reads DIDIT_API_KEY.
client = Didit()
result = client.workflows.create(
workflow_label="Standard KYC",
features=[{
"feature": "OCR",
"config": {"duplicated_user_action": "review"},
}, {
"feature": "LIVENESS",
"config": {"face_liveness_method": "passive"},
}, {
"feature": "FACE_MATCH",
"config": {"face_match_score_decline_threshold": 40, "face_match_score_review_threshold": 60},
}],
)
print(result)import Didit from "@didit-protocol/sdk-node";
// Reads DIDIT_API_KEY.
const didit = new Didit();
const result = await didit.workflows.create({
workflow_label: "Standard KYC",
features: [{
feature: "OCR",
config: { duplicated_user_action: "review" },
}, {
feature: "LIVENESS",
config: { face_liveness_method: "passive" },
}, {
feature: "FACE_MATCH",
config: { face_match_score_decline_threshold: 40, face_match_score_review_threshold: 60 },
}],
});
console.log(result);ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()
result, err := client.Workflows.Create(ctx, didit.SimpleWorkflowRequest{
WorkflowLabel: didit.String("Standard KYC"),
Features: []didit.SimpleWorkflowFeature{{
Feature: "OCR",
Config: didit.Some(map[string]any{"duplicated_user_action": "review"}),
}, {
Feature: "LIVENESS",
Config: didit.Some(map[string]any{"face_liveness_method": "passive"}),
}, {
Feature: "FACE_MATCH",
Config: didit.Some(map[string]any{"face_match_score_decline_threshold": 40, "face_match_score_review_threshold": 60}),
}},
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", result)import java.util.List;
import java.util.Map;
import me.didit.Didit;
import me.didit.types.SimpleWorkflowFeature;
import me.didit.types.SimpleWorkflowRequest;
// Reads DIDIT_API_KEY.
Didit client = new Didit();
var result = client.workflows().create(SimpleWorkflowRequest.builder()
.workflowLabel("Standard KYC")
.features(List.of(
SimpleWorkflowFeature.builder()
.feature(SimpleWorkflowFeature.Feature.of("OCR"))
.config(Map.of("duplicated_user_action", "review"))
.build(),
SimpleWorkflowFeature.builder()
.feature(SimpleWorkflowFeature.Feature.of("LIVENESS"))
.config(Map.of("face_liveness_method", "passive"))
.build(),
SimpleWorkflowFeature.builder()
.feature(SimpleWorkflowFeature.Feature.of("FACE_MATCH"))
.config(Map.of("face_match_score_decline_threshold", 40, "face_match_score_review_threshold", 60))
.build()))
.build());
System.out.println(result);<?php
require 'vendor/autoload.php';
use Didit\DiditClient;
// Reads DIDIT_API_KEY.
$didit = new DiditClient();
$result = $didit->workflows->create([
'workflow_label' => 'Standard KYC',
'features' => [[
'feature' => 'OCR',
'config' => ['duplicated_user_action' => 'review'],
], [
'feature' => 'LIVENESS',
'config' => ['face_liveness_method' => 'passive'],
], [
'feature' => 'FACE_MATCH',
'config' => ['face_match_score_decline_threshold' => 40, 'face_match_score_review_threshold' => 60],
]],
]);
print_r($result->toArray());require "didit"
# Reads DIDIT_API_KEY.
didit = Didit::Client.new
result = didit.workflows.create(
workflow_label: "Standard KYC",
features: [{
feature: "OCR",
config: { duplicated_user_action: "review" },
}, {
feature: "LIVENESS",
config: { face_liveness_method: "passive" },
}, {
feature: "FACE_MATCH",
config: { face_match_score_decline_threshold: 40, face_match_score_review_threshold: 60 },
}]
)
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.Workflows.CreateAsync(new SimpleWorkflowRequest
{
WorkflowLabel = "Standard KYC",
Features = new SimpleWorkflowFeature[]
{
new()
{
Feature = "OCR",
Config = new Dictionary<string, object> { ["duplicated_user_action"] = "review" },
},
new()
{
Feature = "LIVENESS",
Config = new Dictionary<string, object> { ["face_liveness_method"] = "passive" },
},
new()
{
Feature = "FACE_MATCH",
Config = new Dictionary<string, object> { ["face_match_score_decline_threshold"] = 40, ["face_match_score_review_threshold"] = 60 },
},
},
});
Console.WriteLine(JsonSerializer.Serialize(result));{
"uuid": "c3d4e5f6-7890-12cd-ef34-333333333333",
"workflow_id": "c3d4e5f6-7890-12cd-ef34-333333333333",
"workflow_label": "Standard KYC",
"workflow_type": null,
"is_default": false,
"is_archived": false,
"total_price": 0.15,
"min_price": 0.15,
"max_price": 0.15,
"features": "OCR + LIVENESS + FACE_MATCH",
"is_simple_workflow": false,
"is_editable": false,
"workflow_url": "https://verify.didit.me/u/w9TkPOx8RWG3UAz5ZRQGVQ",
"workflow_graph": {
"start_node": "ocr",
"nodes": "... one node per feature plus a final status node ..."
},
"max_retry_attempts": 3,
"retry_window_days": 7,
"session_expiration_time": 604800,
"version": 1,
"status": "published",
"published_at": "2026-05-17T10:30:00Z",
"created_at": "2026-05-17T10:30:00Z",
"updated_at": "2026-05-17T10:30:00Z"
}Workflow
Crea workflow API: costruisci il flusso KYC
Crea via API un workflow Didit con funzionalità ordinate: KYC, KYB, AML e biometria in un unico flusso. Pagamento a chiamata, senza contratti.
POST
/
v3
/
workflows
/
cURL
curl -X POST 'https://verification.didit.me/v3/workflows/' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"workflow_label": "Standard KYC",
"features": [
{"feature": "OCR"},
{"feature": "LIVENESS", "config": {"face_liveness_method": "passive"}},
{"feature": "FACE_MATCH", "config": {"face_match_score_decline_threshold": 40, "face_match_score_review_threshold": 60}}
]
}'from didit import Didit
# Reads DIDIT_API_KEY.
client = Didit()
result = client.workflows.create(
workflow_label="Standard KYC",
features=[{
"feature": "OCR",
"config": {"duplicated_user_action": "review"},
}, {
"feature": "LIVENESS",
"config": {"face_liveness_method": "passive"},
}, {
"feature": "FACE_MATCH",
"config": {"face_match_score_decline_threshold": 40, "face_match_score_review_threshold": 60},
}],
)
print(result)import Didit from "@didit-protocol/sdk-node";
// Reads DIDIT_API_KEY.
const didit = new Didit();
const result = await didit.workflows.create({
workflow_label: "Standard KYC",
features: [{
feature: "OCR",
config: { duplicated_user_action: "review" },
}, {
feature: "LIVENESS",
config: { face_liveness_method: "passive" },
}, {
feature: "FACE_MATCH",
config: { face_match_score_decline_threshold: 40, face_match_score_review_threshold: 60 },
}],
});
console.log(result);ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()
result, err := client.Workflows.Create(ctx, didit.SimpleWorkflowRequest{
WorkflowLabel: didit.String("Standard KYC"),
Features: []didit.SimpleWorkflowFeature{{
Feature: "OCR",
Config: didit.Some(map[string]any{"duplicated_user_action": "review"}),
}, {
Feature: "LIVENESS",
Config: didit.Some(map[string]any{"face_liveness_method": "passive"}),
}, {
Feature: "FACE_MATCH",
Config: didit.Some(map[string]any{"face_match_score_decline_threshold": 40, "face_match_score_review_threshold": 60}),
}},
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", result)import java.util.List;
import java.util.Map;
import me.didit.Didit;
import me.didit.types.SimpleWorkflowFeature;
import me.didit.types.SimpleWorkflowRequest;
// Reads DIDIT_API_KEY.
Didit client = new Didit();
var result = client.workflows().create(SimpleWorkflowRequest.builder()
.workflowLabel("Standard KYC")
.features(List.of(
SimpleWorkflowFeature.builder()
.feature(SimpleWorkflowFeature.Feature.of("OCR"))
.config(Map.of("duplicated_user_action", "review"))
.build(),
SimpleWorkflowFeature.builder()
.feature(SimpleWorkflowFeature.Feature.of("LIVENESS"))
.config(Map.of("face_liveness_method", "passive"))
.build(),
SimpleWorkflowFeature.builder()
.feature(SimpleWorkflowFeature.Feature.of("FACE_MATCH"))
.config(Map.of("face_match_score_decline_threshold", 40, "face_match_score_review_threshold", 60))
.build()))
.build());
System.out.println(result);<?php
require 'vendor/autoload.php';
use Didit\DiditClient;
// Reads DIDIT_API_KEY.
$didit = new DiditClient();
$result = $didit->workflows->create([
'workflow_label' => 'Standard KYC',
'features' => [[
'feature' => 'OCR',
'config' => ['duplicated_user_action' => 'review'],
], [
'feature' => 'LIVENESS',
'config' => ['face_liveness_method' => 'passive'],
], [
'feature' => 'FACE_MATCH',
'config' => ['face_match_score_decline_threshold' => 40, 'face_match_score_review_threshold' => 60],
]],
]);
print_r($result->toArray());require "didit"
# Reads DIDIT_API_KEY.
didit = Didit::Client.new
result = didit.workflows.create(
workflow_label: "Standard KYC",
features: [{
feature: "OCR",
config: { duplicated_user_action: "review" },
}, {
feature: "LIVENESS",
config: { face_liveness_method: "passive" },
}, {
feature: "FACE_MATCH",
config: { face_match_score_decline_threshold: 40, face_match_score_review_threshold: 60 },
}]
)
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.Workflows.CreateAsync(new SimpleWorkflowRequest
{
WorkflowLabel = "Standard KYC",
Features = new SimpleWorkflowFeature[]
{
new()
{
Feature = "OCR",
Config = new Dictionary<string, object> { ["duplicated_user_action"] = "review" },
},
new()
{
Feature = "LIVENESS",
Config = new Dictionary<string, object> { ["face_liveness_method"] = "passive" },
},
new()
{
Feature = "FACE_MATCH",
Config = new Dictionary<string, object> { ["face_match_score_decline_threshold"] = 40, ["face_match_score_review_threshold"] = 60 },
},
},
});
Console.WriteLine(JsonSerializer.Serialize(result));{
"uuid": "c3d4e5f6-7890-12cd-ef34-333333333333",
"workflow_id": "c3d4e5f6-7890-12cd-ef34-333333333333",
"workflow_label": "Standard KYC",
"workflow_type": null,
"is_default": false,
"is_archived": false,
"total_price": 0.15,
"min_price": 0.15,
"max_price": 0.15,
"features": "OCR + LIVENESS + FACE_MATCH",
"is_simple_workflow": false,
"is_editable": false,
"workflow_url": "https://verify.didit.me/u/w9TkPOx8RWG3UAz5ZRQGVQ",
"workflow_graph": {
"start_node": "ocr",
"nodes": "... one node per feature plus a final status node ..."
},
"max_retry_attempts": 3,
"retry_window_days": 7,
"session_expiration_time": 604800,
"version": 1,
"status": "published",
"published_at": "2026-05-17T10:30:00Z",
"created_at": "2026-05-17T10:30:00Z",
"updated_at": "2026-05-17T10:30:00Z"
}
Usa questo endpoint per creare workflow tramite API senza costruire tu stesso i nodi del grafo del workflow. Invia un array
L’ordine delle funzionalità è importante. Ad esempio, inserisci
L’oggetto
Questo grafo usa
Per esprimere “l’NFC non è stato eseguito per nessun motivo noto”, usa
Ogni campo configurato diventa un valore utilizzabile in una ramificazione,
Un grafo non valido risponde con
Il nodo finale usa
features nell’ordine in cui gli utenti devono completare i controlli. Didit lo converte internamente in un workflow basato su nodi e aggiunge automaticamente il passaggio finale di stato.
Questo endpoint POST /v3/workflows/ crea solo workflow semplici e lineari, cioè un elenco piatto di features. Per ramificazioni, instradamento condizionale, Document AI e nodi di rifiuto o decisione, usa il formato a grafo descritto di seguito. Questo formato alimenta il builder visuale della console e gli strumenti workflow del Didit MCP.
Consulta Configurazioni delle funzionalità del workflow per ogni campo config accettato da ciascuna funzionalità.
Workflow KYC di base
{
"workflow_label": "Standard KYC",
"features": [
{
"feature": "OCR",
"config": {
"documents_allowed": {
"USA": {
"DL": {
"enabled": 1,
"sides": 2
}
}
},
"duplicated_user_action": "REVIEW"
}
},
{
"feature": "LIVENESS",
"config": {
"face_liveness_method": "PASSIVE"
}
},
{
"feature": "FACE_MATCH"
}
]
}
Workflow del questionario
Crea prima il questionario conPOST /v3/questionnaires/. Poi usa il questionnaire_id restituito come questionnaire_uuid.
{
"workflow_label": "Source of Funds",
"features": [
{
"feature": "QUESTIONNAIRE",
"config": {
"questionnaire_uuid": "11111111-2222-3333-4444-555555555555",
"review_questionnaire_manually": true
}
}
]
}
OCR prima di FACE_MATCH, NFC, DATABASE_VALIDATION o dei controlli AML sugli utenti che dipendono dai dati del documento.
Riferimento della configurazione delle funzionalità
Ogni elemento difeatures[] ha questa struttura:
{
"feature": "OCR",
"label": "ID Verification",
"config": {}
}
config esatto dipende dalla funzionalità. Consulta l’elenco completo dei campi, i valori predefiniti, le impostazioni obbligatorie, gli intervalli di valori ed esempi in Configurazioni delle funzionalità del workflow.
Per OCR, ometti config.documents_allowed, invia null oppure invia {} per consentire ogni tipo di documento supportato. Includilo solo se vuoi limitare il workflow a paesi o tipi di documento specifici. Per QUESTIONNAIRE, config.questionnaire_uuid è obbligatorio.
Impostazioni opzionali del workflow
Puoi includere questi campi di primo livello quando crei un workflow per controllare il comportamento delle sessioni. Sono tutti facoltativi e, se omessi, vengono usati i valori predefiniti del workflow.| Campo | Tipo | Descrizione |
|---|---|---|
is_white_label_enabled | booleano | Abilita la personalizzazione White label per le sessioni create con questo workflow. Predefinito false. |
is_desktop_allowed | booleano | Consente l’esecuzione del flusso di verifica sui browser desktop. Predefinito false. |
max_retry_attempts | intero (0–10) | Numero massimo di nuovi tentativi consentiti dopo una verifica rifiutata. 0 blocca l’utente dopo il primo rifiuto. Predefinito 3. |
retry_window_days | intero (1–365) o null | Finestra mobile in giorni usata per contare i nuovi tentativi (null = limite complessivo senza finestra temporale). Predefinito 7. |
session_expiration_time | intero (3600–2419200) | Secondi prima che una sessione non completata scada. Minimo 1 ora, massimo 4 settimane. Predefinito 604800 (7 giorni). |
response_attributes | oggetto o null | Limita i campi restituiti per ogni funzionalità, ad esempio {"id_verifications": ["full_name", "document_number"], "face_matches": null}. null o una chiave mancante restituisce tutti i campi. Un elenco vuoto restituisce solo status, warnings, node_id, is_nfc_skipped e skip_reason, mentre gli altri campi vengono restituiti come null. |
{
"workflow_label": "Standard KYC",
"is_white_label_enabled": true,
"is_desktop_allowed": true,
"max_retry_attempts": 5,
"retry_window_days": 14,
"session_expiration_time": 86400,
"features": [
{ "feature": "OCR" },
{ "feature": "LIVENESS" },
{ "feature": "FACE_MATCH" }
]
}
Grafo dei flussi con ramificazioni e nodi
Una listafeatures lineare non può esprimere “se X allora Y”. Per le ramificazioni condizionali (rifiutare in base a uno stato, instradare in base a un campo estratto, far dipendere un passaggio da una corrispondenza), un passaggio di richiesta di Document AI o i nodi terminali di rifiuto/decisione, i flussi di Didit usano un grafo di nodi: la stessa struttura prodotta dal builder visuale della console.
Il modo più semplice per costruire un flusso a grafo è il Didit MCP: chiedi a un agente in linguaggio naturale (“dopo la verifica dell’identità, se la professione è ≈ ‘Software Engineer’, aggiungi un passaggio di prova dei fondi”) e lui costruirà, convaliderà e salverà il grafo per te. La struttura descritta di seguito è quella prodotta da questi strumenti e dalla console.
Struttura del grafo
Un grafo è{ start_node, nodes }. nodes è una mappa dall’ID del nodo al nodo. Gli archi sono impliciti: ogni nodo punta in avanti tramite next (incondizionato) e/o branches[].goto (condizionato).
| Tipo di nodo | Struttura |
|---|---|
feature | { "node_type": "feature", "feature": "OCR", "config": {…}, "next": "<id>", "branches": [] } |
branch | { "node_type": "branch", "branches": [ { "id", "logic": "and"|"or", "rules": [<rule>], "goto": "<id>" } ], "next": "<fallback id>" } |
status (terminale) | { "node_type": "status", "session_status": "Approved"|"Declined"|"In Review"|"Determine" } |
action | { "node_type": "action", "actions": [ { "type": "add_tag"|"add_review"|… } ], "next": "<id>" } |
webhook | { "node_type": "webhook", "config": { "url", "method" }, "branches": [], "next": "<id>" } |
start_node deve essere un nodo di tipo feature. I rami vengono valutati in ordine e vince il primo che corrisponde; un rules: [] vuoto è il ramo generico “altrimenti” (va messo per ultimo). session_status: "Determine" decide automaticamente in base all’esito combinato delle funzionalità.
Ogni nodo di tipo branch deve avere un ramo “altrimenti” esplicito: un ramo con
rules: [] che instrada le sessioni che non corrispondono a nessuna delle condizioni. Non affidarti al next del nodo branch come fallback: un next isolato viene visualizzato come un arco ambiguo nel generatore visuale ed è facile da dimenticare. Quando invii un nodo branch con un next e senza un ramo “altrimenti” esplicito, l’API converte quel next in un ramo “altrimenti” esplicito al posto tuo (quindi { …, "branches": [<conditions>], "next": "liveness" } viene salvato come branches: [<conditions>, { "id": "else", "rules": [], "goto": "liveness" }]). Scrivi tu il ramo “altrimenti” per essere esplicito: la conversione è una rete di sicurezza, non un sostituto.Regole di ramificazione e operatori
Ogni regola confronta un campo con un valore tramite un operatore:{ "field": "kyc.extra_fields.profession", "operator": "fuzzy_match", "value": "Software Engineer", "score": 80 }
- I campi indicano un esito di una funzionalità (
kyc.status,aml.status,document_ai.status,face_match.score, …) oppure un valore estratto (kyc.full_name,kyc.age,kyc.nationality,kyc.extra_fields.profession, un campo di Document AIdocument_ai.<key>,expected_details.*). Un ramo può leggere solo un campo la cui funzionalità sia stata eseguita su ogni percorso che porta al ramo stesso. - Operatori:
equals,not_equals,greater_than(_or_equals),less_than(_or_equals),contains,not_contains,in,not_in,is_empty,is_not_empty,regexefuzzy_match(solo per campi stringa; richiede unscoreda 0 a 100, cioè una soglia di somiglianza, ad esempio professione simile almeno all’80% a “Software Engineer”).
Ramificazione in base al motivo per cui l’NFC non è stato eseguito
Dopo un nodoNFC, usa nfc.skip_reason con equals o in per instradare le sessioni in base al motivo per cui la lettura del chip non è avvenuta. Il campo ha questi sette valori stabili:
USER_SKIPPEDDOCUMENT_WITHOUT_CHIPCHIP_CERTIFICATE_UNAVAILABLEDEVICE_WITHOUT_NFCINTEGRATION_WITHOUT_NFC_ACCESSMRZ_KEY_UNAVAILABLEJPKI_UNAVAILABLE
nfc.skip_reason è null, quindi né una regola equals né una regola in per un motivo di salto corrispondono.
Il campo viene risolto anche per i nodi NFC saltati a causa di un controllo. Questo include i casi in cui non esistono né un report né un avviso NFC, e i casi in cui allow_nfc_skip è false ma il gate sul documento o sul dispositivo impedisce l’esecuzione dell’NFC. Puoi quindi instradare queste sessioni senza fare affidamento su una voce di nfc_verifications[].
Le sessioni memorizzate prima che la capacità NFC diventasse tri-stato possono avere
has_device_nfc_support: false. Una sessione web meno recente può quindi risolversi in DEVICE_WITHOUT_NFC invece che in INTEGRATION_WITHOUT_NFC_ACCESS.equals per il salto dell’utente, in per i salti dovuti a gate o capacità, e un ramo “altrimenti” esplicito per l’NFC riuscito. Il ramo si trova dopo il nodo NFC, e ogni destinazione punta in avanti verso un nodo terminale:
{
"start_node": "ocr",
"nodes": {
"ocr": {
"node_type": "feature",
"feature": "OCR",
"next": "nfc"
},
"nfc": {
"node_type": "feature",
"feature": "NFC",
"config": { "allow_nfc_skip": false },
"next": "route_nfc"
},
"route_nfc": {
"node_type": "branch",
"branches": [
{
"id": "user_skipped",
"logic": "and",
"rules": [
{ "field": "nfc.skip_reason", "operator": "equals", "value": "USER_SKIPPED" }
],
"goto": "manual_review"
},
{
"id": "nfc_unavailable",
"logic": "and",
"rules": [
{
"field": "nfc.skip_reason",
"operator": "in",
"value": [
"DOCUMENT_WITHOUT_CHIP",
"CHIP_CERTIFICATE_UNAVAILABLE",
"DEVICE_WITHOUT_NFC",
"INTEGRATION_WITHOUT_NFC_ACCESS",
"MRZ_KEY_UNAVAILABLE",
"JPKI_UNAVAILABLE"
]
}
],
"goto": "manual_review"
},
{
"id": "else",
"logic": "and",
"rules": [],
"goto": "approved"
}
]
},
"manual_review": { "node_type": "status", "session_status": "In Review" },
"approved": { "node_type": "status", "session_status": "Approved" }
}
}
in con tutti e sette i valori. Mantieni un ramo “altrimenti” esplicito per l’NFC riuscito (nfc.skip_reason: null) e per qualsiasi valore futuro che il tuo grafo non riconosce ancora.
Document AI (ad esempio prova dei fondi)
Un nodo di funzionalitàDOCUMENT_AI richiede uno o più documenti ed estrae campi denominati:
{
"node_type": "feature",
"feature": "DOCUMENT_AI",
"label": "Proof of Funds",
"config": {
"document_ai_documents": [
{
"document_key": "proof_of_funds",
"title": "Proof of Funds",
"description": "Upload a recent bank statement.",
"fields": [
{
"key": "account_holder",
"name": "Account holder",
"instruction": "The full name of the account holder as printed on the statement.",
"type": "text",
"required": true,
"is_full_name": true
},
{
"key": "closing_balance",
"name": "Closing balance",
"instruction": "The closing balance amount.",
"type": "number",
"required": true
}
]
}
],
"document_ai_missing_required_fields_action": "REVIEW",
"document_ai_name_mismatch_action": "REVIEW"
},
"next": "final_decision"
}
document_ai.<key>, e l’esito del passaggio è document_ai.status.
Imposta "is_full_name": true sul campo che contiene il nome completo del titolare del documento. Il suo valore estratto viene confrontato con il nome completo dell’identità verificata (il nome ottenuto tramite OCR o verifica dell’identità, oppure i dettagli attesi della sessione), e document_ai_name_mismatch_action decide cosa succede in caso di mancata corrispondenza sotto document_ai_name_match_score_threshold. Il flag è facoltativo: un documento può non contrassegnare alcun campo, e al massimo un campo per documento può impostarlo. Consulta Configurazioni delle funzionalità dei flussi → Document AI per ogni campo di configurazione di Document AI.
Endpoint e ciclo di vita della bozza
La modifica del grafo avviene per applicazione e usa gli endpoint della console e della gestione (Bearer dell’utente +read:workflows/write:workflows). Un grafo può essere modificato solo su una versione in bozza, quindi il ciclo di vita è crea bozza → imposta grafo → pubblica:
| Metodo | Percorso | Scopo |
|---|---|---|
GET | …/verification-settings/{settings_uuid}/workflow-graph/ | Grafo attuale + status/is_editable |
POST | …/application/{app}/workflow-graph/validate/ (body { "graph": … }) | Validazione di prova (simulazione) |
GET | …/application/{app}/workflow-graph/field-definitions/ | Campi utilizzabili nei rami e operatori validi |
POST | …/verification-settings/{settings_uuid}/create-draft/ | Bozza modificabile a partire da una versione pubblicata |
PUT | …/verification-settings/{settings_uuid}/workflow-graph/ (body { "graph": … }) | Salvare il grafo |
PATCH | …/verification-settings/{settings_uuid}/ (body { "status": "published" }) | Pubblicare la bozza |
Avvisi di validazione
L’endpoint di validazione risponde con{ "is_valid": true, "graph": …, "warnings": [] }. Un avviso è consultivo: il grafo è valido, può essere salvato e pubblicato anche in presenza di avvisi. Ogni voce indica il nodo di ramo e il braccio a cui si riferisce, così chi costruisce il flusso può individuare con precisione la condizione:
{
"type": "branch_outcome_contradiction",
"node_id": "after_ocr",
"branch_id": "b1",
"severity": "warning",
"message": "Branch 1 only matches sessions where ID Verification Status is Approved or In Review, but every path from it ends in the session outcome \"Declined\". Check the condition or the outcome.",
"params": { "branchNumber": 1, "field": "ID Verification Status", "allowed": "Approved or In Review", "outcome": "Declined" }
}
type | Significato |
|---|---|
branch_outcome_contradiction | La condizione del braccio e l’esito che ogni percorso da esso raggiunge sono in contrasto. Ad esempio, kyc.status NOT EQUALS Declined instradato verso un esito Declined. L’esito può trovarsi anche diversi passaggi più avanti nel percorso. |
branch_condition_unreachable | Il braccio non può mai corrispondere, perché ogni percorso che raggiunge questo ramo limita già il campo di stato a valori che la condizione esclude. |
else_branch_unreachable | Il braccio else non può mai essere eseguito: gli altri bracci coprono già tutti i valori che il campo può assumere in questo punto. |
400 includendo errors e un elenco warnings redatto al meglio. Solo errors bloccano il salvataggio.
Esempio svolto: indirizzare gli ingegneri del software verso la prova dei fondi
Dopo la verifica dell’identità: se è stata rifiutata, rifiuta la sessione; se la professione del titolare ≈ “Software Engineer” (somiglianza ≥80%), richiedi un documento di prova dei fondi; poi prendi una decisione finale.
{
"start_node": "ocr_1",
"nodes": {
"ocr_1": { "node_type": "feature", "feature": "OCR", "label": "ID Verification", "next": "after_ocr" },
"after_ocr": {
"node_type": "branch",
"label": "Route after ID verification",
"branches": [
{ "id": "declined", "logic": "or", "rules": [ { "field": "kyc.status", "operator": "equals", "value": "Declined" } ], "goto": "decline" },
{ "id": "software_engineer", "logic": "and", "rules": [ { "field": "kyc.extra_fields.profession", "operator": "fuzzy_match", "value": "Software Engineer", "score": 80 } ], "goto": "proof_of_funds" },
{ "id": "else", "logic": "and", "rules": [], "goto": "final_decision" }
]
},
"proof_of_funds": {
"node_type": "feature",
"feature": "DOCUMENT_AI",
"label": "Proof of Funds",
"config": {
"document_ai_documents": [
{ "document_key": "proof_of_funds", "title": "Proof of Funds", "description": "Upload a recent bank statement.",
"fields": [
{ "key": "account_holder", "name": "Account holder", "type": "text", "required": true },
{ "key": "closing_balance", "name": "Closing balance", "type": "number", "required": true }
] }
],
"document_ai_missing_required_fields_action": "REVIEW"
},
"next": "final_decision"
},
"final_decision": { "node_type": "status", "session_status": "Determine", "label": "Final decision" },
"decline": { "node_type": "status", "session_status": "Declined", "label": "Declined" }
}
}
session_status: "Determine", che decide automaticamente (approva / rifiuta / in revisione) in base alle funzionalità effettivamente eseguite nella sessione. Così sia il percorso della prova dei fondi sia quello else si risolvono correttamente, senza che alcun ramo legga document_ai.status (che non esiste nel percorso che salta Document AI). Ricorda: un ramo può leggere solo un campo la cui funzionalità è stata eseguita su ogni percorso che lo raggiunge.
Invia il grafo come { "graph": <above> } all’endpoint …/workflow-graph/ (prima convalida). Per creare un nuovo workflow da zero usa didit_workflow_set_graph dell’MCP; per modificare un workflow esistente usa didit_workflow_edit_graph (piccole operazioni che conservano i nodi esistenti e le liste di elementi consentiti). Vedi Didit MCP.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
application/json
Crea un workflow lineare semplice. L'API converte internamente questo elenco di funzionalità in un grafo di workflow basato su nodi. Whitelist dei campi RIGIDA: qualsiasi chiave non presente in questo elenco (incluso workflow_type) viene rifiutata con un 400.
Funzionalità di verifica in ordine di esecuzione. L'API collega ciascun elemento a quello successivo e aggiunge automaticamente un nodo di stato finale.
Minimum array length:
1Show child attributes
Show child attributes
Nome visualizzato per il workflow (massimo 50 caratteri). Il valore predefinito è "ID Verification" se omesso: impostalo sempre affinché i workflow rimangano distinguibili.
Maximum string length:
50Esempio:
"Standard KYC"
Imposta questo workflow come predefinito per le nuove sessioni.
Ometti questo campo per creare un workflow pubblicato pronto per le sessioni. Usa draft solo quando vuoi salvare senza pubblicare.
Opzioni disponibili:
draft, published Abilita la personalizzazione White label per le sessioni create con questo workflow.
Consenti l'esecuzione del flusso di verifica sui browser desktop.
Numero massimo di nuovi tentativi consentiti dopo una verifica rifiutata. 0 blocca l'utente dopo il primo rifiuto.
Intervallo richiesto:
0 <= x <= 10Finestra mobile in giorni utilizzata per contare i nuovi tentativi. null applica un limite complessivo.
Intervallo richiesto:
1 <= x <= 365Numero massimo di invii per il rilevamento della vitalità per sessione. Valore predefinito 3: un tentativo iniziale più due nuovi tentativi. Questo valore viene copiato anche nei nodi di workflow generati per il rilevamento della vitalità e la stima dell'età, a meno che la configurazione a livello di funzionalità non lo sovrascriva.
Intervallo richiesto:
1 <= x <= 3Numero massimo di invii per il confronto facciale per sessione. Valore predefinito 3: un tentativo iniziale più due nuovi tentativi. Questo valore viene copiato anche nei nodi di workflow generati per il confronto facciale, a meno che la configurazione a livello di funzionalità non lo sovrascriva.
Intervallo richiesto:
1 <= x <= 3Secondi prima della scadenza di una sessione non completata. Minimo 1 ora (3600), massimo 4 settimane (2419200).
Intervallo richiesto:
3600 <= x <= 2419200Risposta
Workflow creato. Il corpo della risposta contiene l'INTERA configurazione del workflow — la stessa serializzazione non elaborata di VerificationSettings restituita da GET /v3/workflows/{settings_uuid}/ (~190 campi: ogni toggle di funzionalità, soglia, azione e il workflow_graph generato), non l'elemento sintetico dell'elenco. Salva lo uuid (esposto anche come workflow_id) per poterlo referenziare nelle successive chiamate di creazione della sessione. Nota: features è una stringa unita da " + " e i prezzi sono numeri JSON.
I campi sottostanti sono tipizzati; l'oggetto contiene inoltre ogni altra colonna della configurazione del workflow (attivazione delle funzionalità, soglie, azioni di avviso, documenti consentiti, callback) come proprietà aggiuntive. I campi non applicabili al workflow_type sono null.
Identificativo per versione (settings_uuid). Ogni versione di un workflow ha il proprio.
Identificatore stabile condiviso da tutte le versioni del workflow. Le sessioni create con esso utilizzano l'ultima versione pubblicata.
Nome visualizzato del workflow.
Modello di workflow. null per i workflow a grafo creati senza un modello.
Opzioni disponibili:
kyc, kyb, adaptive_age_verification, biometric_authentication, address_verification, questionnaire_verification, email_verification, phone_verification, null Indica se questo è il workflow predefinito dell'applicazione.
I workflow archiviati non possono avviare nuove sessioni.
Numero di versione all'interno del workflow.
Le versioni in bozza sono modificabili; le versioni pubblicate sono immutabili e utilizzate per le nuove sessioni.
Opzioni disponibili:
draft, published Quando è stata pubblicata questa versione. null per le bozze.
true quando il workflow non presenta un workflow_graph personalizzato.
true solo per le versioni draft.
URL pubblico che avvia una sessione con questo workflow.
Struttura a grafo del workflow (nodi e archi). null per i workflow semplici.
Funzionalità abilitate unite con " + ", ad esempio "OCR + LIVENESS".
Prezzo per sessione; per i workflow a grafo, il percorso più costoso.
Prezzo del percorso più economico all'interno del workflow.
Prezzo del percorso più costoso all'interno del workflow.
Prezzi delle funzionalità aggiuntive specifici per l'organizzazione, oppure null se non ne è impostato alcuno.
Nuovi tentativi consentiti dopo una verifica rifiutata.
Giorni durante i quali sono consentiti i nuovi tentativi.
Secondi prima della scadenza di una sessione non completata.
Il questionario associato al workflow, o null.
Impostazioni di verifica per ruolo per le persone chiave KYB.
Quali livelli di Firma elettronica possono essere utilizzati per firmare in questo momento. Verificalo prima di impostare signature_level. Restituito nei workflow kyc, kyb e a grafo.
Show child attributes
Show child attributes
Indica se un workflow semplice di KYC o KYB esegue la verifica bancaria. Viene eseguita dopo i passaggi di contatto (e la verifica della posizione geografica) e prima della validazione su database, dello screening AML e dell'analisi IP. La verifica bancaria non è ancora disponibile a livello generale: l'attivazione viene rifiutata ovunque non sia abilitata.
Impostazioni della verifica bancaria di un workflow semplice, con le stesse chiavi accettate da un nodo BANK_VERIFICATION (ad esempio bank_countries e bank_method_order). Le chiavi sconosciute vengono ignorate. Ogni chiave è facoltativa e una chiave assente mantiene il proprio valore predefinito, pertanto {} indica tutti i valori predefiniti. Consulta Impostazioni della verifica bancaria.
Esempio:
{}
Indica se un semplice workflow KYC esegue la verifica della posizione geografica. Viene eseguita dopo i passaggi di contatto e prima della verifica bancaria e della validazione su database. I workflow aziendali (KYB) non possono eseguirla.
Impostazioni di verifica della posizione di un workflow semplice, con le stesse chiavi accettate da un nodo GEOLOCATION (ad esempio is_geolocation_geofencing_enabled e geolocation_max_attempts). Le chiavi sconosciute vengono ignorate. Ogni chiave è facoltativa e una chiave assente mantiene il valore predefinito, quindi {} indica tutti i valori predefiniti.
Esempio:
{}
Ultima modifica il 7 novembre 2026