> ## 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. # Importare dati da un altro provider KYC > Importa con Didit sessioni di verifica storiche, utenti, volti, blocklist, aziende, transazioni e regole di stato dei workflow. Usa questa guida per scegliere il percorso di importazione corretto quando sposti dati da un altro provider in Didit. Con "importazione" i clienti intendono spesso due operazioni diverse:- **Importare verifiche storiche**: ricreare record storici di verifiche KYC e KYB, di monitoraggio delle transazioni o di regole del workflow già completate, così che Didit mostri lo storico del vecchio provider. Usa `POST /v3/session/imports/`. - **Importare dati operativi**: creare Users, Businesses, volti del profilo, voci di blocklist o di allowlist, così che Didit possa usarli nei controlli futuri. Usa le API delle entità, dei volti e delle liste.Le importazioni di verifiche creano record storici con `session_type: "MIGRATED"` per KYC e KYB. Non inviano email agli utenti finali, non reindirizzano gli utenti al flusso ospitato e non rieseguono la verifica originale. I record importati compaiono negli elenchi delle sessioni, nei profili delle entità, nelle viste delle transazioni e in `GET /v3/session/{session_id}/decision/` dove applicabile.## Quale importazione usare?| Obiettivo | Percorso di importazione da usare | Cosa crea | Ideale per | | - | - | - | - | | Ricreare sessioni KYC storiche | `POST /v3/session/imports/` con `import_type=user_verification` | `Session`, dati di Verifica dell'identità, immagini opzionali di documento e selfie, video del documento e del rilevamento della vitalità, tag, metadati | Trasferire richiedenti già completati da Sumsub, MetaMap, Veriff, Onfido, Persona, Jumio, Incode, iDenfy, Trulioo o da un altro provider KYC | | Ricreare sessioni KYB storiche | `POST /v3/session/imports/` con `import_type=business_verification` | `BusinessSession`, dati dell'azienda nel registro delle imprese, dirigenti, titolari effettivi, tag, metadati | Trasferire controlli aziendali già completati da fornitori KYB, provider di registri delle imprese o strumenti KYB interni | | Ricreare record storici di monitoraggio delle transazioni | `POST /v3/session/imports/` con `import_type=transactions` | `Transaction`, parti soggette e controparti, risultati dei provider, dati Travel Rule, snapshot della rete, metadati | Trasferire lo storico di motori di regole, KYT, screening dei wallet o monitoraggio delle transazioni fiat | | Importare regole personalizzate di stato del workflow | `POST /v3/session/imports/` con `import_type=status_rules` | `VerificationSettings.feature_status_rules` | Trasferire la logica di policy da un altro provider o da un foglio di calcolo nel motore di workflow di Didit | | Creare Users senza sessioni storiche | `POST /v3/users/create/` oppure importazione CSV dalla Console | Righe di profilo `VendorUser` | Caricare l'elenco degli utenti prima di avviare nuovi controlli Didit | | Associare volti del profilo attendibili agli utenti | `POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/` | Evidenze dei volti del profilo indicizzate per il rilevamento dei duplicati e per la ricerca facciale | Migrare immagini dei volti del profilo da un altro provider KYC senza ricreare le sessioni complete | | Inserire in blocklist o allowlist dei volti | `POST /v3/lists/{list_uuid}/entries/face-upload/` oppure `POST /v3/lists/{list_uuid}/entries/` con `reference_session_id` | Voce di lista dei volti ed embedding biometrico | Migrare volti di frode noti, volti attendibili in allowlist, oppure inserire in blocklist un volto da una sessione Didit esistente | | Creare Businesses senza sessioni KYB storiche | `POST /v3/businesses/create/` oppure importazione CSV dalla Console | Righe di profilo `VendorBusiness` | Caricare l'elenco dei clienti aziendali prima di eseguire controlli KYB |> [!NOTE] > > Se ti serve solo un profilo utente o aziendale per i controlli futuri, non importare una sessione di verifica storica. Usa le API delle entità User o Business. Se vuoi che la decisione, i campi del documento, gli avvisi o le evidenze del vecchio provider compaiano in Didit come storico di conformità, usa `POST /v3/session/imports/`.## Cosa può essere migrato da ciascun provider?Didit accetta un file CSV o NDJSON in formato canonico, quindi puoi migrare da qualsiasi provider dopo aver esportato e trasformato i dati. Lo schema di importazione è sempre quello canonico di Didit.| Famiglia di provider | Fonti tipiche | Generalmente migrabili | Note | | - | - | - | - | | Provider KYC | Sumsub, MetaMap, Veriff, Onfido, Persona, Jumio, Incode, iDenfy, Trulioo, HyperVerge, AU10TIX, Mitek, Ondato | ID dell'applicant, ID utente del provider, stato della decisione, campi del documento, immagini del documento, immagine selfie/liveness, etichette di rifiuto, tag, metadati grezzi del provider | Usa `import_type=user_verification`. Se il provider non può esportare le immagini, importa i campi strutturati e lascia vuoti gli URL delle immagini. | | Provider KYB | Provider di registri delle imprese, Sumsub KYB, Trulioo KYB, esportazioni di registri in stile Creditsafe, strumenti KYB interni | Nome dell'azienda, numero di registrazione, paese, stato nel registro, esponenti aziendali, titolari effettivi, livello di rischio, payload grezzo del registro | Usa `import_type=business_verification`. Esponenti aziendali e titolari effettivi vengono passati come array JSON. | | Provider di monitoraggio delle transazioni / KYT | Sumsub Transaction Monitoring, esportazioni KYT in stile Chainalysis, Crystal, Merkle Science, Sardine, Unit21, Alloy, motori di regole interni | ID transazione, importo, valuta, direzione, soggetto/controparte, riscontri delle regole, risultati del provider, stato della Travel Rule, snapshot del grafo di rete | Usa `import_type=transactions`. Le transazioni importate sono record storici e, per impostazione predefinita, non vengono sottoposte di nuovo a screening. | | Fogli di workflow e policy | Esportazioni delle policy di compliance, tabelle di regole dei provider, fogli di rischio interni | Regole di stato per funzionalità, ad esempio «se il paese di emissione è X, imposta Verifica dell'identità su In revisione» | Usa `import_type=status_rules`. Le regole vengono validate rispetto al catalogo dei campi workflow di Didit prima di essere salvate. | | Archivi di utenti e profili | CRM, database clienti, esportazione utenti del provider, data warehouse | `vendor_data`, nome visualizzato, metadati, tag, immagini facciali attendibili | Usa le API degli utenti e il caricamento dei volti del profilo. Non equivale a una sessione di verifica completata. | | Dati di blocklist e allowlist | Liste di frode dei provider, fogli operativi antifrode interni, liste di chargeback, liste interne vicine alle sanzioni | Email, telefoni, documenti, wallet, IP, impronte digitali del dispositivo, volti, paesi, utenti, aziende | Usa le API delle liste. Per le immagini dei volti, usa l'endpoint dedicato al caricamento dei volti, così Didit può estrarre l'embedding biometrico. |## Flusso di migrazione1) Decidi se vuoi importare storico, profili, volti, liste, transazioni o regole. 2) Esporta i dati dal vecchio provider in autonomia. Non inviare a Didit le chiavi API del vecchio provider. 3) Trasforma l'esportazione del provider nel template CSV o NDJSON canonico di Didit corrispondente. 4) Per le migrazioni di grandi dimensioni, preferisci NDJSON e suddividi i dati in file che puoi riprovare in modo indipendente. 5) Crea il job di importazione e controllane l'avanzamento. 6) Recupera gli errori di riga, correggi solo le righe non riuscite e ritentale. Tutti i job di importazione sono idempotenti sul loro ID esterno naturale.## Crea un job di importazioneCrea un job di importazione con una singola richiesta multipart:```bash theme={null} curl -X POST https://verification.didit.me/v3/session/imports/ \ -H "x-api-key: YOUR_API_KEY" \ -F "import_type=user_verification" \ -F "workflow_id=YOUR_KYC_WORKFLOW_ID" \ -F "file=@didit-import.ndjson" ```Usa CSV per migrazioni più piccole basate su fogli di calcolo e NDJSON per le migrazioni di grandi dimensioni. Con 100k+ righe, NDJSON è più facile da trasmettere in streaming, suddividere, validare e ritentare.Un'applicazione può eseguire fino a 4 job di importazione contemporaneamente, quindi suddividi una migrazione grande in più file e avvia un job per ciascuno. Ogni job scarica in parallelo i file multimediali di una riga. Un job interrotto da un deploy o dal riavvio di un worker riprende automaticamente dall'ultima riga importata, quindi non devi riavviarlo.Per le importazioni di transazioni, ometti `workflow_id`:```bash theme={null} curl -X POST https://verification.didit.me/v3/session/imports/ \ -H "x-api-key: YOUR_API_KEY" \ -F "import_type=transactions" \ -F "file=@didit-transactions.ndjson" ```### Campi della richiesta| Campo | Obbligatorio | Descrizione | | - | - | - | | `import_type` | No, predefinito `user_verification` | Uno tra `user_verification`, `business_verification`, `status_rules`, `transactions`. | | `workflow_id` | Sì, tranne per `transactions` | UUID del workflow a cui si collegano i record importati. `user_verification` e `status_rules` richiedono un workflow di Verifica degli utenti; `business_verification` richiede un workflow di Verifica aziendale. | | `file` | Uno tra `file` e `source_file_url` | Il file CSV o NDJSON canonico, caricato inline. | | `source_file_url` | Uno tra `file` e `source_file_url` | URL HTTPS da cui Didit scarica il file. Gli URL di rete privata vengono rifiutati. | | `source_format` | No | `csv` o `ndjson`. Viene dedotto dall'estensione del file se omesso. |### Come vengono tracciati e deduplicati i recordNon esiste un campo della richiesta per la sorgente dei dati: ogni importazione usa lo schema canonico di Didit. Ogni record importato salva `metadata.imported_from = "generic"` per la tracciabilità.Le importazioni `user_verification` e `business_verification` deduplicano le righe su `external_id` all'interno dell'applicazione, quindi ritentare lo stesso file non crea duplicati. Le importazioni `transactions` deduplicano invece su `transaction_id`.Una migrazione da provider (`source=provider`) salva ogni record come `:`, ad esempio `sumsub:5f8c0e2a9b1d4c3e2f1a0b9c`. Un'importazione di file di Verifica degli utenti che ha inviato l'ID del provider senza prefisso (`5f8c0e2a9b1d4c3e2f1a0b9c`) viene riconosciuta come lo stesso record, in entrambe le direzioni. Puoi quindi avviare una migrazione tramite file e completarla con una migrazione da provider, o viceversa, senza importare due volte lo stesso record.## Importare foto dei documenti, video e selfie come provaPer `import_type=user_verification`, puoi importare le foto originali dei documenti, i video di acquisizione del documento e del rilevamento della vitalità e l'immagine selfie dal provider precedente.Usa queste colonne canoniche:| Prova | Colonna preferita | Alternativa per importazioni di piccole dimensioni | Archiviata in Didit come | | - | - | - | - | | Immagine fronte del documento | `document_front_url` | `document_front_base64` | Immagine fronte OCR di Verifica dell'identità | | Immagine retro del documento | `document_back_url` | `document_back_base64` | Immagine retro OCR di Verifica dell'identità | | Selfie / immagine di rilevamento della vitalità | `selfie_url` | `selfie_base64` | Immagine di riferimento Face/Liveness | | Video fronte del documento | `document_front_video_url` | solo URL | Video fronte OCR di Verifica dell'identità | | Video retro del documento | `document_back_video_url` | solo URL | Video retro OCR di Verifica dell'identità | | Video di rilevamento della vitalità | `liveness_video_url` | solo URL | Video di acquisizione Face/Liveness |Per le migrazioni di grandi dimensioni, usa **URL HTTPS**. Didit scarica ogni file, verifica che l'URL sia sicuro, salva una copia di proprietà di Didit e la collega alla sessione importata. Le immagini vengono compresse; i video vengono salvati così come sono. Il base64 inline è accettato per le immagini nelle importazioni di piccole dimensioni, ma **i video devono essere sempre forniti come URL**: il base64 aumenterebbe ogni video di circa il 33% e supererebbe rapidamente il limite di importazione per file.Esempio di riga NDJSON con URL dei media ospitati dal provider:```json theme={null} { "external_id": "applicant-123", "vendor_data": "user-42", "created_at": "2025-01-12T10:30:00Z", "status": "Approved", "email": "user@example.com", "phone": "+34687020083", "first_name": "Jane", "last_name": "Doe", "date_of_birth": "1990-05-15", "document_type": "P", "issuing_state": "USA", "document_number": "123456789", "expiration_date": "2030-01-15", "document_front_url": "https://provider-export.example.com/files/applicant-123-front.jpg", "document_back_url": "https://provider-export.example.com/files/applicant-123-back.jpg", "selfie_url": "https://provider-export.example.com/files/applicant-123-selfie.jpg", "document_front_video_url": "https://provider-export.example.com/files/applicant-123-front.webm", "document_back_video_url": "https://provider-export.example.com/files/applicant-123-back.webm", "liveness_video_url": "https://provider-export.example.com/files/applicant-123-liveness.mp4", "reject_reasons_json": "[]", "provider_metadata_json": "{\"source\":\"sumsub-export\"}" } ```Regole importanti sui media:- Gli URL devono usare `https`. - Gli URL non devono risolvere in indirizzi IP privati, localhost, intervalli link-local o host di metadati interni. - Per le immagini si accetta una colonna URL oppure la relativa alternativa `*_base64`; se sono impostate entrambe, ha precedenza il base64. I video accettano solo URL: non esiste una colonna `*_video_base64`. - I video devono essere `mp4`, `webm` o `mov`, e ciascun video può avere una dimensione massima di **10 MB**. I file più grandi o non video vengono rifiutati come errori di riga. - Didit applica timeout di connessione e lettura, una dimensione massima dei file e non effettua tentativi infiniti. - Gli errori di download dei media vengono salvati come errori di riga, così il resto dell'importazione può proseguire. - Se non hai media dal provider, lascia vuote queste colonne. Didit importa comunque i dati strutturati della decisione e i campi del documento. - Immagini e video importati sono una prova per la revisione storica. Per impostazione predefinita, Didit non riesegue OCR, analisi di vitalità o analisi delle frodi documentali sui media storici importati. Prompt per l'importazione della Verifica degli utenti Copia il prompt negli appunti \

\`You are helping migrate historical User Verification (KYC) sessions into Didit.

Goal:
Transform the customer's Sumsub, MetaMap, or provider export into Didit's canonical verification import file, then call Didit's import API.

Didit API:
\- Create import job: POST https://verification.didit.me/v3/session/imports/
\- Poll job: GET https://verification.didit.me/v3/session/imports/{import_id}/
\- Read row errors: GET https://verification.didit.me/v3/session/imports/{import_id}/errors/
\- Download template: GET https://verification.didit.me/v3/session/imports/template/?import_type=user_verification
\- Authenticate with x-api-key: 

Inputs you need:
\- DIDIT_API_KEY
\- DIDIT_WORKFLOW_ID for a User Verification workflow
\- Provider export file or API output

Canonical columns:
external_id, vendor_data, created_at, status, email, phone, first_name, last_name, date_of_birth, gender, nationality, document_type, issuing_state, document_number, personal_number, expiration_date, document_front_url, document_back_url, selfie_url, document_front_base64, document_back_base64, selfie_base64, document_front_video_url, document_back_video_url, liveness_video_url, is_blocklisted, reject_reasons_json, tags, provider_metadata_json

Rules:
\- phone is optional and accepts international format (for example +34687020083); it is stored on the imported session.
\- external_id must be the provider's unique verification/applicant id.
\- vendor_data must be the customer's stable user id. If absent, use the provider identity/user id.
\- status must be Approved, Declined, In Review, or Expired.
\- date_of_birth and expiration_date must use YYYY-MM-DD.
\- created_at must be ISO 8601.
\- nationality and issuing_state must be ISO-3166 alpha-3, for example USA, ESP, BRA.
\- document_type must use Didit codes: P, ID, DL, RP, SSC, HIC, WP, TC, VISA, PSC, BC, OTHER.
\- reject_reasons_json must be a JSON array. provider_metadata_json must be a JSON object.
\- Use document_front_url, document_back_url, and selfie_url when the provider can export evidence images. Use HTTPS media URLs for large imports. Avoid inline base64 unless the import is small.
\- Use document_front_video_url, document_back_video_url, and liveness_video_url to import capture videos. Videos must be mp4, webm, or mov and at most 10 MB each; otherwise the row is rejected.
\- If only one document side exists, fill document_front_url and leave document_back_url empty.
\- Never call the import API with provider credentials. The customer downloads provider data themselves.
\- The import is idempotent by external_id inside one Didit application, so retries are safe.

Steps:
1\. Inspect the provider export schema.
2\. Map each provider row to the canonical fields.
3\. Write NDJSON for large files; one JSON object per line.
4\. Validate the first 10 rows locally before uploading.
5\. Create an import job:
curl -X POST https://verification.didit.me/v3/session/imports/ \
-H "x-api-key: $DIDIT_API_KEY" \
-F "import_type=user_verification" \
-F "workflow_id=$DIDIT_WORKFLOW_ID" \
-F "file=@didit-import.ndjson"
6\. Poll until status is COMPLETED or FAILED.
7\. If failed_count is greater than 0, fetch /errors/ and produce a corrected file containing only failed rows.

Output:
\- A canonical CSV or NDJSON file ready for Didit.
\- The curl command used to create the import job.
\- The import_id and polling command.
\- A short summary of created, skipped, and failed rows.`

\
Incolla in Prompt per l'importazione della Verifica aziendale (KYB) Copia il prompt negli appunti \

\`You are helping migrate historical Business Verification (KYB) sessions into Didit.

Goal:
Transform the customer's KYB provider export into Didit's canonical business verification import file, then call Didit's import API.

Didit API:
\- Create import job: POST https://verification.didit.me/v3/session/imports/
\- Poll job: GET https://verification.didit.me/v3/session/imports/{import_id}/
\- Read row errors: GET https://verification.didit.me/v3/session/imports/{import_id}/errors/
\- Download template: GET https://verification.didit.me/v3/session/imports/template/?import_type=business_verification
\- Authenticate with x-api-key: 

Inputs you need:
\- DIDIT_API_KEY
\- DIDIT_WORKFLOW_ID for a Business Verification workflow
\- Provider export file or API output

Canonical business columns:
external_id, vendor_data, created_at, status, company_name, registration_number, country_code, registry_status, verification_status, company_type, tax_number, risk_level, incorporation_date, registered_address, is_from_registry, officers_json, beneficial_owners_json, provider_metadata_json, tags

Rules:
\- external_id must be the provider's unique business verification id.
\- vendor_data must be the customer's stable business id.
\- status must be Approved, Declined, In Review, or Expired.
\- country_code must be ISO-3166 alpha-3.
\- officers_json and beneficial_owners_json must be JSON arrays of objects.
\- provider_metadata_json must be a JSON object.
\- The import is idempotent by external_id inside one Didit application.

Create an import job:
curl -X POST https://verification.didit.me/v3/session/imports/ \
-H "x-api-key: $DIDIT_API_KEY" \
-F "import_type=business_verification" \
-F "workflow_id=$DIDIT_WORKFLOW_ID" \
-F "file=@didit-business-import.ndjson"

Output:
\- A canonical CSV or NDJSON file ready for Didit.
\- The curl command used to create the import job.
\- The import_id and polling command.
\- A short summary of created, skipped, and failed rows.`

\
Incolla in Prompt per l'importazione delle regole di stato personalizzate Copia il prompt negli appunti \

\`You are helping import custom status rules into a Didit workflow.

Goal:
Transform the customer's policy spreadsheet into Didit's feature_status_rules format, then call Didit's import API.

Didit API:
\- Create import job: POST https://verification.didit.me/v3/session/imports/
\- Poll job: GET https://verification.didit.me/v3/session/imports/{import_id}/
\- Read row errors: GET https://verification.didit.me/v3/session/imports/{import_id}/errors/
\- Download template: GET https://verification.didit.me/v3/session/imports/template/?import_type=status_rules
\- Authenticate with x-api-key: 

Inputs you need:
\- DIDIT_API_KEY
\- DIDIT_WORKFLOW_ID for the workflow to update
\- A policy spreadsheet or JSON policy definition

Canonical status-rule columns:
feature, rules_json, mode

Rules:
\- feature must be a Didit feature key such as OCR, LIVENESS, FACE_MATCH, AML, KYB_REGISTRY, KYB_DOCUMENTS, or KYB_KEY_PEOPLE.
\- rules_json must be a JSON array of rule objects.
\- Each rule needs field, operator, status, and usually value.
\- mode is replace or append. Default is replace.
\- Do not reference status fields such as kyc.status; status rules compute status and must use other report fields.

Example rules_json:
\[{"field":"kyc.issuing_state","operator":"in","value":["VEN","IRN"],"status":"In Review"}]

Create an import job:
curl -X POST https://verification.didit.me/v3/session/imports/ \
-H "x-api-key: $DIDIT_API_KEY" \
-F "import_type=status_rules" \
-F "workflow_id=$DIDIT_WORKFLOW_ID" \
-F "file=@didit-status-rules.csv"

Output:
\- A canonical CSV or NDJSON file ready for Didit.
\- The curl command used to create the import job.
\- The import_id and polling command.
\- A summary of updated and failed rule rows.`

\
Incolla in Prompt per l'importazione delle transazioni Copia il prompt negli appunti \

\`You are helping migrate historical transaction monitoring records into Didit.

Goal:
Transform the customer's legacy transaction monitoring export into Didit's canonical transaction import file, then call Didit's import API.

Didit API:
\- Create import job: POST https://verification.didit.me/v3/session/imports/
\- Poll job: GET https://verification.didit.me/v3/session/imports/{import_id}/
\- Read row errors: GET https://verification.didit.me/v3/session/imports/{import_id}/errors/
\- Download template: GET https://verification.didit.me/v3/session/imports/template/?import_type=transactions
\- Authenticate with x-api-key: 

Inputs you need:
\- DIDIT_API_KEY
\- A transaction export file or API output

Canonical transaction columns:
transaction_id, transaction_at, transaction_category, direction, amount, currency, currency_kind, amount_in_default_currency, default_currency, payment_details, payment_reference_id, action_type, status, score, severity, subject_json, counterparty_json, custom_properties_json, provider_results_json, travel_rule_json, network_snapshot_json, metadata_json

Rules:
\- transaction_id is required and is idempotent per Didit application.
\- transaction_category must be one of Didit's transaction categories, for example finance, kyc, travelRule, userPlatformEvent, gamblingBet, gamblingLimitChange, gamblingBonusChange, or auditTrailEvent.
\- direction must be INBOUND or OUTBOUND.
\- status must be APPROVED, IN_REVIEW, DECLINED, or AWAITING_USER.
\- subject_json must include vendor_data and full_name.
\- counterparty_json is optional but should be included when the legacy provider has it.
\- provider_results_json must be a JSON array.
\- travel_rule_json, network_snapshot_json, custom_properties_json, and metadata_json must be JSON objects when present.

Create an import job:
curl -X POST https://verification.didit.me/v3/session/imports/ \
-H "x-api-key: $DIDIT_API_KEY" \
-F "import_type=transactions" \
-F "file=@didit-transactions.ndjson"

Output:
\- A canonical CSV or NDJSON file ready for Didit.
\- The curl command used to create the import job.
\- The import_id and polling command.
\- A summary of created, skipped, and failed transaction rows.`

\
Incolla in ## Interrogare lo stato di avanzamento```bash theme={null} curl https://verification.didit.me/v3/session/imports/IMPORT_ID/ \ -H "x-api-key: YOUR_API_KEY" ```La risposta include `status`, `import_type`, `total_rows`, `processed_rows`, `created_count`, `updated_count`, `skipped_count`, `failed_count` e `checkpoint_row`.## Scaricare gli errori di riga```bash theme={null} curl https://verification.didit.me/v3/session/imports/IMPORT_ID/errors/ \ -H "x-api-key: YOUR_API_KEY" ```Ogni errore include `row_number`, `external_id`, `error` e `raw_row`, così puoi correggere solo le righe non riuscite e riprovare.## Protezione dagli abusiLe importazioni storiche tramite `POST /v3/session/imports/` sono disabilitate per impostazione predefinita. Didit abilita questa funzione per ogni organizzazione dopo una revisione, perché questi processi possono elaborare milioni di righe e scaricare media. Le importazioni di dati operativi descritte in questa guida, ovvero la creazione di utenti, la creazione di aziende, il caricamento di volti di profilo, il caricamento di blocklist di volti o l'aggiunta di voci alle liste, non richiedono un'abilitazione speciale per la migrazione, oltre alle normali autorizzazioni della chiave API, alla disponibilità del prodotto e ai limiti di frequenza di questi endpoint.I processi di importazione storici vengono eseguiti su processi di lavoro isolati, con limiti di dimensione dei file, budget di righe, URL dei media solo HTTPS, blocco degli URL verso reti private e un limite di 4 processi di importazione attivi per applicazione. Inoltre, gli errori vengono registrati per ogni riga.## Stati canonici| Esito del provider | Stato in Didit | | - | - | | Approvata / Verde / Verificata | `Approved` | | Rifiutata / Rossa / Respinta | `Declined` | | Revisione manuale / In attesa / Revisione necessaria | `In Review` | | Incompleta / Init / Riga storica sconosciuta | `Expired` |## IdempotenzaDidit usa `external_id` come chiave di idempotenza per le importazioni di Verifica degli utenti e Verifica aziendale (KYB), nell'ambito di ciascuna applicazione. Le importazioni di transazioni usano `transaction_id` nell'ambito di ciascuna applicazione. Ripetere l'importazione dello stesso file salta le righe già importate e crea le righe non ancora elaborate.## Importare utenti, volti di profilo e blocklistUsa questi percorsi quando non stai ricreando una sessione di verifica completata.### Importare i profili utenteCrea gli utenti con [`POST /v3/users/create/`](https://docs.didit.me/it/management-api/users/create) oppure con l'importazione CSV dalla Business Console in [Importare ed esportare utenti](https://docs.didit.me/it/entities/users/import-export.md). Questa operazione crea o aggiorna solo il profilo `VendorUser`. Non crea una sessione di verifica, una decisione KYC, un report sui documenti, un avviso o uno storico di webhook.Usala quando vuoi che Didit sappia che il cliente esiste prima dei controlli futuri, oppure quando devi completare campi simili a quelli di un CRM, come `display_name`, tag o metadati.### Caricare volti di profilo attendibiliDopo che esiste un utente, carica un volto di profilo attendibile con [`POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/`](https://docs.didit.me/it/management-api/users/upload-face). Questo collega la prova biometrica al profilo utente e la indicizza per il rilevamento dei duplicati e per la ricerca facciale.Questa operazione **non** inserisce il volto in blocklist. È utile quando disponi di un'immagine del profilo attendibile proveniente da un precedente provider KYC e vuoi che i futuri controlli di Didit la confrontino.### Importare blocklist e allowlist di voltiPer bloccare o consentire direttamente un volto, usa [`POST /v3/lists/{list_uuid}/entries/face-upload/`](https://docs.didit.me/it/management-api/lists/upload-face) con una lista di tipo facciale. Didit estrae l'embedding biometrico e memorizza una voce della lista.Usalo per immagini di frodatori noti, volti di allowlist attendibili o migrazioni di liste antifrode dai provider. Se il volto proviene da una sessione Didit esistente, preferisci [`POST /v3/lists/{list_uuid}/entries/`](https://docs.didit.me/it/management-api/lists/create-entry) con `reference_session_id`: Didit estrae il volto corretto dalla sessione e collega la voce alla sessione di origine.### Importare liste di utenti, aziende, documenti, wallet, email, telefoni, IP o dispositiviUsa [`POST /v3/lists/{list_uuid}/entries/`](https://docs.didit.me/it/management-api/lists/create-entry) per i valori di lista non relativi ai volti. Questo è il percorso corretto per blocklist, allowlist e liste di chargeback dei provider, indirizzi dei wallet, IP a rischio noti, impronte dei dispositivi, numeri di documento, email, numeri di telefono, utenti o aziende.## Prossimi passi> [card] [Importare utenti](https://docs.didit.me/it/entities/users/import-export.md) > > Carica i profili utente e collega i volti di profilo attendibili.> [card] [Importare aziende](https://docs.didit.me/it/entities/businesses/import-export.md) > > Carica i profili delle aziende prima di eseguire il KYB.> [card] [Caricare un volto di profilo](https://docs.didit.me/it/management-api/users/upload-face.md) > > Collega immagini di volti attendibili agli utenti importati.> [card] [Caricare un volto in lista](https://docs.didit.me/it/management-api/lists/upload-face.md) > > Aggiungi volti a blocklist o allowlist.> [card] [Creare una voce di lista](https://docs.didit.me/it/management-api/lists/create-entry.md) > > Importa numeri di telefono, email, wallet, documenti, IP, dispositivi, utenti o aziende nelle liste.> [card] [Limiti di frequenza](https://docs.didit.me/it/integration/rate-limiting.md) > > Progetta cicli di migrazione sicuri e nuovi tentativi. ## OpenAPI ````yaml it/openapi-25.json POST /v3/session/imports/ 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/session/imports/: post: tags: - Sessions summary: Crea un job di importazione delle verifiche description: >- Crea un job di importazione asincrono per sessioni storiche di Verifica degli utenti, sessioni di Verifica aziendale, record di monitoraggio delle transazioni o regole di stato personalizzate del workflow. Imposta `source=provider` per migrare da un altro provider: Didit legge Sumsub, Onfido, Persona e ComplyCube con la tua chiave di sola lettura, legge i record di Veriff, iDenfy e MetaMap tramite gli ID che carichi in `file`, e importa un file di esportazione nel formato di Didit per gli altri provider. Gli ID dei record sono associati a un namespace per provider (`sumsub:`), quindi una nuova esecuzione ignora tutto ciò che è già presente in Didit; inoltre, un record importato tramite file con l'ID semplice del provider viene riconosciuto in entrambe le direzioni, garantendo che il passaggio tra un'importazione da file e una migrazione da provider non importi mai un record due volte. Un'applicazione può eseguire fino a 4 job di importazione contemporaneamente; un job interrotto da un deploy o dal riavvio di un worker riprende automaticamente dall'ultima riga importata. Le importazioni sono disabilitate per impostazione predefinita e devono essere abilitate per organizzazione da Didit. operationId: post_v3_session_imports_create requestBody: required: true content: multipart/form-data: schema: type: object properties: import_type: type: string enum: - user_verification - business_verification - status_rules - transactions default: user_verification description: >- Cosa importare: sessioni storiche di Verifica degli utenti, sessioni storiche di Verifica aziendale, regole di stato personalizzate del workflow o record storici di monitoraggio delle transazioni. workflow_id: type: string format: uuid description: >- UUID del workflow a cui collegare le sessioni importate o le regole di stato. Obbligatorio per user_verification, business_verification e status_rules. Omettere per transactions. source_format: type: string enum: - csv - ndjson description: >- Opzionale. Se omesso, viene dedotto dall'estensione del file caricato. file: type: string format: binary description: >- File canonico CSV o NDJSON. Usa NDJSON per importazioni di grandi dimensioni. Dimensione massima di caricamento 25 MB (usa `source_file_url` per file più grandi). È mutuamente esclusivo con `source_file_url`. source_file_url: type: string format: uri description: >- Alternativa al caricamento del file. Deve essere un URL HTTPS che punta a un indirizzo pubblico (le reti private/di loopback vengono rifiutate). Si esclude a vicenda con `file`. source: type: string enum: - file - provider description: >- `provider` indica una migrazione da un altro provider di verifica dell'identità. Ometti per un'importazione da file. provider: type: string enum: - sumsub - jumio - veriff - onfido - persona - metamap - socure - idnow - shufti - idenfy - ondato - trulioo - au10tix - complycube - other description: >- Origine della migrazione, da `GET /v3/session/imports/providers/`. Obbligatoria quando `source` è `provider`. credentials: type: object additionalProperties: type: string description: >- La chiave di sola lettura del provider, con i nomi dei campi elencati in `credential_fields`. Crittografata a riposo, mai restituita ed eliminata al termine dell'importazione. Inviala come stringa JSON in multipart. options: type: object properties: region: type: string description: >- La regione del provider, una delle sue `regions` (Onfido: `eu`, `us`, `ca`). status_mapping: type: object additionalProperties: type: string enum: - Approved - Declined - In Review - Expired - Not Finished - Abandoned description: >- Modifiche alla mappatura predefinita degli stati del provider: dallo stato di origine allo stato di Didit. `Not Finished` e `Abandoned` vengono ignorati e conteggiati, mai importati. dry_run: type: boolean default: false description: >- Conta ciò che la migrazione importerebbe (per stato, già in Didit, stessa persona, non completato) senza scrivere nulla. Il job termina nello stato `READY`; avvialo con `POST /v3/session/imports/{importId}/start/`. face_templates: type: boolean default: false description: >- Genera modelli biometrici dai selfie importati ed esegui la ricerca rispetto ai volti e alla blocklist dell'applicazione. Le corrispondenze vengono contrassegnate solo per la revisione. Richiede `lawful_basis_confirmed`. lawful_basis_confirmed: type: boolean default: false description: >- Conferma che disponi di una base giuridica per condividere questi selfie con Didit in qualità di responsabile del trattamento. application/json: schema: type: object required: - source_file_url properties: import_type: type: string enum: - user_verification - business_verification - status_rules - transactions default: user_verification description: >- Cosa importare: sessioni storiche di Verifica degli utenti, sessioni storiche di Verifica aziendale, regole di stato personalizzate del workflow o record storici di monitoraggio delle transazioni. workflow_id: type: string format: uuid description: >- UUID del workflow a cui collegare le sessioni importate o le regole di stato. Obbligatorio per user_verification, business_verification e status_rules. Omettere per transactions. source_format: type: string enum: - csv - ndjson description: >- Opzionale. Se omesso, viene dedotto dall'estensione del file dell'URL. source_file_url: type: string format: uri description: >- Alternativa al caricamento del file. Deve essere un URL HTTPS che punta a un indirizzo pubblico (le reti private/di loopback vengono rifiutate). Si esclude a vicenda con `file`. source: type: string enum: - file - provider description: >- `provider` indica una migrazione da un altro provider di verifica dell'identità. Ometti per un'importazione da file. provider: type: string enum: - sumsub - jumio - veriff - onfido - persona - metamap - socure - idnow - shufti - idenfy - ondato - trulioo - au10tix - complycube - other description: >- Origine della migrazione, da `GET /v3/session/imports/providers/`. Obbligatoria quando `source` è `provider`. credentials: type: object additionalProperties: type: string description: >- La chiave di sola lettura del provider, con i nomi dei campi elencati in `credential_fields`. Crittografata a riposo, mai restituita ed eliminata al termine dell'importazione. Inviala come stringa JSON in multipart. options: type: object properties: region: type: string description: >- La regione del provider, una delle sue `regions` (Onfido: `eu`, `us`, `ca`). status_mapping: type: object additionalProperties: type: string enum: - Approved - Declined - In Review - Expired - Not Finished - Abandoned description: >- Modifiche alla mappatura predefinita degli stati del provider: dallo stato di origine allo stato di Didit. `Not Finished` e `Abandoned` vengono ignorati e conteggiati, mai importati. dry_run: type: boolean default: false description: >- Conta ciò che la migrazione importerebbe (per stato, già in Didit, stessa persona, non completato) senza scrivere nulla. Il job termina nello stato `READY`; avvialo con `POST /v3/session/imports/{importId}/start/`. face_templates: type: boolean default: false description: >- Genera modelli biometrici dai selfie importati ed esegui la ricerca rispetto ai volti e alla blocklist dell'applicazione. Le corrispondenze vengono contrassegnate solo per la revisione. Richiede `lawful_basis_confirmed`. lawful_basis_confirmed: type: boolean default: false description: >- Conferma che disponi di una base giuridica per condividere questi selfie con Didit in qualità di responsabile del trattamento. examples: URL-based import: value: import_type: user_verification workflow_id: 9f9b1234-aaaa-bbbb-cccc-1234567890ab source_file_url: https://files.example.com/exports/sessions.ndjson responses: '201': description: >- Processo di importazione accettato. Effettua il polling dello `uuid` restituito fino a quando lo `status` non è `COMPLETED` o `FAILED`. content: application/json: schema: $ref: '#/components/schemas/SessionImportJob' examples: Job accepted: value: uuid: 3f9c1a2b-4d5e-4f60-8a7b-9c0d1e2f3a4b status: PENDING import_type: user_verification source_format: ndjson source_filename: sessions.ndjson total_rows: 0 processed_rows: 0 checkpoint_row: 0 created_count: 0 updated_count: 0 skipped_count: 0 failed_count: 0 total_media_bytes: 0 last_error: null created_at: '2026-05-17T08:42:11Z' updated_at: '2026-05-17T08:42:11Z' started_at: null completed_at: null '400': description: >- Workflow, tipo di file, dimensione del file, URL di origine o combinazione di selettori non validi. Una migrazione la cui chiave viene rifiutata dal provider restituisce `code` (`invalid_credentials`, `missing_permission`, `wrong_region`, `provider_unavailable`, `rate_limited`, `ids_required`, `record_not_found`), `missing_permissions` e `suggested_region`. content: application/json: examples: Invalid workflow: value: workflow_id: - Invalid workflow_id. Workflow required: value: workflow_id: - This field is required for this import type. Wrong file type: value: file: - Only CSV and NDJSON files are supported. File too large: value: file: - Import file exceeds the maximum allowed size. No source: value: file: - Upload a file or provide source_file_url. Both sources: value: file: - Use either file or source_file_url, not both. '403': description: >- Importazioni non abilitate, applicazione sandbox o chiave API mancante (una chiave errata, revocata o scaduta riceve `401`). Le importazioni di verifiche sono disabilitate per impostazione predefinita e devono essere abilitate da Didit per ogni organizzazione. content: application/json: examples: Imports not enabled: value: detail: >- Verification imports are not enabled for this organization. Sandbox: value: detail: >- Verification imports are not enabled for sandbox applications. Bad API key: value: detail: You do not have permission to perform this action. '429': description: >- L'applicazione ha già 4 job di importazione attivi (PENDING/PROCESSING/PAUSED), il numero massimo eseguibile contemporaneamente. Attendi che uno termini prima di avviarne un altro. content: application/json: examples: Active job: value: detail: >- This application already has 4 active import jobs, the most it can run at once. Wait for one to finish before starting another. security: - ApiKeyAuth: [] x-codeSamples: - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.sessions.imports.create( import_type="user_verification", workflow_id="9f9b1234-aaaa-bbbb-cccc-1234567890ab", source_file_url="https://files.example.com/exports/sessions.ndjson", ) 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.sessions.imports.create({ import_type: "user_verification", workflow_id: "9f9b1234-aaaa-bbbb-cccc-1234567890ab", source_file_url: "https://files.example.com/exports/sessions.ndjson", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Imports.Create(ctx, didit.SessionsImportsCreateParams{\n\tImportType: didit.Some(didit.SessionsImportsCreateParamsImportType(\"user_verification\")),\n\tWorkflowID: didit.String(\"9f9b1234-aaaa-bbbb-cccc-1234567890ab\"),\n\tSourceFileURL: didit.String(\"https://files.example.com/exports/sessions.ndjson\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import me.didit.Didit; import me.didit.types.SessionsImportsCreateParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.sessions().imports().create(SessionsImportsCreateParams.builder() .importType(SessionsImportsCreateParams.ImportType.of("user_verification")) .workflowId("9f9b1234-aaaa-bbbb-cccc-1234567890ab") .sourceFileUrl("https://files.example.com/exports/sessions.ndjson") .build()); System.out.println(result); - lang: php label: PHP source: |- sessions->imports->create([ 'import_type' => 'user_verification', 'workflow_id' => '9f9b1234-aaaa-bbbb-cccc-1234567890ab', 'source_file_url' => 'https://files.example.com/exports/sessions.ndjson', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.sessions.imports.create( import_type: "user_verification", workflow_id: "9f9b1234-aaaa-bbbb-cccc-1234567890ab", source_file_url: "https://files.example.com/exports/sessions.ndjson" ) 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.Sessions.Imports.CreateAsync(new SessionsImportsCreateParams { ImportType = new SessionsImportsCreateParamsImportType("user_verification"), WorkflowId = "9f9b1234-aaaa-bbbb-cccc-1234567890ab", SourceFileUrl = "https://files.example.com/exports/sessions.ndjson", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: SessionImportJob: type: object required: - uuid - status - import_type - source_format - source_filename - total_rows - processed_rows - created_count - updated_count - skipped_count - failed_count properties: uuid: type: string format: uuid description: >- ID del processo di importazione. Usa questo valore per verificare lo stato di avanzamento e recuperare gli errori delle righe. status: type: string enum: - PENDING - PROCESSING - COMPLETED - FAILED - PAUSED - CANCELLED - READY import_type: type: string enum: - user_verification - business_verification - status_rules - transactions source_format: type: string enum: - csv - ndjson source_filename: type: string total_rows: type: integer format: int64 processed_rows: type: integer format: int64 checkpoint_row: type: integer format: int64 created_count: type: integer format: int64 updated_count: type: integer format: int64 skipped_count: type: integer format: int64 failed_count: type: integer format: int64 total_media_bytes: type: integer format: int64 last_error: type: string nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time started_at: type: string format: date-time nullable: true completed_at: type: string format: date-time nullable: true state: type: string enum: - ready - queued - running - paused - completed - errors - failed - cancelled description: >- Lo stato del job così come mostrato nella console; `errors` corrisponde a un job completato con righe rifiutate. source: type: string enum: - file - api - provider provider: type: string description: Origine della migrazione; vuota per un'importazione da file o API. provider_options: type: object credential_hint: type: string description: >- I primi caratteri della chiave contenuta nella migrazione. La chiave stessa non viene mai restituita. credentials_expires_at: type: string format: date-time nullable: true resumes_at: type: string format: date-time nullable: true description: >- Quando un processo sospeso a causa del limite di frequenza del provider riprende automaticamente. status_mapping: type: object additionalProperties: type: string is_dry_run: type: boolean dry_run_summary: type: object description: >- Risultati di una simulazione (dry run): `total`, `by_status`, `already_in_didit`, `same_person`, `not_finished`, `failed`, `unmapped_statuses`. face_templates_enabled: type: boolean lawful_basis_confirmed_at: type: string format: date-time nullable: true not_finished_count: type: integer format: int64 same_person_count: type: integer format: int64 face_templates_count: type: integer format: int64 face_duplicates_count: type: integer format: int64 face_blocklist_hits_count: type: integer format: int64 created_by_name: type: string nullable: true created_by_email: type: string nullable: true 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.