> ## 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. # Verifica dell'identità API: OCR documenti e autenticità > Didit verifica i documenti d'identità in oltre 220 paesi e 14.000+ tipi. Autenticità, OCR, MRZ, inferenza sotto 2 s, pagamento a consumo, nessun contratto. ## OpenAPI ````yaml it/openapi-25.json POST /v3/id-verification/ 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/id-verification/: post: tags: - Standalone APIs summary: Verifica dell'identità (OCR del documento + controlli antifrode) description: >- Esegui l'OCR di un documento d'identità e i controlli antifrode sul documento in un'unica chiamata: restituisce i campi estratti del titolare, la MRZ analizzata, uno `status` `Approved`/`Declined`/`In Review` e un elenco `warnings` che spiega ogni problema riscontrato. Supporta 14,000+ tipi di documento da 220+ paesi e territori. **Come funziona.** Invia il `front_image` del documento (obbligatorio) e, per i documenti a due lati, il `back_image`. Carica foto non ritagliate con tutti e quattro gli angoli del documento visibili: il servizio rileva, allinea e ritaglia il documento autonomamente, quindi non ritagliarlo preventivamente. Il documento viene classificato automaticamente (non devi mai dichiarare il paese o il tipo di documento), la zona visiva viene letta tramite OCR e vengono decodificati la MRZ e gli eventuali codici a barre. I controlli incrociati convalidano quindi le date, i formati dei numeri e le cifre di controllo della MRZ, confrontando la zona visiva con la MRZ. Con `perform_document_liveness=true`, le immagini vengono inoltre analizzate per rilevare riproduzioni su schermo, copie stampate e manipolazioni del ritratto. **Logica decisionale.** Lo `status` è `Approved` a meno che almeno un avviso non determini un rifiuto. I rischi di frode e di errore grave portano sempre a un rifiuto: `DOCUMENT_EXPIRED`, `SCREEN_CAPTURE_DETECTED`, `PRINTED_COPY_DETECTED`, `PORTRAIT_MANIPULATION_DETECTED`, `PUBLIC_DOCUMENT_IMAGE_DETECTED`, oltre agli errori di estrazione (`NAME_NOT_DETECTED`, `DATE_OF_BIRTH_NOT_DETECTED`, `DOCUMENT_NUMBER_NOT_DETECTED`). (`PORTRAIT_IMAGE_NOT_DETECTED`, `INVALID_DATE` e `MRZ_NOT_DETECTED` esistono nelle sessioni dei workflow ma non vengono mai generati da questo endpoint autonomo. `COULD_NOT_DETECT_DOCUMENT_TYPE` viene restituito qui quando l'immagine frontale non corrisponde con elevata affidabilità al modello di un documento ufficiale noto, e rifiuta la richiesta.) Tre gruppi di rischio sono configurabili per richiesta tramite `invalid_mrz_action`, `inconsistent_data_action` ed `expiration_date_not_detected_action` (`DECLINE` o `NO_ACTION`). Tutti gli altri avvisi (ad es. `POSSIBLE_DUPLICATED_USER`) sono informativi e non causano mai un rifiuto da soli. Quando `perform_document_liveness=true` (il valore predefinito) e il controllo di contraffazione non restituisce un punteggio utilizzabile (il provider non è riuscito, ha risposto con uno stato diverso da 200 o ha risposto con HTTP 200 con `status="ERR"`), la chiamata restituisce `200` con `status: "In Review"` e un avviso `DOCUMENT_LIVENESS_NOT_COMPUTED` (`log_type: "warning"`) invece di `Approved`: un controllo non eseguito non dimostra che il documento sia autentico. Questa escalation non è configurabile e non sovrascrive mai un `Declined`; con `perform_document_liveness=false` il controllo viene ignorato e lo stato segue gli avvisi rimanenti come in precedenza. Un documento che non può essere elaborato affatto restituisce `400` con `{"error": "COULD_NOT_RECOGNIZE_DOCUMENT"}`; un documento leggibile ma problematico restituisce `200` con `status: "Declined"`: controlla sempre `id_verification.status` e `id_verification.warnings`, non solo il codice HTTP. **Fatturazione.** Ciascuna risposta `200` consuma un credito dell'API di Verifica dell'identità (pagato con il credito del tuo piano o con il saldo di ricarica). Quando il saldo dell'organizzazione non copre la chiamata, l'endpoint restituisce `403` con l'errore di crediti insufficienti prima di qualsiasi elaborazione delle immagini. **Persistenza della sessione (`save_api_request`, predefinito `true`).** Quando è `true`, la chiamata viene salvata come sessione di tipo API: compare nella Business Console, il `request_id` restituito è un vero e proprio ID di sessione che puoi passare a `GET /v3/session/{sessionId}/decision/`, le immagini ritagliate del documento/ritratto vengono archiviate e restituite come URL multimediali temporanei (`https:///ocr/...`), e viene inviato un webhook `status.updated` agli endpoint webhook configurati. Quando è `false`, non viene memorizzato nulla, `request_id` è un UUID di correlazione monouso e `portrait_image`/`front_image`/`back_image` vengono restituiti inline come stringhe JPEG con codifica base64. **Sandbox.** Le chiavi API di sandbox ignorano qualsiasi elaborazione e fatturazione: dopo la validazione della richiesta (un input non valido restituisce comunque `400`), l'endpoint restituisce un payload fittizio statico `Approved` (una carta d'identità fittizia degli Stati Uniti per un "Sandbox User"), non viene salvata alcuna sessione e non viene consumato alcun credito. **Autenticazione.** Invia la chiave API della tua applicazione nell'intestazione `x-api-key`. Credenziali mancanti o non valide restituiscono `403` (`{"detail": "You do not have permission to perform this action."}`): questa API non restituisce mai `401`. **Limite di frequenza.** Budget di scrittura condiviso di 300 richieste/min per chiave API su tutti gli endpoint POST/PATCH/DELETE; il suo superamento restituisce `429`. operationId: post_v3id-verification parameters: [] requestBody: required: true content: multipart/form-data: schema: type: object required: - front_image properties: front_image: type: string format: binary description: >- Fronte del documento d'identità. Estensioni consentite: `tiff`, `jpg`, `jpeg`, `png`, `webp`, `pdf`. Dimensione massima di caricamento: **10 MB** (i file più grandi vengono rifiutati con `400`). I PDF vengono convertiti in immagine prima dell'OCR; i PDF crittografati richiedono `front_image_password`. Le immagini vengono compresse automaticamente a ~0.5 MB e viene applicato l'orientamento EXIF. Carica l'acquisizione completa e non ritagliata, con tutti e quattro gli angoli del documento visibili. front_image_password: type: string description: >- Password per decrittografare `front_image` quando è un PDF crittografato. L'invio di un PDF crittografato senza password (o con una errata) restituisce `400`. writeOnly: true back_image: type: string format: binary description: >- Retro del documento: invialo ogni volta che il documento ne dispone (molte carte d'identità presentano la MRZ o un codice a barre sul retro; ometterlo lascia semplicemente vuoti la MRZ e i campi del retro nella risposta; questo endpoint non genera un avviso di MRZ mancante). Stesso formato e limiti di dimensione di `front_image`. Se omesso, `back_image` e i campi del retro risultano `null` nella risposta. back_image_password: type: string description: >- Password per decrittografare `back_image` quando è un PDF crittografato. writeOnly: true perform_document_liveness: type: boolean default: true description: >- Esegue lo screening di entrambe le immagini per rilevare frodi di presentazione: riproduzioni da schermo (`SCREEN_CAPTURE_DETECTED`), copie stampate (`PRINTED_COPY_DETECTED`) e manipolazione del ritratto (`PORTRAIT_MANIPULATION_DETECTED`). Ognuna di queste comporta il rifiuto automatico. Abilitato per impostazione predefinita; imposta su `false` per saltare lo screening antifrode e ridurre la latenza. Quando è abilitato e il provider non restituisce alcun punteggio utilizzabile, la risposta è `In Review` con un avviso `DOCUMENT_LIVENESS_NOT_COMPUTED` anziché `Approved`. example: true minimum_age: type: integer nullable: true default: null minimum: 1 maximum: 120 description: >- Accettato e convalidato (1–120) ma **attualmente non applicato** da questo endpoint — non produce mai un avviso `MINIMUM_AGE_NOT_MET` da questo campo. Applica le regole sull'età a partire da `date_of_birth`/`age` restituiti, oppure utilizza un workflow di sessione di verifica con restrizioni di età. expiration_date_not_detected_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- Cosa fare quando non è possibile leggere alcuna data di scadenza (`EXPIRATION_DATE_NOT_DETECTED`). Il valore predefinito è `NO_ACTION` perché molti documenti di identità non riportano alcuna data di scadenza stampata. Nota: una data di scadenza *rilevata e trascorsa* comporta sempre il rifiuto (`DOCUMENT_EXPIRED`), indipendentemente da questa opzione. invalid_mrz_action: type: string enum: - NO_ACTION - DECLINE default: DECLINE description: >- Cosa fare quando la MRZ estratta non supera la convalida delle cifre di controllo (`MRZ_VALIDATION_FAILED`). Una MRZ mancante non genera alcun avviso su questo endpoint. Rilevante solo per i documenti che contengono una MRZ. `REVIEW` non è supportato su questo endpoint e restituisce `400`. inconsistent_data_action: type: string enum: - NO_ACTION - DECLINE default: DECLINE description: >- Cosa fare quando i dati estratti sono internamente incoerenti: `DATA_INCONSISTENT`, `MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME` (la zona visiva non concorda con la MRZ) o `DOCUMENT_NAME_DIFFERENT_FROM_OTHER_APPROVED_DOCUMENTS`. critical_field_occlusion_action: type: string enum: - NO_ACTION - DECLINE default: DECLINE description: >- Cosa fare quando un campo stampato critico è stato fisicamente coperto nell'acquisizione (`CRITICAL_FIELD_OCCLUSION_DETECTED`) - un numero di identità, un nome, la data di nascita o la data di scadenza. Rifiuta per impostazione predefinita, come gli altri rischi di integrità del documento di questo endpoint: coprire i numeri rispetto ai quali viene riconciliato un report è l'aspetto tipico di un documento oscurato. Il valore letto per un campo coperto viene comunque escluso dall'estrazione, quindi l'avviso `*_NOT_DETECTED` corrispondente di solito lo accompagna. `REVIEW` non è supportato su questo endpoint e restituisce `400`. document_or_personal_number_format_mismatch_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- Cosa fare quando un numero non corrisponde al formato utilizzato dall'autorità emittente per quel tipo di documento (`DOCUMENT_NUMBER_FORMAT_MISMATCH`, `PERSONAL_NUMBER_FORMAT_MISMATCH`). Il valore predefinito è `NO_ACTION`, che segnala l'avviso senza modificare lo stato. `REVIEW` non è supportato su questo endpoint e restituisce `400`. preferred_characters: type: string enum: - latin - non_latin default: latin description: >- Sistema di scrittura preferito per i campi nome/indirizzo sui documenti che stampano sia testo in caratteri latini sia in caratteri non latini (arabo, cirillico, CJK, …). `latin` restituisce valori traslitterati/latini; `non_latin` preferisce il sistema di scrittura nativo. save_api_request: type: boolean default: true description: >- Quando è `true` (predefinito), rende persistente la chiamata come sessione di tipo API — visibile nella Business Console, recuperabile tramite `GET /v3/session/{sessionId}/decision/` utilizzando il `request_id` restituito, notificata tramite un webhook `status.updated`, e con le immagini del documento restituite come URL multimediali. Quando è `false`, non viene memorizzato nulla, `request_id` è un UUID temporaneo e le immagini vengono restituite inline come stringhe JPEG in base64. example: true vendor_data: type: string description: >- Stringa opaca opzionale (il tuo ID utente interno, email, UUID...) memorizzata nella sessione persistita e restituita nella risposta. Usala per correlare le chiamate API con i tuoi record e per filtrare le sessioni in un secondo momento. example: user-123 metadata: type: object additionalProperties: true description: >- Oggetto JSON opzionale memorizzato con la sessione (quando `save_api_request=true`) e restituito nella risposta. Nelle richieste multipart, invialo come campo stringa con codifica JSON (ad es. `metadata={"flow":"onboarding"}`): viene interpretato come oggetto. example: flow: onboarding example: front_image: (binary JPEG/PNG/PDF of the document front) back_image: (binary JPEG/PNG/PDF of the document back) perform_document_liveness: true save_api_request: true vendor_data: user-123 metadata: flow: onboarding responses: '200': description: >- Documento elaborato. `id_verification.status` è `Approved`, `Declined` o `In Review`; ogni problema rilevato è dettagliato in `id_verification.warnings`. Viene restituito `In Review` quando un controllo del rilevamento della vitalità del documento richiesto non ha prodotto alcun risultato utilizzabile (`DOCUMENT_LIVENESS_NOT_COMPUTED`). Un documento problematico restituisce comunque `200` con `status: "Declined"` — esamina il corpo, non solo il codice HTTP. Quando `save_api_request=true`, `request_id` è l'ID di sessione persistito e i campi immagine sono URL multimediali di breve durata; con `save_api_request=false` sono stringhe JPEG base64 inline. content: application/json: examples: Approved: summary: >- Carta d'identità fronte-retro letta chiaramente (salvata — immagini come URL dei contenuti multimediali) value: request_id: 11d219ed-d59c-4b1d-8d65-9b933f12d5b8 id_verification: status: Approved document_type: Identity Card document_subtype: ID_CARD_GENERIC document_number: CBX164224 personal_number: 20446581H portrait_image: >- https:///ocr/11d219ed-d59c-4b1d-8d65-9b933f12d5b8-portrait_image-8c2f.jpg?signature=... front_image: >- https:///ocr/11d219ed-d59c-4b1d-8d65-9b933f12d5b8-front_image-4a1e.jpg?signature=... back_image: >- https:///ocr/11d219ed-d59c-4b1d-8d65-9b933f12d5b8-back_image-77b0.jpg?signature=... front_image_camera_front: null back_image_camera_front: null front_image_camera_front_face_match_score: null back_image_camera_front_face_match_score: null front_image_quality_score: focus_score: 78 brightness_score: 83.2 brightness_issue: ok is_document_fully_visible: true resolution_score: 40.7 overall_score: 70.2 back_image_quality_score: focus_score: 100 brightness_score: 95.6 brightness_issue: ok is_document_fully_visible: true resolution_score: 43 overall_score: 84.4 date_of_birth: '1980-01-13' age: 46 expiration_date: '2032-03-31' date_of_issue: '2022-03-31' issuing_state: ESP issuing_state_name: Spain first_name: Julio Francisco last_name: Fores Sena full_name: Julio Francisco Fores Sena gender: M address: >- Brda. Urb. El Cardonal 0052 52 Po3 B,Taco,San Cristobal De La Laguna,Santa Cruz De Tenerife formatted_address: >- Av. el Cardonal, 52, b, 38108 La Laguna, Santa Cruz de Tenerife, Spain place_of_birth: Valencia, Valencia marital_status: UNKNOWN nationality: ESP extra_fields: first_surname: Fores second_surname: Sena mrz: surname: FORES SENA name: JULIO FRANCISCO country: ESP nationality: ESP birth_date: '800113' expiry_date: '320331' sex: M document_type: ID document_number: CBX164224 optional_data: 20446581H optional_data_2: '' birth_date_hash: '9' expiry_date_hash: '8' document_number_hash: '3' final_hash: '3' personal_number: 20446581H warnings: [] errors: [] mrz_type: TD1 mrz_string: |- IDESPCBX164224320446581H<<<<<< 8001139M3203318ESP<<<<<<<<<<<3 FORES- Av. el Cardonal, 52, b, 38108 La Laguna, Santa Cruz de Tenerife, Spain raw_results: address_components: - long_name: b short_name: b types: - subpremise - long_name: '52' short_name: '52' types: - street_number - long_name: Avenida el Cardonal short_name: Av. el Cardonal types: - route - long_name: La Laguna short_name: La Laguna types: - locality - political - long_name: Spain short_name: ES types: - country - political - long_name: '38108' short_name: '38108' types: - postal_code formatted_address: >- Av. el Cardonal, 52, b, 38108 La Laguna, Santa Cruz de Tenerife, Spain geometry: location: lat: 28.4501161 lng: -16.3004407 location_type: ROOFTOP types: - street_address - subpremise document_location: latitude: 28.4501161 longitude: -16.3004407 label: Spain Identity Card Address is_verified: true category: Residential warnings: [] barcodes: [] vendor_data: user-123 metadata: flow: onboarding created_at: '2026-06-12T02:21:56.013573+00:00' Declined - expired document: summary: Caricamento del solo fronte di una carta d'identità scaduta value: request_id: f61681b8-9422-4378-ac3e-04c6a247fb45 id_verification: status: Declined document_type: Identity Card document_subtype: ID_CARD_GENERIC document_number: BNK123072 personal_number: 21771255F portrait_image: >- https:///ocr/f61681b8-9422-4378-ac3e-04c6a247fb45-portrait_image-1d9a.jpg?signature=... front_image: >- https:///ocr/f61681b8-9422-4378-ac3e-04c6a247fb45-front_image-5c2b.jpg?signature=... back_image: null front_image_camera_front: null back_image_camera_front: null front_image_camera_front_face_match_score: null back_image_camera_front_face_match_score: null front_image_quality_score: focus_score: 100 brightness_score: 95.7 brightness_issue: ok is_document_fully_visible: true resolution_score: 22.2 overall_score: 79.3 back_image_quality_score: null date_of_birth: '1997-01-30' age: 29 expiration_date: '2025-11-26' date_of_issue: null issuing_state: ESP issuing_state_name: Spain first_name: Lucia last_name: Marin Castro full_name: Lucia Marin Castro gender: F address: null formatted_address: null place_of_birth: null marital_status: UNKNOWN nationality: ESP extra_fields: first_surname: Marin second_surname: Castro mrz: {} parsed_address: null warnings: - risk: DOCUMENT_EXPIRED feature: ID_VERIFICATION additional_data: null log_type: error short_description: Document expired long_description: >- The document's expiration date has passed, rendering it no longer valid for use. barcodes: [] vendor_data: user-123 metadata: null created_at: '2026-06-12T02:25:48.117204+00:00' 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. id_verification: type: object properties: status: type: string enum: - Approved - Declined - In Review description: >- `Approved` quando nessun avviso si traduce in un rifiuto e il controllo di vitalità del documento richiesto ha prodotto un risultato utilizzabile; `In Review` quando tale controllo richiesto non ha prodotto alcun risultato utilizzabile (`DOCUMENT_LIVENESS_NOT_COMPUTED`); `Declined` quando un avviso si traduce in un rifiuto: l'elenco `warnings` ne spiega il motivo. document_type: type: string nullable: true description: >- Nome visualizzato del tipo di documento rilevato: `Identity Card`, `Passport`, `Driver's License`, `Residence Permit`, `Health Insurance Card` o `Tax Card`. `null` quando non è stato possibile classificare il documento. example: Identity Card document_subtype: type: string nullable: true description: >- Sottotipo più dettagliato quando disponibile (ad es. `ID_CARD_GENERIC`, `EPASSPORT`). example: ID_CARD_GENERIC document_number: type: string nullable: true example: CBX164224 personal_number: type: string nullable: true description: >- Numero personale/nazionale secondario stampato su alcuni documenti. example: 20446581H portrait_image: type: string nullable: true description: >- Foto ritagliata del ritratto dal documento. Un URL multimediale a breve durata (`https:///ocr/...`) quando `save_api_request=true` (predefinito); una stringa JPEG inline codificata in base64 quando `save_api_request=false`. `null` se non è stato rilevato alcun ritratto. front_image: type: string nullable: true description: >- Ritaglio allineato del fronte del documento. URL multimediale quando salvato, JPEG base64 inline altrimenti. back_image: type: string nullable: true description: >- Ritaglio allineato del retro del documento. `null` quando non è stato caricato alcun `back_image`. front_image_camera_front: type: string nullable: true description: >- Sempre `null` su questo endpoint (compilato solo nelle sessioni di verifica con acquisizione da fotocamera). back_image_camera_front: type: string nullable: true description: Sempre `null` su questo endpoint. front_image_camera_front_face_match_score: type: number nullable: true description: Sempre `null` su questo endpoint. back_image_camera_front_face_match_score: type: number nullable: true description: Sempre `null` su questo endpoint. front_image_quality_score: type: object nullable: true description: >- Diagnostica della qualità di acquisizione per l'immagine caricata (`null` quando il lato non è stato fornito o il calcolo del punteggio non è riuscito). Tutti i punteggi vanno da 0 a 100. properties: focus_score: type: number format: float description: >- Nitidezza del ritaglio del documento (più alta è, maggiore è la nitidezza). brightness_score: type: number format: float description: Qualità dell'esposizione (più alta è migliore). brightness_issue: type: string nullable: true description: >- `ok` quando l'esposizione è adeguata, altrimenti il problema rilevato (ad es. troppo scura / troppo luminosa). is_document_fully_visible: type: boolean nullable: true description: >- Indica se tutti e quattro gli angoli del documento si trovano all'interno dell'inquadratura. resolution_score: type: number format: float description: Risoluzione effettiva dell'area del documento. overall_score: type: number format: float description: Punteggio di qualità aggregato. back_image_quality_score: type: object nullable: true description: >- Diagnostica della qualità di acquisizione per l'immagine caricata (`null` quando il lato non è stato fornito o il calcolo del punteggio non è riuscito). Tutti i punteggi vanno da 0 a 100. properties: focus_score: type: number format: float description: >- Nitidezza del ritaglio del documento (più alta è, maggiore è la nitidezza). brightness_score: type: number format: float description: Qualità dell'esposizione (più alta è migliore). brightness_issue: type: string nullable: true description: >- `ok` quando l'esposizione è adeguata, altrimenti il problema rilevato (ad es. troppo scura / troppo luminosa). is_document_fully_visible: type: boolean nullable: true description: >- Indica se tutti e quattro gli angoli del documento si trovano all'interno dell'inquadratura. resolution_score: type: number format: float description: Risoluzione effettiva dell'area del documento. overall_score: type: number format: float description: Punteggio di qualità aggregato. date_of_birth: type: string format: date nullable: true example: '1980-01-13' age: type: integer nullable: true description: >- Età del titolare in anni, calcolata da `date_of_birth`. example: 46 expiration_date: type: string format: date nullable: true example: '2032-03-31' date_of_issue: type: string format: date nullable: true example: '2022-03-31' issuing_state: type: string nullable: true description: Paese di emissione (ISO 3166-1 alpha-3). example: ESP issuing_state_name: type: string nullable: true example: Spain first_name: type: string nullable: true example: Julio Francisco last_name: type: string nullable: true example: Fores Sena full_name: type: string nullable: true example: Julio Francisco Fores Sena gender: type: string nullable: true description: '`M`, `F` o `null` quando non stampato/rilevato.' example: M address: type: string nullable: true description: Indirizzo esattamente come stampato sul documento. formatted_address: type: string nullable: true description: Versione geocodificata e normalizzata di `address`. place_of_birth: type: string nullable: true example: Valencia, Valencia marital_status: type: string nullable: true description: >- `UNKNOWN` a meno che il documento non riporti lo stato civile. example: UNKNOWN nationality: type: string nullable: true description: Nazionalità del titolare (ISO 3166-1 alpha-3). example: ESP extra_fields: type: object nullable: true additionalProperties: true description: >- Dati aggiuntivi specifici del documento privi di una colonna dedicata (ad es. `first_surname`/`second_surname` sui documenti di identità spagnoli, categorie di patente sulle patenti di guida). mrz: type: object description: >- Zona a lettura ottica analizzata. Un **oggetto vuoto** (`{}`) quando il documento non ha una MRZ o non è stato possibile leggerla — in tal caso controlla anche l'elenco `warnings`. Le date all'interno della MRZ utilizzano il formato grezzo `YYMMDD`. properties: surname: type: string example: FORES SENA name: type: string example: JULIO FRANCISCO country: type: string description: Paese di emissione (ISO 3166-1 alpha-3). example: ESP nationality: type: string description: Nazionalità del titolare (ISO 3166-1 alpha-3). example: ESP birth_date: type: string description: Data di nascita MRZ non elaborata (`YYMMDD`). example: '800113' expiry_date: type: string description: Data di scadenza MRZ non elaborata (`YYMMDD`). example: '320331' sex: type: string example: M document_type: type: string description: >- Codice del tipo di documento MRZ (ad es. `ID`, `P`). example: ID document_number: type: string example: CBX164224 optional_data: type: string nullable: true example: 20446581H optional_data_2: type: string nullable: true example: '' birth_date_hash: type: string description: Cifra di controllo MRZ per la data di nascita. example: '9' expiry_date_hash: type: string description: Cifra di controllo MRZ per la data di scadenza. example: '8' document_number_hash: type: string description: >- Cifra di controllo MRZ per il numero del documento. example: '3' final_hash: type: string description: Cifra di controllo MRZ composita. example: '3' personal_number: type: string nullable: true example: 20446581H warnings: type: array items: type: string description: >- Avvisi non fatali relativi all'analisi del codice MRZ. errors: type: array items: type: string description: >- Errori di parsing/cifra di controllo MRZ. Gli errori non vuoti vengono segnalati come avviso `MRZ_VALIDATION_FAILED`. mrz_type: type: string description: >- Formato MRZ: `TD1` (carte d'identità, 3 righe), `TD2` o `TD3` (passaporti, 2 righe). example: TD1 mrz_string: type: string description: >- Testo MRZ non elaborato così come letto, righe separate da `\n`. mrz_key: type: string description: >- Chiave composita (numero del documento + cifre di controllo) utilizzata per i controlli incrociati. parsed_address: type: object nullable: true description: >- Suddivisione geocodificata e strutturata di `address`. `null` se il documento non contiene alcun indirizzo o se non è stato possibile analizzarlo. properties: street_1: type: string nullable: true example: Avenida el Cardonal 52 street_2: type: string nullable: true example: b city: type: string nullable: true example: La Laguna region: type: string nullable: true example: Canarias country: type: string nullable: true description: Codice paese ISO 3166-1 alpha-2. example: ES postal_code: type: string nullable: true example: '38108' address_type: type: string nullable: true example: Avenida formatted_address: type: string nullable: true description: Stringa dell'indirizzo geocodificato canonico. example: >- Av. el Cardonal, 52, b, 38108 La Laguna, Santa Cruz de Tenerife, Spain raw_results: type: object additionalProperties: true description: >- Payload di geocodifica non elaborato (`address_components`, `geometry.location`, `place_id`, …) per utilizzi avanzati. document_location: type: object nullable: true properties: latitude: type: number longitude: type: number description: >- Coordinate geocodificate dell'indirizzo del documento. label: type: string nullable: true description: >- Da quale campo del documento è stato letto l'indirizzo. example: Spain Identity Card Address is_verified: type: boolean description: >- Indica se la geocodifica ha confermato l'esistenza dell'indirizzo. category: type: string nullable: true description: >- Categoria dell'indirizzo (ad es. `Residential`, `Commercial`). example: Residential warnings: type: array description: >- Vuoto in caso di approvazione senza anomalie. Ogni voce illustra un rischio rilevato; le voci con `log_type: "error"` impostano `status` su `Declined`, mentre `DOCUMENT_LIVENESS_NOT_COMPUTED` (`log_type: "warning"`) lo imposta su `In Review`. items: type: object properties: risk: type: string description: >- Codice di rischio leggibile dalla macchina. Rischi con rifiuto automatico: `DOCUMENT_EXPIRED`, `MINIMUM_AGE_NOT_MET`, `PORTRAIT_IMAGE_NOT_DETECTED`, `SCREEN_CAPTURE_DETECTED`, `PRINTED_COPY_DETECTED`, `PORTRAIT_MANIPULATION_DETECTED`, `PUBLIC_DOCUMENT_IMAGE_DETECTED`, `INVALID_DATE`, `COULD_NOT_RECOGNIZE_DOCUMENT` (solo 400, mai un avviso), `DOCUMENT_NUMBER_NOT_DETECTED`, `COULD_NOT_DETECT_DOCUMENT_TYPE`, `NAME_NOT_DETECTED`, `DATE_OF_BIRTH_NOT_DETECTED`. Regolati dalle opzioni della richiesta: `MRZ_NOT_DETECTED` / `MRZ_VALIDATION_FAILED` (`invalid_mrz_action`), `DATA_INCONSISTENT` / `MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME` / `DOCUMENT_NAME_DIFFERENT_FROM_OTHER_APPROVED_DOCUMENTS` (`inconsistent_data_action`), `EXPIRATION_DATE_NOT_DETECTED` (`expiration_date_not_detected_action`). Altri rischi (es. `POSSIBLE_DUPLICATED_USER`) sono informativi. `DOCUMENT_LIVENESS_NOT_COMPUTED` viene generato quando `perform_document_liveness=true` ma il controllo di contraffazione non ha restituito alcun punteggio utilizzabile; imposta `status` su `In Review`. `COULD_NOT_DETECT_DOCUMENT_TYPE` viene restituito anche quando il fronte del documento non corrisponde con elevata affidabilità al modello di un documento ufficiale noto, ad esempio un documento modificato, generato al computer o con un modello non ancora supportato. example: DOCUMENT_EXPIRED feature: type: string enum: - ID_VERIFICATION description: >- Funzionalità che ha generato l'avviso. Sempre `ID_VERIFICATION` su questo endpoint. additional_data: type: object nullable: true additionalProperties: true description: >- Contesto aggiuntivo per alcuni rischi (ad es. `POSSIBLE_DUPLICATED_USER` include `duplicated_session_id`); `null` per la maggior parte. log_type: type: string enum: - error - warning - information description: >- Gravità. Gli avvisi `error` portano `status` a `Declined`; `warning` (solo `DOCUMENT_LIVENESS_NOT_COMPUTED`, quando il controllo anti-manomissione richiesto non ha prodotto un punteggio utilizzabile) porta `status` a `In Review`; le voci `information` sono informative e non modificano mai lo stato. short_description: type: string description: >- Riepilogo del rischio su una riga leggibile dall'utente. long_description: type: string description: Spiegazione di facile lettura del rischio. barcodes: type: array description: >- Codici a barre decodificati dal documento (PDF417, QR, …). Vuoto se il documento non ne contiene o non è stato possibile leggerne alcuno. items: type: object properties: type: type: string description: >- Tipo di codice a barre (ad es. `PDF417`, `QR_CODE`, `UNKNOWN`). position: type: object nullable: true additionalProperties: true description: >- Posizione del codice a barre nell'immagine, quando disponibile. data: type: string description: Payload decodificato. data_raw: type: string description: >- Payload non elaborato (non decodificato), se diverso. side: type: string nullable: true description: '`front` o `back`.' vendor_data: type: string nullable: true description: Eco del `vendor_data` inviato, o `null`. metadata: type: object nullable: true additionalProperties: true description: Eco dell'oggetto `metadata` inviato, o `null`. created_at: type: string format: date-time description: Timestamp ISO 8601 (UTC) di generazione della risposta. '400': description: >- Errore di validazione o di elaborazione. I problemi a livello di campo restituiscono l'envelope standard di DRF (un array di messaggi per ciascun campo interessato). I problemi relativi a PDF crittografati restituiscono `{"detail": ...}`. Un'immagine del documento in cui non è possibile riconoscere alcun documento restituisce `{"error": "COULD_NOT_RECOGNIZE_DOCUMENT"}`. I caricamenti di PDF possono inoltre non riuscire con "The submitted PDF file is corrupted or invalid." o con un errore di assenza di pagine. content: application/json: examples: Missing front image: summary: '`front_image` non incluso nei dati del modulo' value: front_image: - No file was submitted. Unsupported file extension: summary: Estensione del file diversa da tiff/jpg/jpeg/png/webp/pdf value: front_image: - >- File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, webp, pdf. File too large: summary: Il caricamento supera il limite di 10 MB value: front_image: - File size should not exceed 10 MB Invalid option value: summary: Le opzioni accettano solo DECLINE o NO_ACTION value: invalid_mrz_action: - '"REVIEW" is not a valid choice.' Encrypted PDF: summary: PDF caricato senza la password richiesta value: detail: >- The PDF is encrypted. Please upload a decrypted PDF or a photo instead. Wrong PDF password: summary: >- `front_image_password` / `back_image_password` non decifra il PDF value: detail: >- The PDF password is incorrect. Please provide the correct password. Document not recognized: summary: Nessun documento d'identità rilevato nell'immagine value: error: COULD_NOT_RECOGNIZE_DOCUMENT PDF conversion failure: summary: Impossibile convertire il PDF caricato in un'immagine value: error: Failed to convert front image PDF. '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 elaborazione delle immagini. 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 '503': $ref: '#/components/responses/DocumentProcessingBusy' security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: cURL source: |- curl -X POST 'https://verification.didit.me/v3/id-verification/' \ -H 'x-api-key: YOUR_API_KEY' \ -F 'front_image=@./id_front.jpg' \ -F 'back_image=@./id_back.jpg' \ -F 'perform_document_liveness=true' \ -F 'save_api_request=true' \ -F 'vendor_data=user-123' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.id_verification.verify( front_image=open("front_image.jpg", "rb"), back_image=open("back_image.jpg", "rb"), perform_document_liveness=True, save_api_request=True, vendor_data="user-123", metadata={"flow": "onboarding"}, ) print(result) - lang: javascript label: Node.js source: |- import Didit, { fileFromPath } from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.idVerification.verify({ front_image: await fileFromPath("front_image.jpg"), back_image: await fileFromPath("back_image.jpg"), perform_document_liveness: true, save_api_request: true, vendor_data: "user-123", metadata: { flow: "onboarding" }, }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDVerification.Verify(ctx, didit.IDVerificationVerifyParams{\n\tFrontImage: didit.FileFromPath(\"front_image.jpg\"),\n\tBackImage: didit.Some(didit.FileFromPath(\"back_image.jpg\")),\n\tPerformDocumentLiveness: didit.Bool(true),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n\tMetadata: didit.Some(map[string]any{\"flow\": \"onboarding\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.nio.file.Path; import java.util.Map; import me.didit.Didit; import me.didit.types.IdVerificationVerifyParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.idVerification().verify(IdVerificationVerifyParams.builder() .frontImage(Path.of("front_image.jpg")) .backImage(Path.of("back_image.jpg")) .performDocumentLiveness(true) .saveApiRequest(true) .vendorData("user-123") .metadata(Map.of("flow", "onboarding")) .build()); System.out.println(result); - lang: php label: PHP source: |- idVerification->verify([ 'front_image' => File::fromPath('front_image.jpg'), 'back_image' => File::fromPath('back_image.jpg'), 'perform_document_liveness' => true, 'save_api_request' => true, 'vendor_data' => 'user-123', 'metadata' => ['flow' => 'onboarding'], ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.id_verification.verify( front_image: Pathname("front_image.jpg"), back_image: Pathname("back_image.jpg"), perform_document_liveness: true, save_api_request: true, vendor_data: "user-123", metadata: { flow: "onboarding" } ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Collections.Generic; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.IdVerification.VerifyAsync(new IdVerificationVerifyParams { FrontImage = FileUpload.FromPath("front_image.jpg"), BackImage = FileUpload.FromPath("back_image.jpg"), PerformDocumentLiveness = true, SaveApiRequest = true, VendorData = "user-123", Metadata = new Dictionary { ["flow"] = "onboarding" }, }); Console.WriteLine(JsonSerializer.Serialize(result)); components: responses: DocumentProcessingBusy: description: >- Al momento sono in fase di elaborazione troppi documenti, pertanto questo caricamento non è stato elaborato: non è stato memorizzato nulla e non è stato utilizzato alcun tentativo. Invia nuovamente lo stesso file dopo il numero di secondi indicato in `Retry-After`. Basa la logica su `code`, non sul testo del messaggio. headers: Retry-After: description: >- Secondi da attendere prima di inviare nuovamente la stessa richiesta. schema: type: integer example: 10 content: application/json: schema: type: object required: - detail - code properties: detail: type: string code: type: string enum: - document_processing_busy example: detail: We are busy processing documents. Please try again in a moment. code: document_processing_busy 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.