Vai al contenuto principale
POST
Python
Sottoponi identificatori digitati e attributi di identità dichiarati, seleziona i controlli da eseguire e verifica separatamente ciascun risultato. Usa prima Pianifica un controllo antifrode per controllare i requisiti di input e i costi stimati.

Scegli un profilo

Fissa profile_version in modo che i valori predefiniti selezionati e la politica decisionale siano espliciti. Il profilo predefinito è standard, versione 2026-08-27. La versione 2026-09-14 aggiunge l’arricchimento sociale facoltativo di email e telefono e registra ogni controllo completato come sessione nativa di Verifica degli utenti. In questa versione, i componenti aggiuntivi a pagamento sono facoltativi e devono essere attivati esplicitamente. La versione 2026-09-14.1 abilita anche le ricerche di identificatori nella rete globale antifrode per le organizzazioni con piano Enterprise che condividono dati a livello globale. La versione 2026-09-14.2 aggiunge un controllo facoltativo di riferimento tra selfie e CPF per il Brasile. Le versioni precedenti mantengono il loro comportamento originale. I profili attuali supportano il rischio email, il rischio telefono, il rischio IP, la validazione su database idonea e la cronologia di rete privata della tua applicazione. L’associazione d’identità basata su selfie richiede la versione 2026-09-14.2. Se la selezioni nelle versioni precedenti, viene restituito not_available_in_profile_version.

Identità dichiarata e contesto

Inserisci email, telefono e identificativi governativi in subject.identifiers. Gli identificativi governativi richiedono il paese di emissione; in alcuni casi può essere necessario anche l’ente emittente, quando i numeri sono univoci solo all’interno di una regione. Inserisci nomi, data di nascita, nazionalità e indirizzo in subject.attributes. Sono affermazioni da confrontare laddove una fonte selezionata lo consenta, non fatti verificati solo perché sono stati inviati. Usa context per l’indirizzo IP del tentativo, lo user agent, la finalità, il paese e qualsiasi dichiarazione di consenso richiesta. In questo modo si separano le informazioni sul tentativo di verifica da quelle sulla persona. Per i controlli biometrici supportati, fornisci subject.selfie come JPEG, PNG o WebP codificato in base64, fino a 6 MB. È accettato anche un data URI di immagine corrispondente. Non inviare un’immagine di riferimento, un URL remoto o una chiave di archiviazione.

Selfie e identificativo dichiarato

Seleziona biometric_identity, invia un identificativo tax_number brasiliano e un selfie, e conferma context.consent_obtained. Il controllo di riferimento verifica che quel selfie appartenga al titolare del CPF dichiarato. Se il consenso manca, viene restituito consent_required; per i paesi non supportati viene restituito unsupported_region. Il modulo ha un prezzo per controllo basato sulla tariffa di validazione su database della tua organizzazione; consulta il piano prima di eseguirlo. Quando il riferimento risponde, identity_relationship.result è match, mismatch o inconclusive. Una risposta inconcludente richiede una revisione e non viene mai trattata come una mancata corrispondenza. Il risultato stabilisce solo la relazione tra selfie e CPF. Non convalida un nome o una data di nascita inviati, non dimostra la vitalità e non cerca un volto su internet o nella rete globale antifrode. Nomi e data di nascita restano affermazioni, a meno che un’altra fonte selezionata non fornisca prove per quei campi. Timeout ed errori della fonte sono risultati non disponibili e non vengono addebitati. Le risposte inconcludenti completate vengono addebitate alla stessa tariffa del controllo di riferimento. Questo controllo non include il selfie nel risultato e non lo memorizza come contenuto multimediale della sessione.

Seleziona i controlli

checks.include seleziona i moduli, e checks.exclude ha la precedenza. Un elenco include esplicitamente vuoto disattiva tutte le attività facoltative; la normalizzazione viene comunque eseguita. Se ometti include, vengono usati i valori predefiniti del profilo fissato. L’arricchimento sociale di email e telefono si seleziona separatamente con email_social e phone_social. Richiedono un identificativo valido e corrispondente e non inviano un OTP.

Leggi i risultati senza confonderli

Ogni modulo riporta lo stato di esecuzione, il motivo e le unità fatturabili. not_requested, excluded_by_caller, missing_required_input e source_unavailable descrivono esiti diversi. Una fonte mancante non equivale a una mancata corrispondenza dell’identità né a un risultato di rischio zero. attribute_evidence descrive le prove a livello di campo, mentre risk mantiene separate le dimensioni di identità, contatto, dispositivo, comportamento e rete antifrode. Un’email, un dispositivo o un altro identificativo condiviso è una connessione osservata, non una prova che due account appartengano alla stessa persona o che sia stata commessa una frode. recommendation è la raccomandazione del controllo; non modifica lo stato di un altro record. I risultati dell’arricchimento sociale compaiono in enrichment, con i risultati non disponibili distinti da quelli completati.

Rete globale antifrode

Seleziona networks_cross_org per interrogare sulla rete condivisa gli identificatori supportati di email e telefono e gli identificatori di documento con il namespace corretto. La ricerca richiede il piano Enterprise e che la modalità di condivisione della tua organizzazione sia impostata su global. In caso contrario, il piano segnala il modulo con available: false e availability_reason: "entitlement_required", e un controllo che lo seleziona lo salta con stato skipped e motivo entitlement_required. Lo stesso motivo si applica quando Networks non è abilitato per la tua organizzazione. Le applicazioni sandbox non sono soggette al piano né alla modalità di condivisione: con un identificatore supportato, il modulo viene eseguito e restituisce un risultato campione vuoto. La ricerca utilizza il budget di letture esistente dell’organizzazione e registra la lettura nel registro di audit. Non prevede alcun addebito per ricerca. Pianificare un controllo non interroga l’indice condiviso e non consuma il suo budget di letture. network.cross_organization contiene signals_checked e gli insights aggregati e divulgati, quando il controllo è completato. Ogni insight contiene il tipo di segnale, le classi di esito, il numero di contributori, l’intervallo di recenza e, solo se la divulgazione è attiva, le categorie di settore. Non identifica mai un’altra organizzazione, un account, una persona o una verifica. I risultati sotto la soglia di divulgazione vengono omessi; un elenco vuoto non dimostra l’assenza di storico di frodi. Un segnale condiviso divulgato attiva una raccomandazione di revisione, mai un rifiuto automatico né una corrispondenza di identità. Una ricerca non disponibile riporta il proprio motivo separatamente da una ricerca completata senza risultati. Se la tua organizzazione perde in seguito l’accesso alla rete tra organizzazioni, ad esempio dopo un cambio di piano o quando la condivisione non è più global, il recupero dei risultati, i nuovi tentativi e i dettagli della sessione nascondono gli aggregati condivisi e le relative evidenze di rischio derivate. La raccomandazione originale resta una decisione storica; le letture non modificano lo stato della verifica.

Sessioni, nuovi tentativi e addebiti

check_id recupera il risultato memorizzato tramite Ottieni un controllo antifrode. Quando è presente, request_id identifica la sessione di verifica nativa. Le versioni 2026-09-14, 2026-09-14.1 e 2026-09-14.2 creano sempre quella sessione, anche quando viene selezionata solo la cronologia della rete privata. Riutilizzare client_reference con lo stesso corpo della richiesta restituisce il risultato originale, senza una nuova esecuzione né un nuovo addebito, finché quel controllo esiste. Un corpo diverso con lo stesso riferimento restituisce 409. Se l’esecuzione è ancora in corso, ripeti la stessa richiesta dopo l’intervallo indicato in Retry-After nella risposta. Eliminare la verifica associata elimina anche il risultato del controllo antifrode; il recupero restituisce poi 404. Un controllo eliminato durante l’esecuzione non può pubblicare un risultato completato. I prezzi derivano dalle tariffe prepagate o contrattuali correnti della tua organizzazione. I moduli non disponibili e saltati non vengono fatturati, e la cronologia della rete privata non prevede alcun addebito per controllo. I controlli in sandbox usano risposte campione, senza chiamate a fornitori a pagamento né addebiti.

Autorizzazioni

x-api-key
string
header
obbligatorio

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

subject
object
obbligatorio
client_reference
string

Il tuo riferimento per questo controllo. Funziona anche come chiave di idempotenza: riutilizzarlo con lo stesso corpo della richiesta restituisce il controllo originale senza eseguire né fatturare nuovamente i moduli; riutilizzarlo con un corpo della richiesta diverso restituisce 409.

Required string length: 1 - 255
profile
string
predefinito:standard

ID del profilo di orchestrazione. Il valore predefinito è il profilo Didit standard.

Required string length: 1 - 64
profile_version
string

Fissa una versione bloccata del profilo. Il valore predefinito è la versione corrente del profilo.

Required string length: 1 - 32
context
object
checks
object
vendor_data
string
Maximum string length: 1000
metadata
any

Risposta

check_id
string<uuid>
obbligatorio
client_reference
string | null
obbligatorio
processing_status
enum<string>
obbligatorio
  • pending - In sospeso
  • running - In esecuzione
  • completed - Completato
  • failed - Non riuscito
Opzioni disponibili:
pending,
running,
completed,
failed
profile_id
string
obbligatorio
profile_version
string
obbligatorio
created_at
string<date-time>
obbligatorio
completed_at
string<date-time> | null
obbligatorio
inputs
object[]
obbligatorio
modules
object[]
obbligatorio
attribute_evidence
object[]
obbligatorio
compound_evidence
object[]
obbligatorio
risk
object[]
obbligatorio
network
object
obbligatorio
recommendation
enum<string>
obbligatorio
  • approve - Approva
  • review - Revisiona
  • reject - Rifiuta
Opzioni disponibili:
approve,
review,
reject
next_action
enum<string>
obbligatorio
  • none - Nessuno
  • manual_review - Revisione manuale
  • step_up - Passaggio a un livello superiore
  • resubmit_capture - Invia nuovamente l'acquisizione
Opzioni disponibili:
none,
manual_review,
step_up,
resubmit_capture
decision_reasons
string[]
obbligatorio
coverage
object
obbligatorio
usage
object[]
obbligatorio
request_id
string<uuid>

Sessione di verifica nativa creata per questo controllo.

enrichment
object
identity_relationship
object | null
vendor_data
string | null
metadata
unknown
Ultima modifica il 7 novembre 2026