> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # Validazione su database API: corrispondenza ID nazionale > Didit: validazione su database con POST /v3/database-validation/ su 100+ fonti nazionali e globali, matching waterfall 1x1 e 2x2. A consumo. ## Servizi basati sull'indirizzo Per i servizi che verificano un indirizzo di residenza o di utenza, puoi inviare un unico campo `address` e Didit lo suddividerà prima di eseguire il controllo. Per ottenere la migliore percentuale di corrispondenza, invia direttamente i campi strutturati dell'indirizzo di Didit: | Campo | Significato | | - | - | | `address_element_1` | Indirizzo stradale, incluso numero civico e tipo di via | | `address_element_2` | Facoltativo: interno, edificio, piano o riga aggiuntiva dell'indirizzo | | `address_element_3` | Quartiere, distretto, località o zona | | `address_element_4` | Città, comune, stato, provincia o regione | | `address_element_5` | Codice di avviamento postale (CAP) | I campi strutturati sostituiscono il valore del singolo campo `address`. `postal_code` è accettato come alias di `address_element_5`. ## Consenso Alcuni servizi di database richiedono il consenso esplicito dell'utente finale prima che il fornitore possa essere interrogato. Il catalogo dei servizi contrassegna queste righe con `requires_consent=true`. Invia `consent=true` quando il consenso dell'utente si applica ai servizi selezionati. Didit rifiuta la richiesta prima di qualsiasi chiamata al fornitore o evento di fatturazione se un servizio selezionato richiede il consenso e tu non lo invii. ## Caricamento dei file La validazione su database utilizza `multipart/form-data`. I servizi biometrici che richiedono `selfie` la espongono come campo di caricamento file nel playground delle API, così puoi selezionare direttamente un'immagine invece di incollare un percorso o una stringa base64. Nel codice, carica il file con la sintassi multipart standard: ```bash theme={null} -F "selfie=@./selfie.jpg" ``` ## Errori di validazione Didit convalida i campi obbligatori, la struttura dell'indirizzo e i formati specifici di ciascun servizio prima di chiamare il fornitore. Ad esempio, i servizi di registro cinesi come `chn_national_id` e `chn_passport_verification` si aspettano `full_name` nel sistema di scrittura cinese originale, e `chn_national_id` richiede inoltre un numero di identità nazionale cinese valido di 15 o 18 caratteri con una cifra di controllo corretta. Se una richiesta non può essere eseguita, l'API restituisce errori espliciti sui campi e non viene addebitato alcun utilizzo. Se si verifica un errore del fornitore dopo il controllo preliminare, la risposta include `validation_errors`, e le richieste API salvate memorizzano tali errori nel risultato della validazione su database. ## Input rifiutato e risultati non disponibili Quando nessun servizio restituisce un risultato utilizzabile, controlla ogni voce di `validation_errors` prima di decidere se riprovare. Lo stato HTTP da solo non determina se un nuovo tentativo sia appropriato. Una risposta `400` con `code: "provider_rejected_input"` e `retryable: false` significa che ogni tentativo che non ha prodotto una risposta ha esplicitamente rifiutato l'input. Correggi i dati forniti prima di riprovare. Questi tentativi non vengono fatturati. Una risposta `502` con `code: "empty_provider_response"` e `retryable: true` significa che il servizio non è riuscito a produrre un risultato utilizzabile per un altro motivo. Rientrano in questo caso un input rifiutato seguito da un fallback non disponibile oppure un fallback che non fornisce alcuna spiegazione. Riprova più tardi; la risposta non stabilisce che l'input sia errato. Se un database continua a non funzionare, Didit invia un'email alle organizzazioni che lo hanno usato di recente, quando l'interruzione persiste, e di nuovo quando controlli reali confermano che risponde nuovamente — vedi [Notifiche di disponibilità](https://docs.didit.me/it/core-technology/database-validation/overview.md#notifiche-di-disponibilità). Quando solo alcuni dei servizi selezionati non funzionano, la richiesta riesce comunque: la risposta è `200` e i servizi non riusciti sono elencati in `database_validation.errors[]`, ciascuno con gli stessi campi `code` e `retryable`. `database_validation.status` segue quindi i servizi che hanno risposto e può essere `Approved`, perciò controlla `errors[]` in ogni risposta e non solo nelle risposte `4xx` o `5xx`. Un servizio segnalato lì non compare in `validations` e `services_used`, e non viene fatturato; riprova quel servizio da solo. Altri errori `502` possono richiedere un input corretto. Ad esempio, `provider_invalid_input` e `provider_validation_error` descrivono un input rifiutato dalla fonte e l'input non deve essere sottoposto a un nuovo tentativo senza modifiche, anche quando la risposta legacy non include `retryable`. Le indicazioni per i nuovi tentativi relative a `empty_provider_response` non si applicano a questi codici. Un risultato di mancata corrispondenza definitivo è un controllo completato, non un guasto di disponibilità. ## OpenAPI ````yaml it/openapi-25.json POST /v3/database-validation/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API di verifica dell'identità. Autenticati con l'intestazione x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/database-validation/: post: tags: - Standalone APIs summary: Validazione su database (indipendente) description: >- Valida i dati di identità di una persona confrontandoli con fonti governative e registri ufficiali — CPF in Brasile, RENAPER in Argentina, registri DNI in Spagna e Perù, INE in Messico e 100+ altri servizi in 60+ paesi. **Selezione dei servizi.** Ogni paese espone uno o più servizi di catalogo identificati da un `service_id` (ad es. `bra_cpf`, `arg_renaper`, `pan_cedula_sib`). Fissa i servizi desiderati con l'array `services` — se lo ometti, viene eseguito esattamente **un** servizio predefinito (il servizio attivo da più tempo per il paese). L'invio di `services` converte inoltre la risposta nel formato esteso con `services_used` e `match_score`. Scopri i servizi, i relativi campi obbligatori e i prezzi tramite `GET /v1/organization/database-validation-countries/` (un endpoint di catalogo non documentato in questa specifica) o tramite l'editor di workflow della Business Console. Alcuni servizi sono contrassegnati con `requires_consent=true` nel catalogo e richiedono `consent=true`; altri richiedono l'onboarding per la tua organizzazione prima di poter essere chiamati. **Campi di input.** `identification_number` è un campo universale che mappa automaticamente il campo corretto specifico per paese (vedi la sua descrizione). Le regole di formato del paese vengono applicate prima che venga chiamato qualsiasi provider (ad es. il CPF BRA deve essere composto esattamente da 11 cifre) e gli errori di formato non vengono mai fatturati. I servizi biometrici richiedono il caricamento di un `selfie` (solo multipart); RENAPER in Argentina richiede inoltre `gender`. **Risultati.** Ciascun servizio restituisce una mappa `validation` campo per campo e un `outcome_code` neutro rispetto al fornitore (`MATCH`, `PARTIAL_MATCH`, `NO_MATCH`, `DOCUMENT_NOT_FOUND`, `INVALID_DOCUMENT_FORMAT`, `INVALID_INPUT`, `MINOR_BLOCKED`, `DECEASED`, `BIOMETRIC_NO_MATCH`, `BIOMETRIC_IMAGE_UNUSABLE`, `INCONCLUSIVE`, `DOCUMENT_SUPERSEDED`, `REGISTRY_UNAVAILABLE`, `REGISTRY_ERROR`). Nota le differenze: `NO_MATCH` indica una mancata corrispondenza definitiva, `INCONCLUSIVE` significa che il registro non ha potuto confermare né in un senso né nell'altro (revisione, non rifiuto), e `BIOMETRIC_IMAGE_UNUSABLE` è un problema tecnico relativo al selfie (da ripetere), a differenza del definitivo `BIOMETRIC_NO_MATCH`. Il `match_type` complessivo aggrega i risultati tra i servizi (qualsiasi corrispondenza completa → `full_match`, altrimenti qualsiasi parziale → `partial_match`, altrimenti `no_match`) e `no_match_action`/`partial_match_action` lo traducono nello `status` finale. `validation_type` è derivato: `two_by_two` quando due o più servizi distinti hanno prodotto un riscontro completo (sul numero di identificazione, su nome completo + data di nascita insieme, o sull'indirizzo senza contraddizioni), altrimenti `one_by_one`. **Persistenza.** Il valore predefinito di `save_api_request` è **true**: il risultato viene memorizzato come sessione (`request_id` funziona con `GET /v3/session/{sessionId}/decision/`), compare nella console e attiva un webhook `status.updated`. Controlla inoltre il formato di `validations` — oggetti per ciascun servizio quando la richiesta viene salvata, una mappa aggregata `{field: match}` quando non lo è. **Fatturazione.** Per servizio: a ogni servizio che restituisce un risultato fatturabile viene addebitato il rispettivo prezzo di catalogo. I servizi non riusciti o ignorati non vengono fatturati e le richieste rifiutate con `400` non costano nulla. Il controllo preventivo del saldo copre la somma dei prezzi dei servizi selezionati (`403` se insufficiente). **Errori.** Quando nessun servizio selezionato restituisce un risultato utilizzabile, l'API restituisce `400` con `validation_errors` se ogni tentativo senza risposta ha rifiutato esplicitamente l'input (`provider_rejected_input`, `retryable: false`). Correggi l'input prima di riprovare. Altrimenti restituisce `502` con `validation_errors` (`empty_provider_response`, `retryable: true`), inclusi casi misti di rifiuto dell'input e tentativi di fallback non disponibili; non viene addebitato nulla (viene comunque registrata una sessione con stato `Not Finished` quando `save_api_request=true`). Quando falliscono solo alcuni servizi, la risposta `200` include i relativi errori in `database_validation.errors`. **Sandbox.** Le chiavi delle applicazioni sandbox ignorano le chiamate ai registri e la fatturazione, restituendo una risposta statica `full_match` — il payload sandbox include sempre `services_used` e `match_score: 100` a prescindere da come sia stato inviato `services`, quindi non verificare il gating del formato esteso in produzione o la frazione 0.0–1.0 di `match_score` rispetto alle risposte sandbox. Invia la richiesta come `application/json`, oppure come `multipart/form-data` quando carichi un `selfie`. operationId: post_v3database-validation parameters: [] requestBody: required: true content: application/json: schema: type: object required: - issuing_state properties: issuing_state: type: string description: >- Codice paese ISO 3166-1 **alpha-3** del registro rispetto al quale convalidare (ad es. `BRA`, `ESP`, `COL`). Determina quali servizi sono disponibili. I codici non supportati restituiscono `400` con l'elenco completo delle opzioni valide. example: BRA services: type: array items: type: string description: >- `service_id` di catalogo da eseguire per questo paese (ad es. `["bra_cpf"]`). Accetta anche una singola stringa o una stringa separata da virgole/codificata in JSON. **Se omesso o vuoto, viene eseguito esattamente un servizio predefinito** — il servizio live da più tempo attivo per il paese; i servizi più recenti, biometrici e a consumo (pay-as-you-go) devono essere indicati esplicitamente. L'invio di `services` passa la risposta al formato esteso (aggiunge `services_used` e `match_score`). Ogni id deve esistere ed essere attivo per lo `issuing_state`; i servizi che richiedono l'onboarding restituiscono `400` finché non vengono attivati per la tua organizzazione. Scopri i servizi disponibili per paese tramite `GET /v1/organization/database-validation-countries/` (un endpoint di catalogo non documentato in questa specifica) o nell'editor dei workflow della Business Console. example: - bra_cpf validation_type: type: string deprecated: true description: >- DEPRECATO. Accettato per compatibilità con le versioni precedenti ma ignorato: il `validation_type` della risposta è ora derivato da quanti servizi hanno avuto una corrispondenza completa. Usa `services` per fissare servizi specifici. consent: type: boolean default: false description: >- Imposta su `true` quando l'utente finale ha acconsentito esplicitamente ai servizi di validazione selezionati. Obbligatorio per i servizi contrassegnati da `requires_consent=true` nel catalogo: senza di esso tali servizi restituiscono `400` con `services_requiring_consent`. identification_number: type: string description: >- Numero di identificazione universale — mappato automaticamente al campo specifico del paese corretto, quindi puoi usarlo al posto di `personal_number`/`tax_number`/`document_number`: ARG→document_number (DNI), BOL→document_number (CI), BRA→tax_number (CPF, 11 cifre), CHL→personal_number (RUT), COL→personal_number (Cédula), CRI→personal_number (Cédula), DOM→personal_number (Cédula, 11 cifre), ECU→personal_number (Cédula, 10 cifre), ESP→personal_number (DNI/NIE), GTM→document_number (DPI), HND→document_number (DNI), MEX→personal_number (CURP, 18 caratteri), PAN→personal_number (Cédula), PER→personal_number (DNI, 8 cifre), PRY→document_number (CI), SLV→document_number (DUI), URY→personal_number (CI), VEN→document_number (Cédula). Non sovrascrive mai un campo specifico del paese fornito esplicitamente. first_name: type: string description: >- Il nome proprio della persona fisica. Richiesto da alcuni servizi o paesi. example: John last_name: type: string description: >- Il cognome della persona fisica. Richiesto da alcuni servizi o paesi. example: Doe middle_name: type: string description: >- Secondo nome, utilizzato da alcuni servizi nazionali (AUS, NZL, …). full_name: type: string description: >- Nome completo: alcuni servizi lo accettano al posto di nome/cognome (ad es. i servizi CHN, che confrontano il nome nel sistema di scrittura nativo). date_of_birth: type: string format: date description: Data di nascita, `YYYY-MM-DD`. Richiesta da molti servizi. example: '1980-01-01' personal_number: type: string description: >- Identificativo personale univoco rilasciato dallo stato. Utilizzato da: CHL (RUT), COL (Cédula), CRI, DOM, ECU, ESP (DNI/NIE), MEX (CURP), PAN (Cédula), PER (DNI), URY. Valuta l'uso di `identification_number` in alternativa. tax_number: type: string description: >- Identificativo fiscale. Usato da: BRA (CPF, 11 cifre). Considera invece `identification_number`. document_number: type: string description: >- Numero del documento. Utilizzato da: ARG (DNI), BOL (CI), GTM (DPI), HND (DNI), PRY (CI), SLV (DUI), VEN (Cédula). Considera invece `identification_number`. document_type: type: string enum: - P - DL - ID - RP - SSC - HIC - WP - TC - VISA - PSC - BC - OTHER description: >- Tipo di documento in fase di convalida: `P` passaporto, `DL` patente di guida, `ID` carta d'identità, `RP` permesso di soggiorno (oltre a `SSC`, `HIC`, `WP`, `TC`, `VISA`, `PSC`, `BC`, `OTHER`). Richiesto da alcuni servizi (es. ESP). expiration_date: type: string format: date description: >- Data di scadenza del documento, `YYYY-MM-DD`. Obbligatoria per la validazione ESP (Spagna). example: '2030-01-15' date_of_issue: type: string format: date description: >- Data di emissione del documento, `YYYY-MM-DD` (fecha de expedición). Obbligatoria per la validazione della cédula COL (Colombia). example: '2015-06-20' nationality: type: string description: >- Nazionalità in formato ISO 3166-1 alpha-3. Richiesta da alcuni servizi. gender: type: string enum: - M - F - X description: >- Genere: `M`, `F` o `X` (altro/sconosciuto). Richiesto per la validazione RENAPER dell'Argentina (`arg_renaper`). address: description: >- Indirizzo di residenza. È preferibile l'oggetto strutturato `{"street_1":"123 Main St","street_2":"Apt 4B","city":"Springfield","region":"IL","postal_code":"62701","country":"US"}`; viene comunque accettata una stringa completa su riga singola. Richiesto dai servizi di verifica dell'indirizzo; quando un servizio definisce i requisiti per l'indirizzo, le parti mancanti restituiscono `400` con `address_fields_required_by`. oneOf: - type: object properties: street_1: type: string street_2: type: string city: type: string region: type: string postal_code: type: string country: type: string - type: string description: Indirizzo completo su riga singola (legacy). address_element_1: type: string description: >- Indirizzo stradale inclusi numero civico e tipo di via. Se omesso, viene ricavato da `address`. address_element_2: type: string description: >- Appartamento, interno, edificio, piano o riga di indirizzo aggiuntiva. Inviare solo se si dispone esplicitamente di questo dato. address_element_3: type: string description: >- Città, sobborgo, distretto, località o quartiere. Se omesso, viene ricavato da `address`. address_element_4: type: string description: >- Stato, provincia, regione o città. Se omesso, viene ricavato da `address`. address_element_5: type: string description: Codice postale o CAP. `postal_code` è accettato come alias. postal_code: type: string description: >- Codice postale per i servizi basati sull'indirizzo (alias di `address_element_5`). driver_license_number: type: string description: >- Numero della patente di guida per i servizi governativi di verifica dei documenti (AUS, NZL, IND). driver_license_card_number: type: string description: >- Numero della tessera fisica della patente di guida, dove richiesto separatamente dal numero di patente (AUS). driver_license_state: type: string description: Stato o territorio di rilascio della patente di guida (AUS). driver_license_version: type: string description: Codice versione della patente di guida (NZL). passport_number: type: string description: >- Numero di passaporto per i servizi governativi di verifica del passaporto (AUS, NZL, IND, CHN). passport_expiration_date: type: string format: date description: >- Data di scadenza del passaporto, `YYYY-MM-DD`, per i servizi di verifica del passaporto. passport_file_number: type: string description: Numero di pratica del passaporto (IND). passport_issue_country: type: string description: >- Paese di emissione del passaporto (ISO 3166-1 alpha-3) per i servizi di verifica del passaporto. medicare_card_number: type: string description: Numero della carta Medicare (AUS). immi_card_number: type: string description: Numero dell'ImmiCard australiana. immi_card_expiry_date: type: string format: date description: Data di scadenza dell'ImmiCard australiana. citizenship_certificate_number: type: string description: Numero del certificato di cittadinanza (AUS). birth_registration_number: type: string description: Numero di registrazione del certificato di nascita (AUS). birth_registration_date: type: string format: date description: Data di registrazione del certificato di nascita (AUS). birth_registration_state: type: string description: Stato di registrazione del certificato di nascita (AUS). marriage_certificate_number: type: string description: Numero del certificato di matrimonio (AUS). change_of_name_certificate_number: type: string description: Numero del certificato di cambio nome (AUS). first_partner_name: type: string description: Nome del coniuge su un certificato di matrimonio (AUS). last_partner_name: type: string description: Cognome del partner su un certificato di matrimonio (AUS). voter_id: type: string description: Numero di registrazione elettorale (IND EPIC, IRL). epic_card: type: string description: Numero della tessera elettorale EPIC indiana. pan: type: string description: PAN indiano (Permanent Account Number). national_id: type: string description: >- Numero di identificazione nazionale (CHN, MYS, KEN, KHM, NGA, ZAF, …). cic: type: string description: >- Código de Identificación de Credencial (CIC) dell'INE/IFE messicano, 9 cifre. Utilizzato dal servizio di validità delle credenziali MEX INE (`mex_ine_vigencia`). identificador_ciudadano: type: string description: >- Identificador del Ciudadano dell'INE messicano (9 cifre). Utilizzato con `cic` per i modelli INE moderni (E/F/G/H) in `mex_ine_vigencia`. ocr: type: string description: >- Numero OCR dell'INE messicano (13 cifre, retro del documento). Utilizzato con `cic` per il Modello D in `mex_ine_vigencia`. voter_number: type: string description: >- Clave de Elector dell'INE messicano (18 caratteri). Utilizzata con `emission_number` per i modelli IFE legacy (A/B/C) in `mex_ine_vigencia`. emission_number: type: string description: >- Número de Emisión dell'INE messicano. Utilizzato con `voter_number` per i modelli IFE legacy (A/B/C) in `mex_ine_vigencia`. bvn: type: string description: Numero di verifica bancaria nigeriano. bank_card_number: type: string description: >- Numero di carta bancaria (verifica della carta bancaria CHN). company_registration_number: type: string description: >- Numero di registrazione aziendale rilasciato dal registro delle imprese: il CNPJ in Brasile (es. `11222333000181`), il numero di registrazione in Sudafrica (es. `1936/007721/06`). Obbligatorio per i servizi del registro delle imprese e degli amministratori aziendali (`bra_company_registry`, `bra_company_directors`, `zaf_company_registry`, `zaf_company_directors`). company_name: type: string description: >- Ragione sociale registrata, confrontata con la voce del registro. Opzionale per `zaf_company_registry`. initials: type: string description: >- Le iniziali della persona come stampate sul documento. Obbligatorie per `zaf_drivers_license`; accettate da `zaf_bank_account_holder`. licence_number: type: string description: >- Numero della patente di guida come stampato sulla tessera, per `zaf_drivers_license`. Se omesso, viene utilizzato `document_number`. refugee_file_number: type: string description: >- Numero di pratica per rifugiati rilasciato dal Department of Home Affairs del Sudafrica. Richiesto da `zaf_refugee`. bank_name: type: string description: >- Nome della banca presso cui è detenuto il conto. Obbligatorio per `zaf_bank_account_holder`. bank_account_number: type: string description: >- Numero di conto bancario. Obbligatorio per `zaf_bank_account_holder`; accettato da `zaf_fraud_prevention`. account_type: type: string description: >- Tipo di conto bancario per `zaf_bank_account_holder`: `current`, `savings`, `transmission`, `subscriptionShare` o `notKnown`, senza distinzione tra maiuscole e minuscole. Qualsiasi altro valore restituisce `400`. Omettilo se non conosci il tipo: la verifica incrociata del tipo di conto verrà quindi segnalata come non confermata. phone_number: type: string description: >- Numero di cellulare di contatto, per i servizi che verificano la contattabilità (`zaf_bank_account_holder`, `zaf_fraud_prevention`, `zaf_refugee`). right_thumb: type: string description: >- Impronta digitale del pollice destro codificata in Base64 per `zaf_dha_fingerprint_match`, insieme a `left_thumb` o da sola. left_thumb: type: string description: >- Impronta digitale del pollice sinistro codificata in Base64 per `zaf_dha_fingerprint_match`, insieme a `right_thumb` o da sola. score_level: type: integer description: >- Livello minimo del punteggio biometrico per `zaf_criminal_face_screening`. Il valore predefinito è `3`. max_matches: type: integer description: >- Numero massimo di corrispondenze candidate restituite da `zaf_criminal_face_screening`. Il valore predefinito è `1`. vehicle_register_number: type: string description: >- Numero di registrazione del veicolo. Obbligatorio, insieme a `vehicle_licence_plate` e `vin`, per `zaf_vehicle_ownership`. vehicle_licence_plate: type: string description: >- Numero di targa del veicolo. Obbligatorio, insieme a `vehicle_register_number` e `vin`, per `zaf_vehicle_ownership`. vin: type: string description: >- Numero di identificazione del veicolo (VIN o numero di telaio). Obbligatorio, insieme a `vehicle_register_number` e `vehicle_licence_plate`, per `zaf_vehicle_ownership`. ssn: type: string description: Social Security Number (USA). phone: type: string description: Numero di telefono per i servizi di verifica telefonica. landline: type: string description: Numero di rete fissa per i servizi di verifica telefonica. email: type: string format: email description: Indirizzo email per i servizi di verifica dell'identità. country_of_residence: type: string description: >- Paese di residenza ISO 3166-1 alpha-2. Utilizzato dai servizi globali di arricchimento dell'identità (ad es. `glb_identity_enrichment`) per concentrare la ricerca. example: US partial_match_action: type: string enum: - DECLINE - NO_ACTION default: NO_ACTION description: >- Effetto di un `partial_match` su `database_validation.status`. Il valore predefinito è `NO_ACTION` (lo stato rimane `Approved`, con un avviso). no_match_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- Effetto di un `no_match` su `database_validation.status`. Il valore predefinito è `DECLINE`. save_api_request: type: boolean default: true description: >- Salva la validazione come sessione (visibilità nella console, endpoint della decisione, webhook `status.updated`). Modifica anche la struttura della risposta di `validations`: oggetti per servizio quando è `true` (predefinito), una mappa di campi unificata quando è `false`. vendor_data: type: string description: >- Il tuo identificatore per l'utente validato; restituito nella risposta e memorizzato con la sessione. metadata: type: object nullable: true description: >- JSON a struttura libera memorizzato con la richiesta e restituito nella risposta. example: issuing_state: BRA services: - bra_cpf identification_number: '12345678900' first_name: John last_name: Doe date_of_birth: '1980-01-01' vendor_data: user-1234 multipart/form-data: schema: type: object required: - issuing_state properties: issuing_state: type: string description: >- Codice paese ISO 3166-1 **alpha-3** del registro rispetto al quale convalidare (ad es. `BRA`, `ESP`, `COL`). Determina quali servizi sono disponibili. I codici non supportati restituiscono `400` con l'elenco completo delle opzioni valide. example: BRA services: type: array items: type: string description: >- `service_id` di catalogo da eseguire per questo paese (ad es. `["bra_cpf"]`). Accetta anche una singola stringa o una stringa separata da virgole/codificata in JSON. **Se omesso o vuoto, viene eseguito esattamente un servizio predefinito** — il servizio live da più tempo attivo per il paese; i servizi più recenti, biometrici e a consumo (pay-as-you-go) devono essere indicati esplicitamente. L'invio di `services` passa la risposta al formato esteso (aggiunge `services_used` e `match_score`). Ogni id deve esistere ed essere attivo per lo `issuing_state`; i servizi che richiedono l'onboarding restituiscono `400` finché non vengono attivati per la tua organizzazione. Scopri i servizi disponibili per paese tramite `GET /v1/organization/database-validation-countries/` (un endpoint di catalogo non documentato in questa specifica) o nell'editor dei workflow della Business Console. example: - bra_cpf validation_type: type: string deprecated: true description: >- DEPRECATO. Accettato per compatibilità con le versioni precedenti ma ignorato: il `validation_type` della risposta è ora derivato da quanti servizi hanno avuto una corrispondenza completa. Usa `services` per fissare servizi specifici. consent: type: boolean default: false description: >- Imposta su `true` quando l'utente finale ha acconsentito esplicitamente ai servizi di validazione selezionati. Obbligatorio per i servizi contrassegnati da `requires_consent=true` nel catalogo: senza di esso tali servizi restituiscono `400` con `services_requiring_consent`. identification_number: type: string description: >- Numero di identificazione universale — mappato automaticamente al campo specifico del paese corretto, quindi puoi usarlo al posto di `personal_number`/`tax_number`/`document_number`: ARG→document_number (DNI), BOL→document_number (CI), BRA→tax_number (CPF, 11 cifre), CHL→personal_number (RUT), COL→personal_number (Cédula), CRI→personal_number (Cédula), DOM→personal_number (Cédula, 11 cifre), ECU→personal_number (Cédula, 10 cifre), ESP→personal_number (DNI/NIE), GTM→document_number (DPI), HND→document_number (DNI), MEX→personal_number (CURP, 18 caratteri), PAN→personal_number (Cédula), PER→personal_number (DNI, 8 cifre), PRY→document_number (CI), SLV→document_number (DUI), URY→personal_number (CI), VEN→document_number (Cédula). Non sovrascrive mai un campo specifico del paese fornito esplicitamente. first_name: type: string description: >- Il nome proprio della persona fisica. Richiesto da alcuni servizi o paesi. example: John last_name: type: string description: >- Il cognome della persona fisica. Richiesto da alcuni servizi o paesi. example: Doe middle_name: type: string description: >- Secondo nome, utilizzato da alcuni servizi nazionali (AUS, NZL, …). full_name: type: string description: >- Nome completo: alcuni servizi lo accettano al posto di nome/cognome (ad es. i servizi CHN, che confrontano il nome nel sistema di scrittura nativo). date_of_birth: type: string format: date description: Data di nascita, `YYYY-MM-DD`. Richiesta da molti servizi. example: '1980-01-01' personal_number: type: string description: >- Identificativo personale univoco rilasciato dallo stato. Utilizzato da: CHL (RUT), COL (Cédula), CRI, DOM, ECU, ESP (DNI/NIE), MEX (CURP), PAN (Cédula), PER (DNI), URY. Valuta l'uso di `identification_number` in alternativa. tax_number: type: string description: >- Identificativo fiscale. Usato da: BRA (CPF, 11 cifre). Considera invece `identification_number`. document_number: type: string description: >- Numero del documento. Utilizzato da: ARG (DNI), BOL (CI), GTM (DPI), HND (DNI), PRY (CI), SLV (DUI), VEN (Cédula). Considera invece `identification_number`. document_type: type: string enum: - P - DL - ID - RP - SSC - HIC - WP - TC - VISA - PSC - BC - OTHER description: >- Tipo di documento in fase di convalida: `P` passaporto, `DL` patente di guida, `ID` carta d'identità, `RP` permesso di soggiorno (oltre a `SSC`, `HIC`, `WP`, `TC`, `VISA`, `PSC`, `BC`, `OTHER`). Richiesto da alcuni servizi (es. ESP). expiration_date: type: string format: date description: >- Data di scadenza del documento, `YYYY-MM-DD`. Obbligatoria per la validazione ESP (Spagna). example: '2030-01-15' date_of_issue: type: string format: date description: >- Data di emissione del documento, `YYYY-MM-DD` (fecha de expedición). Obbligatoria per la validazione della cédula COL (Colombia). example: '2015-06-20' nationality: type: string description: >- Nazionalità in formato ISO 3166-1 alpha-3. Richiesta da alcuni servizi. gender: type: string enum: - M - F - X description: >- Genere: `M`, `F` o `X` (altro/sconosciuto). Richiesto per la validazione RENAPER dell'Argentina (`arg_renaper`). address: description: >- Indirizzo di residenza. È preferibile l'oggetto strutturato `{"street_1":"123 Main St","street_2":"Apt 4B","city":"Springfield","region":"IL","postal_code":"62701","country":"US"}`; viene comunque accettata una stringa completa su riga singola. Richiesto dai servizi di verifica dell'indirizzo; quando un servizio definisce i requisiti per l'indirizzo, le parti mancanti restituiscono `400` con `address_fields_required_by`. oneOf: - type: object properties: street_1: type: string street_2: type: string city: type: string region: type: string postal_code: type: string country: type: string - type: string description: Indirizzo completo su riga singola (legacy). address_element_1: type: string description: >- Indirizzo stradale inclusi numero civico e tipo di via. Se omesso, viene ricavato da `address`. address_element_2: type: string description: >- Appartamento, interno, edificio, piano o riga di indirizzo aggiuntiva. Inviare solo se si dispone esplicitamente di questo dato. address_element_3: type: string description: >- Città, sobborgo, distretto, località o quartiere. Se omesso, viene ricavato da `address`. address_element_4: type: string description: >- Stato, provincia, regione o città. Se omesso, viene ricavato da `address`. address_element_5: type: string description: Codice postale o CAP. `postal_code` è accettato come alias. postal_code: type: string description: >- Codice postale per i servizi basati sull'indirizzo (alias di `address_element_5`). driver_license_number: type: string description: >- Numero della patente di guida per i servizi governativi di verifica dei documenti (AUS, NZL, IND). driver_license_card_number: type: string description: >- Numero della tessera fisica della patente di guida, dove richiesto separatamente dal numero di patente (AUS). driver_license_state: type: string description: Stato o territorio di rilascio della patente di guida (AUS). driver_license_version: type: string description: Codice versione della patente di guida (NZL). passport_number: type: string description: >- Numero di passaporto per i servizi governativi di verifica del passaporto (AUS, NZL, IND, CHN). passport_expiration_date: type: string format: date description: >- Data di scadenza del passaporto, `YYYY-MM-DD`, per i servizi di verifica del passaporto. passport_file_number: type: string description: Numero di pratica del passaporto (IND). passport_issue_country: type: string description: >- Paese di emissione del passaporto (ISO 3166-1 alpha-3) per i servizi di verifica del passaporto. medicare_card_number: type: string description: Numero della carta Medicare (AUS). immi_card_number: type: string description: Numero dell'ImmiCard australiana. immi_card_expiry_date: type: string format: date description: Data di scadenza dell'ImmiCard australiana. citizenship_certificate_number: type: string description: Numero del certificato di cittadinanza (AUS). birth_registration_number: type: string description: Numero di registrazione del certificato di nascita (AUS). birth_registration_date: type: string format: date description: Data di registrazione del certificato di nascita (AUS). birth_registration_state: type: string description: Stato di registrazione del certificato di nascita (AUS). marriage_certificate_number: type: string description: Numero del certificato di matrimonio (AUS). change_of_name_certificate_number: type: string description: Numero del certificato di cambio nome (AUS). first_partner_name: type: string description: Nome del coniuge su un certificato di matrimonio (AUS). last_partner_name: type: string description: Cognome del partner su un certificato di matrimonio (AUS). voter_id: type: string description: Numero di registrazione elettorale (IND EPIC, IRL). epic_card: type: string description: Numero della tessera elettorale EPIC indiana. pan: type: string description: PAN indiano (Permanent Account Number). national_id: type: string description: >- Numero di identificazione nazionale (CHN, MYS, KEN, KHM, NGA, ZAF, …). cic: type: string description: >- Código de Identificación de Credencial (CIC) dell'INE/IFE messicano, 9 cifre. Utilizzato dal servizio di validità delle credenziali MEX INE (`mex_ine_vigencia`). identificador_ciudadano: type: string description: >- Identificador del Ciudadano dell'INE messicano (9 cifre). Utilizzato con `cic` per i modelli INE moderni (E/F/G/H) in `mex_ine_vigencia`. ocr: type: string description: >- Numero OCR dell'INE messicano (13 cifre, retro del documento). Utilizzato con `cic` per il Modello D in `mex_ine_vigencia`. voter_number: type: string description: >- Clave de Elector dell'INE messicano (18 caratteri). Utilizzata con `emission_number` per i modelli IFE legacy (A/B/C) in `mex_ine_vigencia`. emission_number: type: string description: >- Número de Emisión dell'INE messicano. Utilizzato con `voter_number` per i modelli IFE legacy (A/B/C) in `mex_ine_vigencia`. bvn: type: string description: Numero di verifica bancaria nigeriano. bank_card_number: type: string description: >- Numero di carta bancaria (verifica della carta bancaria CHN). company_registration_number: type: string description: >- Numero di registrazione aziendale rilasciato dal registro delle imprese: il CNPJ in Brasile (es. `11222333000181`), il numero di registrazione in Sudafrica (es. `1936/007721/06`). Obbligatorio per i servizi del registro delle imprese e degli amministratori aziendali (`bra_company_registry`, `bra_company_directors`, `zaf_company_registry`, `zaf_company_directors`). company_name: type: string description: >- Ragione sociale registrata, confrontata con la voce del registro. Opzionale per `zaf_company_registry`. initials: type: string description: >- Le iniziali della persona come stampate sul documento. Obbligatorie per `zaf_drivers_license`; accettate da `zaf_bank_account_holder`. licence_number: type: string description: >- Numero della patente di guida come stampato sulla tessera, per `zaf_drivers_license`. Se omesso, viene utilizzato `document_number`. refugee_file_number: type: string description: >- Numero di pratica per rifugiati rilasciato dal Department of Home Affairs del Sudafrica. Richiesto da `zaf_refugee`. bank_name: type: string description: >- Nome della banca presso cui è detenuto il conto. Obbligatorio per `zaf_bank_account_holder`. bank_account_number: type: string description: >- Numero di conto bancario. Obbligatorio per `zaf_bank_account_holder`; accettato da `zaf_fraud_prevention`. account_type: type: string description: >- Tipo di conto bancario per `zaf_bank_account_holder`: `current`, `savings`, `transmission`, `subscriptionShare` o `notKnown`, senza distinzione tra maiuscole e minuscole. Qualsiasi altro valore restituisce `400`. Omettilo se non conosci il tipo: la verifica incrociata del tipo di conto verrà quindi segnalata come non confermata. phone_number: type: string description: >- Numero di cellulare di contatto, per i servizi che verificano la contattabilità (`zaf_bank_account_holder`, `zaf_fraud_prevention`, `zaf_refugee`). right_thumb: type: string description: >- Impronta digitale del pollice destro codificata in Base64 per `zaf_dha_fingerprint_match`, insieme a `left_thumb` o da sola. left_thumb: type: string description: >- Impronta digitale del pollice sinistro codificata in Base64 per `zaf_dha_fingerprint_match`, insieme a `right_thumb` o da sola. score_level: type: integer description: >- Livello minimo del punteggio biometrico per `zaf_criminal_face_screening`. Il valore predefinito è `3`. max_matches: type: integer description: >- Numero massimo di corrispondenze candidate restituite da `zaf_criminal_face_screening`. Il valore predefinito è `1`. vehicle_register_number: type: string description: >- Numero di registrazione del veicolo. Obbligatorio, insieme a `vehicle_licence_plate` e `vin`, per `zaf_vehicle_ownership`. vehicle_licence_plate: type: string description: >- Numero di targa del veicolo. Obbligatorio, insieme a `vehicle_register_number` e `vin`, per `zaf_vehicle_ownership`. vin: type: string description: >- Numero di identificazione del veicolo (VIN o numero di telaio). Obbligatorio, insieme a `vehicle_register_number` e `vehicle_licence_plate`, per `zaf_vehicle_ownership`. ssn: type: string description: Social Security Number (USA). phone: type: string description: Numero di telefono per i servizi di verifica telefonica. landline: type: string description: Numero di rete fissa per i servizi di verifica telefonica. email: type: string format: email description: Indirizzo email per i servizi di verifica dell'identità. country_of_residence: type: string description: >- Paese di residenza ISO 3166-1 alpha-2. Utilizzato dai servizi globali di arricchimento dell'identità (ad es. `glb_identity_enrichment`) per concentrare la ricerca. example: US partial_match_action: type: string enum: - DECLINE - NO_ACTION default: NO_ACTION description: >- Effetto di un `partial_match` su `database_validation.status`. Il valore predefinito è `NO_ACTION` (lo stato rimane `Approved`, con un avviso). no_match_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- Effetto di un `no_match` su `database_validation.status`. Il valore predefinito è `DECLINE`. save_api_request: type: boolean default: true description: >- Salva la validazione come sessione (visibilità nella console, endpoint della decisione, webhook `status.updated`). Modifica anche la struttura della risposta di `validations`: oggetti per servizio quando è `true` (predefinito), una mappa di campi unificata quando è `false`. vendor_data: type: string description: >- Il tuo identificatore per l'utente validato; restituito nella risposta e memorizzato con la sessione. metadata: type: object nullable: true description: >- JSON a struttura libera memorizzato con la richiesta e restituito nella risposta. selfie: type: string format: binary description: >- Immagine del selfie (`jpg`, `jpeg`, `png`, `webp`; max 2 MB — le immagini vengono compresse a ~1.5 MB prima del caricamento nel registro) per i servizi di validazione biometrica, ad es. Argentina RENAPER (`arg_renaper`) e Panama SIB (`pan_cedula_sib`, `pan_cedula_sib_plus`). Obbligatorio ogni volta che un servizio selezionato lo include come campo obbligatorio. Disponibile solo tramite `multipart/form-data`. responses: '200': description: >- Validazione completata — almeno un servizio selezionato ha restituito un risultato utilizzabile. Ispeziona `database_validation.match_type` per l'esito aggregato, `validations` per i confronti dei campi per servizio e i relativi `outcome_code`, ed `errors` (quando presente) per i servizi che hanno avuto esito negativo. content: application/json: schema: type: object properties: request_id: type: string format: uuid description: >- ID della sessione salvata quando `save_api_request=true` (utilizzabile con `GET /v3/session/{sessionId}/decision/`); altrimenti un UUID di correlazione temporaneo. database_validation: type: object properties: status: type: string enum: - Approved - Declined - In Review description: >- `Declined` quando il `match_type` complessivo attiva un'azione `DECLINE` (il valore predefinito di `no_match_action` è `DECLINE`, mentre quello di `partial_match_action` è `NO_ACTION`); `In Review` quando nessun servizio ha prodotto un confronto utilizzabile, ad esempio quando l'unico servizio selezionato ha restituito `REGISTRY_UNAVAILABLE` o `INCONCLUSIVE`; `Approved` altrimenti. Una richiesta che ha selezionato più servizi può risultare `Approved` sulla corrispondenza di un servizio mentre un altro non era disponibile, quindi controlla anche `errors` e gli `outcome_code` di ciascun servizio. issuing_state: type: string description: >- Eco del paese ISO 3166-1 alpha-3 rispetto al quale è stata eseguita la validazione. example: BRA validation_type: type: string enum: - one_by_one - two_by_two description: >- Derivato dai risultati: `two_by_two` quando ≥2 servizi distinti hanno prodotto una corrispondenza completa (sul numero identificativo, su nome completo + data di nascita insieme, o sull'indirizzo senza contraddizioni); altrimenti `one_by_one`. (Il campo della richiesta con lo stesso nome è deprecato e ignorato.) screened_data: type: object description: >- Eco dei campi di input inviati ai servizi selezionati (date normalizzate in `YYYY-MM-DD`; un `selfie`, quando inviato, viene restituito come URL pre-firmato; `consent_obtained: true` viene aggiunto quando è stato fornito il consenso). match_type: type: string nullable: true enum: - full_match - partial_match - no_match description: >- Risultato complessivo aggregato tra i servizi con confronti a livello di campo: qualsiasi `full_match` → `full_match`; altrimenti qualsiasi `partial_match` → `partial_match`; altrimenti `no_match`. I servizi basati solo sull'esito, come lo screening criminale biometrico, possono restituire `null`; esamina ciascun elemento in `validations` per il relativo `outcome_code`. validations: description: >- La struttura dipende da `save_api_request`. **`true` (predefinito):** un array di oggetti per servizio (`service_id`, `service_name`, `validation`, `outcome_code`, `outcome_detail`, `source_data`). **`false`:** un singolo oggetto piatto che unisce i risultati a livello di campo di tutti i servizi (`{"full_name": "full_match", ...}`). oneOf: - type: array items: type: object description: >- Risultato della validazione per singolo servizio (restituito quando `save_api_request=true`, l'impostazione predefinita). properties: service_id: type: string description: >- Id di catalogo del servizio che ha prodotto questo risultato (ad es. `bra_cpf`). example: bra_cpf service_name: type: string description: >- Nome del servizio nel catalogo, leggibile dall'utente. example: Brazil - CPF status check validation: type: object description: >- Confronto campo per campo tra i dati inseriti e il record del registro. Le chiavi sono nomi di campo canonici (`full_name`, `date_of_birth`, `identification_number`, `address`, …); i valori sono `full_match`, `partial_match` o `no_match`. additionalProperties: type: string enum: - full_match - partial_match - no_match outcome_code: type: string enum: - MATCH - PARTIAL_MATCH - NO_MATCH - DOCUMENT_NOT_FOUND - INVALID_DOCUMENT_FORMAT - INVALID_INPUT - MINOR_BLOCKED - DECEASED - BIOMETRIC_NO_MATCH - BIOMETRIC_IMAGE_UNUSABLE - INCONCLUSIVE - DOCUMENT_SUPERSEDED - REGISTRY_UNAVAILABLE - REGISTRY_ERROR description: >- Esito indipendente dal vendor della consultazione del registro. `MATCH`/`PARTIAL_MATCH`/`NO_MATCH` descrivono il confronto; `DOCUMENT_NOT_FOUND` indica che l'identificativo non è presente nel registro; `INCONCLUSIVE` indica che il registro non ha potuto confermare in nessun senso (inoltrato a revisione — NON è una mancata corrispondenza); `BIOMETRIC_NO_MATCH` è una mancata corrispondenza facciale definitiva, mentre `BIOMETRIC_IMAGE_UNUSABLE` è un problema tecnico dell'immagine (scatta nuovamente il selfie); `DECEASED`/`MINOR_BLOCKED` sono esiti legati alle policy del registro; `DOCUMENT_SUPERSEDED` indica che l'identità corrispondeva ma l'edizione del documento presentato non è quella registrata (è stata emessa un'edizione più recente); `INVALID_DOCUMENT_FORMAT`/`INVALID_INPUT` indicano che il registro stesso ha rifiutato i dati inviati; `REGISTRY_UNAVAILABLE`/`REGISTRY_ERROR` indicano errori a monte. outcome_detail: type: string nullable: true description: >- Dettaglio dello stato a monte non elaborato a supporto del codice di esito (ad es. un codice di stato HTTP o del registro). source_data: type: object nullable: true description: >- Vista ripulita e normalizzata del record di registro che utilizza nomi di campo canonici (`identification_number`, `first_name`, `last_name`, `date_of_birth`, più flag specifici del registro). I campi immagine, se presenti, vengono restituiti come URL pre-firmati. - type: object additionalProperties: type: string enum: - full_match - partial_match - no_match description: >- Risultati uniti a livello di campo (formato stateless `save_api_request=false`). warnings: type: array items: type: object properties: feature: type: string description: Funzionalità che ha generato l'avviso. risk: type: string description: >- Identificatore di rischio leggibile dalla macchina. additional_data: type: object nullable: true description: >- Contesto aggiuntivo per l'avviso, se disponibile. log_type: type: string description: >- `warning`, `information` o `error` — come il rischio ha influito sull'esito. short_description: type: string description: Riepilogo su una riga leggibile dall'uomo. long_description: type: string description: Spiegazione completa e leggibile. description: >- `DATABASE_VALIDATION_NO_MATCH` o `DATABASE_VALIDATION_PARTIAL_MATCH` quando applicabile; vuoto in caso di corrispondenza completa. errors: type: array description: >- Presente solo quando alcuni (ma non tutti) i servizi selezionati non sono riusciti. Ogni voce include `service_id`, `code`, `message` e `retryable`. Un servizio segnalato qui è assente da `validations` e `services_used`, e non viene fatturato. Questo array è l'unico punto in cui compare, quindi esaminalo anche quando `status` è `Approved`. items: type: object properties: service_id: type: string code: type: string example: empty_provider_response message: type: string retryable: type: boolean description: >- `true` quando il servizio non ha prodotto alcuna risposta e un nuovo tentativo successivo può avere successo; `false` quando la fonte ha rifiutato i dati inviati e l'input deve essere prima corretto. example: true services_used: type: array items: type: string description: >- Id di catalogo dei servizi che hanno restituito un risultato fatturabile. **Presente solo quando la richiesta ha inviato esplicitamente `services`.** match_score: type: number description: >- Frazione (0.0–1.0) dei servizi tentati che hanno prodotto una corrispondenza completa (sul numero identificativo, su nome completo + data di nascita insieme, o sull'indirizzo senza contraddizioni). **Presente solo quando la richiesta ha inviato esplicitamente `services`.** vendor_data: type: string nullable: true description: Eco del `vendor_data` inviato. metadata: type: object nullable: true description: Eco del `metadata` inviato. created_at: type: string format: date-time examples: Full match (Approved): summary: >- Valore predefinito save_api_request=true — oggetti `validations` per servizio value: request_id: 7f9a1c0e-1f2b-4f6e-9d3a-2b1c0e7f9a1c database_validation: status: Approved issuing_state: BRA validation_type: one_by_one screened_data: tax_number: '12345678900' first_name: John last_name: Doe date_of_birth: '1980-01-01' match_type: full_match validations: - validation: full_name: full_match date_of_birth: full_match identification_number: full_match outcome_code: MATCH outcome_detail: '200' service_id: bra_cpf service_name: Brazil - CPF status check source_data: identification_number: '12345678900' first_name: JOHN last_name: DOE date_of_birth: '1980-01-01' lgpd_minor: false minor_under_16: false minor_under_18: false warnings: [] vendor_data: user-1234 metadata: null created_at: '2026-06-11T10:30:00.000000+00:00' Explicit services (extended shape): summary: >- Richiesta inviata con `services` — la risposta aggiunge `services_used` e `match_score` value: request_id: b3e7c1a2-9d4f-4f0b-8a6c-5e2d1f0a9b3e database_validation: status: Approved issuing_state: BRA validation_type: one_by_one screened_data: tax_number: '12345678900' first_name: John last_name: Doe date_of_birth: '1980-01-01' match_type: full_match validations: - validation: full_name: full_match date_of_birth: full_match identification_number: full_match outcome_code: MATCH outcome_detail: '200' service_id: bra_cpf service_name: Brazil - CPF status check source_data: identification_number: '12345678900' first_name: JOHN last_name: DOE date_of_birth: '1980-01-01' lgpd_minor: false minor_under_16: false minor_under_18: false warnings: [] services_used: - bra_cpf match_score: 1 vendor_data: user-1234 metadata: null created_at: '2026-06-11T10:30:00.000000+00:00' No match (Declined): summary: >- Il record del registro delle imprese non corrisponde — predefinito `no_match_action=DECLINE` value: request_id: 0a1b2c3d-4e5f-6789-abcd-ef0123456789 database_validation: status: Declined issuing_state: BRA validation_type: one_by_one screened_data: tax_number: '12345678900' first_name: John last_name: Doe date_of_birth: '1980-01-01' match_type: no_match validations: - validation: full_name: no_match date_of_birth: no_match identification_number: no_match outcome_code: NO_MATCH outcome_detail: '200' service_id: bra_cpf service_name: Brazil - CPF status check source_data: identification_number: '00987654321' first_name: TOTALLY last_name: DIFFERENT NAME date_of_birth: '1999-01-01' lgpd_minor: false minor_under_16: false minor_under_18: false warnings: - feature: DATABASE_VALIDATION risk: DATABASE_VALIDATION_NO_MATCH additional_data: null log_type: error short_description: Database validation no match long_description: >- The system identified a no match in the database validation, requiring further investigation. vendor_data: null metadata: null created_at: '2026-06-11T10:31:00.000000+00:00' Stateless (save_api_request=false): summary: >- `validations` si riduce a una mappa di campi unificata; non viene memorizzato nulla value: request_id: c4d5e6f7-8901-2345-6789-abcdef012345 database_validation: status: Approved issuing_state: BRA validation_type: one_by_one screened_data: tax_number: '12345678900' first_name: John last_name: Doe date_of_birth: '1980-01-01' match_type: full_match validations: full_name: full_match date_of_birth: full_match identification_number: full_match warnings: [] vendor_data: null metadata: null created_at: '2026-06-11T10:32:00.000000+00:00' '400': description: >- Errore di validazione - non viene fatturato nulla. Gli errori sui campi in fase di preflight si verificano prima di qualsiasi chiamata esterna. Se ogni tentativo senza risposta rifiuta esplicitamente l'input, la risposta include invece `validation_errors` con `code: provider_rejected_input` e `retryable: false`; correggi l'input prima di riprovare. I problemi a livello di campo utilizzano la busta standard di DRF; i problemi del catalogo restituiscono un array `services` (più `requires_onboarding` o `services_requiring_consent` se pertinenti); gli errori per campi mancanti includono `fields_required_by` che mappa ogni campo mancante ai servizi che lo richiedono; i servizi che necessitano di almeno un identificatore aggiuntivo (ad es. `usa_states_credit_bureau`, che non può verificare un nome da solo) restituiscono `any_field_required_by` mappando ciascun servizio ai campi di cui almeno uno deve essere presente; i problemi di formato controllati per servizio restituiscono `invalid_fields_by_service`. content: application/json: examples: Invalid issuing_state: summary: >- Paese non supportato — il messaggio elenca tutti i codici alpha-3 validi value: error: - >- Invalid issuing state. Valid options are: ARE, ARG, AUS, AUT, BEL, BGD, BOL, BRA, CAN, CHE, CHL, CHN, CIV, COL, CRI, CZE, DEU, DNK, DOM, ECU, ESP, FIN, FRA, GBR, GHA, GLB, GRC, GTM, HKG, HND, IDN, IND, IRL, ITA, KEN, KHM, MAR, MEX, MYS, NGA, NLD, NOR, NZL, OMN, PAN, PER, PHL, POL, PRT, PRY, QAT, SGP, SLV, SVK, SWE, THA, UGA, URY, USA, VEN, ZAF, ZMB, ZWE Missing required fields: summary: >- Unione dei campi obbligatori nei servizi selezionati, con l'indicazione del campo universale value: error: - >- Missing required fields: tax_number (or use 'identification_number' which maps to 'tax_number' for BRA) fields_required_by: tax_number: - bra_cpf Unknown service id: summary: '`services` contiene un id non presente nel catalogo' value: services: - 'Unknown service_id(s): [''bogus_service'']' Service not live for country: summary: >- `services` fa riferimento a un servizio di un altro paese (o a una voce fittizia) value: services: - >- Services not currently live for PER: ['bra_cpf']. Available services: ['per_dni', 'per_residential', 'per_tax_registration'] Service requires onboarding: summary: >- Il servizio esiste ma non è ancora attivato per la tua organizzazione value: services: - >- Services require onboarding before they can be enabled for AUS: ['aus_australia_driver_licence']. Contact Didit support to activate them. requires_onboarding: - aus_australia_driver_licence Consent missing: summary: >- Un servizio selezionato è contrassegnato con requires_consent=true e `consent` non era `true` value: consent: - >- Explicit end-user consent is required for these database validation services: ['chn_national_id']. Send `consent=true`. services_requiring_consent: - chn_national_id Country format rule violation: summary: >- L'identificatore non rispetta la regola di formato del paese (lunghezza/cifre/regex) value: tax_number: - >- Invalid tax number for BRA: Brazilian CPF (exactly 11 digits). Must be exactly 11 characters long (got 10). Service-specific format violation: summary: >- Un campo non soddisfa i requisiti di formato propri del servizio selezionato value: error: - >- One or more fields do not match the format required by the selected service. invalid_fields_by_service: chn_national_id: - national_id_format Input refused by every attempt: summary: Correggi l'input prima di riprovare value: error: >- The source refused to run this query with the supplied input. validation_errors: - service_id: bra_cpf code: provider_rejected_input message: >- The source refused to run this query with the supplied input. retryable: false schema: type: object additionalProperties: true properties: error: description: >- Spiegazione a livello di richiesta o errori preliminari sui campi. oneOf: - type: string - type: array items: type: string validation_errors: type: array description: >- Presente quando ogni tentativo senza risposta ha rifiutato l'input dopo il preflight. items: type: object properties: service_id: type: string code: type: string message: type: string retryable: type: boolean description: >- Indica se riprovare più tardi può risolvere questo errore del servizio. False indica che è necessario prima correggere l'input fornito. '403': description: >- Autorizzazione negata. Restituito quando l'intestazione `x-api-key` è mancante e anche quando il saldo dell'organizzazione chiamante non è sufficiente a coprire la chiamata; una chiave errata, revocata o scaduta restituisce `401`. Una chiave mancante restituisce `403` con `{"detail": ...}`; una chiave errata, revocata o scaduta restituisce `401`. Crediti insufficienti restituiscono `403` con `{"error": ...}` prima che avvenga qualsiasi screening o chiamata al provider. content: application/json: examples: Missing or invalid API key: summary: >- Nessuna intestazione `x-api-key`, oppure la chiave non è valida/revocata value: detail: You do not have permission to perform this action. Not enough credits: summary: >- Il saldo dell'organizzazione non è sufficiente per coprire la chiamata value: error: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me '429': description: >- Limite di frequenza superato. Gli endpoint POST/PATCH/DELETE condividono un budget di 300 richieste di scrittura al minuto per chiave API (la creazione di transazioni e l'ingestione di eventi hanno un budget separato di 600). La risposta contiene le intestazioni `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`. content: application/json: examples: Write rate limit exceeded: summary: Più di 300 richieste di scrittura nel minuto corrente value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. schema: type: object properties: detail: type: string '502': description: >- Nessun servizio selezionato ha restituito un risultato utilizzabile. Ispeziona ogni voce di validation_errors prima di effettuare un nuovo tentativo; l'errore HTTP 502 da solo non prova un errore temporaneo. Un valore empty_provider_response con retryable: true indica risultati non disponibili o non spiegati, compreso un fornitore primario rifiutato seguito da un'alternativa non disponibile. Le voci legacy provider_invalid_input e provider_validation_error richiedono invece dati di input corretti e possono omettere retryable. Nulla viene fatturato. Quando save_api_request=true, il tentativo fallito viene registrato come sessione con stato Not Finished. Gli errori parziali restituiscono 200 con database_validation.errors. content: application/json: schema: type: object properties: error: type: string validation_errors: type: array items: type: object properties: service_id: type: string code: type: string message: type: string retryable: type: boolean description: >- Indica se riprovare più tardi può risolvere questo errore del servizio. False indica che è necessario prima correggere l'input fornito. examples: Provider returned no result: summary: Tutti i servizi selezionati hanno avuto esito negativo value: error: >- Database validation could not be performed. The external validation service did not return a result. Please try again later. validation_errors: - service_id: bra_cpf code: empty_provider_response message: >- The provider did not return a database validation result. retryable: true security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: |- curl -X POST https://verification.didit.me/v3/database-validation/ \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "issuing_state": "BRA", "services": ["bra_cpf"], "identification_number": "12345678900", "first_name": "John", "last_name": "Doe", "date_of_birth": "1980-01-01", "vendor_data": "user-1234" }' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.database_validation.validate( issuing_state="BRA", services=["bra_cpf"], identification_number="12345678900", first_name="John", last_name="Doe", date_of_birth="1980-01-01", vendor_data="user-1234", ) print(result) - lang: javascript label: Node.js source: |- import Didit from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.databaseValidation.validate({ issuing_state: "BRA", services: ["bra_cpf"], identification_number: "12345678900", first_name: "John", last_name: "Doe", date_of_birth: "1980-01-01", vendor_data: "user-1234", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.DatabaseValidation.Validate(ctx, didit.DatabaseValidationValidateParams{\n\tIssuingState: \"BRA\",\n\tServices: didit.Some([]string{\"bra_cpf\"}),\n\tIdentificationNumber: didit.String(\"12345678900\"),\n\tFirstName: didit.String(\"John\"),\n\tLastName: didit.String(\"Doe\"),\n\tDateOfBirth: didit.String(\"1980-01-01\"),\n\tVendorData: didit.String(\"user-1234\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.time.LocalDate; import java.util.List; import me.didit.Didit; import me.didit.types.DatabaseValidationValidateParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.databaseValidation().validate(DatabaseValidationValidateParams.builder() .issuingState("BRA") .services(List.of("bra_cpf")) .identificationNumber("12345678900") .firstName("John") .lastName("Doe") .dateOfBirth(LocalDate.parse("1980-01-01")) .vendorData("user-1234") .build()); System.out.println(result); - lang: php label: PHP source: |- databaseValidation->validate([ 'issuing_state' => 'BRA', 'services' => ['bra_cpf'], 'identification_number' => '12345678900', 'first_name' => 'John', 'last_name' => 'Doe', 'date_of_birth' => '1980-01-01', 'vendor_data' => 'user-1234', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.database_validation.validate( issuing_state: "BRA", services: ["bra_cpf"], identification_number: "12345678900", first_name: "John", last_name: "Doe", date_of_birth: "1980-01-01", vendor_data: "user-1234" ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.DatabaseValidation.ValidateAsync(new DatabaseValidationValidateParams { IssuingState = "BRA", Services = new string[] { "bra_cpf" }, IdentificationNumber = "12345678900", FirstName = "John", LastName = "Doe", DateOfBirth = "1980-01-01", VendorData = "user-1234", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.