> ## 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 ed esportare utenti: operazioni CSV in blocco

> Importa in blocco da CSV le entità utente del vendor Didit ed esporta la tabella utenti completa. Disponibile dalla Business Console.



Prompt per importazione ed esportazione massiva degli utenti
        Copia il prompt negli appunti



      
      

\<pre>

\````# Goal — bulk-load (or extract) Didit User entities programmatically

CSV import / export is a console-only UI feature. For programmatic bulk operations, loop `POST /v3/users/create/` for imports, optionally upload trusted profile faces with `POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/`, and paginate `GET /v3/users/` for exports. There is no public CSV API endpoint.

\## Bulk import — loop the create endpoint

\```bash
\# users.json — array of records you want to seed into Didit
\# [{"vendor_data":"user-1","display_name":"Alice"}, ...]

jq -c '.[]' users.json | while read user; do
curl -X POST https://verification.didit.me/v3/users/create/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d "$user"
sleep 0.1   # respect rate limits — see /integration/rate-limiting
done
\```

Record shape (matches `POST /v3/users/create/`):

\```json
\{
"vendor_data": "user-42",          // required, unique per app
"display_name": "Jane Doe",        // optional
"metadata": {"tier": "premium"},   // free-form JSON
"tags": ["promo-2026"]             // optional array of strings
}
\```

\`create` is **not** idempotent — a duplicate `vendor_data` returns conflict. Branch on existence:

\```bash
\# Idempotent upsert pattern
if curl -s -o /dev/null -w "%{http_code}" \
 https://verification.didit.me/v3/users/$VD/ \
 -H "x-api-key: $DIDIT_API_KEY" | grep -q 200; then
curl -X PATCH https://verification.didit.me/v3/users/$VD/ \
-H "x-api-key: $DIDIT_API_KEY" -H "Content-Type: application/json" \
-d "$BODY"
else
curl -X POST https://verification.didit.me/v3/users/create/ \
-H "x-api-key: $DIDIT_API_KEY" -H "Content-Type: application/json" \
-d "$BODY"
fi
\```

\## Import faces from another provider

If each imported user has a trusted face image, upload it after the User exists:

\```bash
\# GET /v3/users/{vendor_data}/ or POST /v3/users/create/ first.
\# Use the returned didit_internal_id for the profile attachment endpoint.
curl -X POST https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/$DIDIT_INTERNAL_ID/faces/upload/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"image": "<base64-encoded-jpg-or-png>", "comment": "Imported from previous KYC provider"}'
\```

This stores the face on the User profile and enrolls it for duplicate detection and face search. It does not blocklist the face; use /management-api/lists/upload-face for blocklists.

\## Bulk export — paginate the list endpoint

\```bash
PAGE=1
while :; do
RESP=$(curl -sG https://verification.didit.me/v3/users/ \
-H "x-api-key: $DIDIT_API_KEY" \
\--data-urlencode "page=$PAGE" \
\--data-urlencode "page_size=100")
echo "$RESP" | jq -c '.results[]' >> users.ndjson
HAS_NEXT=$(echo "$RESP" | jq -r '.next // empty')
\[ -z "$HAS_NEXT" ] && break
PAGE=$((PAGE+1))
done
\```

Filter with the same query params as `GET /v3/users/` (`status`, `search`, date ranges, etc).

\## What survives on update vs what stays

\| Field | Behaviour |
\|---|---|
\| `display_name`, `metadata`, `tags` | Overwritten by PATCH |
\| `full_name`, `date_of_birth`, `portrait_image` | Read-only after a verified session (you can override via PATCH but it's logged as a manual override) |
\| Aggregate counters (`session_count`, `approved_count`, etc.) | Computed by Didit — never accept writes |
\| `features` map | Computed — never accept writes |

\## Failure modes

\- `409` on create — `vendor_data` exists; switch to PATCH.
\- `429` — rate limit; back off using `Retry-After`. Don't slam the API; insert 100ms+ between calls.
\- `400` — bad JSON or invalid country/status enum. Log the row and continue.
\- Partial failures: track `vendor_data` → status per row and retry only failures.

\## Console fallback

For one-off migrations bigger than 100K rows, the Business Console CSV import/export (Users → Import / Export) is fast and skips writing your own loop. The console runs the same validations and produces an error report.

\## Sources of truth

\- /management-api/users/create — POST /v3/users/create/ schema
\- /management-api/users/list — GET /v3/users/ pagination + filters
\- /entities/users/data-model — mutable vs read-only fields
\- /integration/rate-limiting — rate limits and Retry-After
\- /integration/integration-prompt — canonical end-to-end prompt````

\</pre>



      
      

Incolla in

La Business Console consente al tuo team di gestire in blocco le entità User senza scrivere codice. Sono supportati due flussi: **importazione CSV** (creare o aggiornare utenti su larga scala) ed **esportazione CSV** (estrarre la tabella degli utenti per strumenti esterni).> [!NOTE]
>
> L'importazione e l'esportazione in blocco creano o aggiornano solo i profili User. Non ricreano le sessioni KYC storiche, gli avvisi sui documenti, le prove di vitalità né le decisioni dei provider. Per una migrazione completa da Sumsub, MetaMap, Veriff, Onfido, Persona o da un altro provider, consulta [Importare dati da un altro provider](https://docs.didit.me/it/sessions-api/import-verifications.md).## Importare utenti da CSV### Quando usarlo- **Migrazione iniziale** da un altro fornitore KYC: porta con te l'elenco degli utenti esistenti.
- **Migrazione dei volti dal provider**: allega le immagini dei volti attendibili ai profili User importati dopo la creazione delle righe.
- **Onboarding in blocco** della lista clienti di un partner.
- **Aggiornamento retroattivo dei metadati**: aggiorna tag, livello o identificativi interni di molti utenti contemporaneamente.### Colonne del modelloScarica il modello da *Users → Import → Download template*. Colonne:| Colonna | Obbligatorio | Descrizione |
| - | - | - |
| `vendor_data` | Sì | Il tuo identificativo dell'utente. Deve essere univoco per applicazione. |
| `display_name` | No | Nome leggibile mostrato nella console. |
| `full_name` | No | Nome legale. Verrà sovrascritto dai dati della sessione verificata. |
| `email` | No | Indirizzo email di contatto noto. |
| `phone` | No | Numero di telefono di contatto noto (formato E.164). |
| `country` | No | Codice paese ISO 3166-1 alpha-3. |
| `status` | No | `ACTIVE`, `FLAGGED` oppure `BLOCKED`. Il valore predefinito è `ACTIVE`. |
| `tags` | No | Tag separati da virgole. |
| `metadata_json` | No | JSON serializzato come stringa per i metadati personalizzati. |### Esecuzione dell'importazione**1. Carica il CSV**Vai a *Users → Import → Upload CSV* e seleziona il file.**2. Controlla l'anteprima**La console convalida ogni riga. Le righe non valide sono evidenziate con il motivo dell'errore (ad esempio `vendor_data` duplicato o codice paese non valido).**3. Avvia l'importazione**Didit elabora le righe in modo asincrono. Puoi chiudere la scheda: l'avanzamento è visibile in *Users → Import history*.**4. Controlla i risultati**Al termine dell'importazione, la cronologia mostra il numero di righe create, aggiornate e saltate, insieme a un report degli errori scaricabile.### Aggiornamento o creazione- Se un `vendor_data` non esiste, viene creato un nuovo User.
- Se un `vendor_data` esiste già, la riga aggiorna lo User esistente (campi del profilo e metadati).
- I contatori aggregati e i campi verificati (`full_name`, `date_of_birth` dalle sessioni approvate) **non vengono mai sovrascritti** dalle importazioni.### Importare i volti dopo la creazione dell'utenteL'importazione CSV crea o aggiorna la riga User, ma non include immagini dei volti nel CSV. Per trasferire i dati biometrici dei volti da un altro provider, carica ogni volto dopo che lo User di destinazione esiste:**1. Crea o importa lo User**Usa l'importazione CSV nella console oppure chiama [`POST /v3/users/create/`](https://docs.didit.me/it/management-api/users/create) in un ciclo.**2. Leggi didit\_internal\_id**Recupera l'User con [`GET /v3/users/{vendor_data}/`](https://docs.didit.me/it/management-api/users/get). La risposta include `didit_internal_id`.**3. Carica il volto**Chiama [`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) con un'immagine del volto in base64 non elaborata.```bash theme={null}
curl -X POST https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/$DIDIT_INTERNAL_ID/faces/upload/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "<base64-encoded-jpg-or-png>",
    "comment": "Imported from previous KYC provider"
  }'
```Il volto deve essere un'immagine valida, di massimo 2 MB una volta decodificata, e deve contenere un volto rilevabile. Didit lo salva nel profilo e lo indicizza per il rilevamento dei duplicati e per la ricerca facciale. Non viene aggiunto a una blocklist di volti, a meno che tu non utilizzi separatamente l'endpoint [Upload face to list](https://docs.didit.me/it/management-api/lists/upload-face.md).## Esportare utenti in CSV### Quando usarlo- **Audit di conformità**: consegna la tabella completa degli utenti ai revisori.
- **Sincronizzazione con il data warehouse**: esportazione periodica verso i tuoi strumenti di business intelligence.
- **Richieste SAR o delle autorità di vigilanza**: estrai sottoinsiemi filtrati di utenti.### Esecuzione di un'esportazione1. Vai a *Users → Export*.
2. Applica i filtri (stato, paese, intervallo di date, ricerca).
3. Scegli le colonne (per impostazione predefinita sono tutti i campi; puoi eliminare le colonne che non ti servono).
4. Invia. Didit genera l'esportazione in modo asincrono e invia via email un link di download firmato all'operatore che l'ha richiesta.> [!NOTE]
>
> Le esportazioni includono solo i dati che il tuo ruolo è autorizzato a leggere. COMPLIANCE\_OFFICER e i ruoli superiori possono esportare l'intera tabella; i ruoli DEVELOPER e READER hanno esportazioni limitate.## Caratteristiche di prestazione| Operazione | Scala tipica | Note |
| - | - | - |
| Importazione | Fino a 100,000 righe | I file più grandi vengono suddivisi in blocchi lato server; l'avanzamento è verificato periodicamente dall'interfaccia |
| Esportazione | Fino a 1,000,000 di righe | Le esportazioni più grandi vengono trasmesse su S3 e consegnate tramite URL firmato |## Traccia di auditOgni importazione ed esportazione viene registrata nel [registro di audit](https://docs.didit.me/it/console/audit-logs.md):- L'operatore che l'ha avviata.
- Numero di righe (importazioni) / istantanea dei filtri (esportazioni).
- Marcature temporali e stato di riuscita o di errore.## Passi successivi> [card] [API per creare utenti](https://docs.didit.me/it/management-api/users/create.md)
>
> Creazione programmatica per importazioni automatizzate.> [card] [Caricare il volto dell'utente](https://docs.didit.me/it/management-api/users/upload-face.md)
>
> Allega le immagini dei volti importate ai profili User.> [card] [Conservazione dei dati](https://docs.didit.me/it/console/data-retention.md)
>
> Per quanto tempo persistono i dati importati.> [card] [Registri di audit](https://docs.didit.me/it/console/audit-logs.md)
>
> Consulta la cronologia di importazioni ed esportazioni.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.