> ## 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.

# Gestione utenti via API: operazioni CRUD

> Crea, leggi, aggiorna, cambia stato ed elimina le entità utente vendor di Didit tramite la Management API. Prezzi a consumo, senza contratti.



Prompt per le operazioni sugli utenti
        Copia il prompt negli appunti



      
      

\<pre>

\````# Goal — full CRUD over Didit User entities

Core CRUD operations sit under `https://verification.didit.me/v3/users/` authenticated with `x-api-key: $DIDIT_API_KEY`. Profile attachment endpoints use the organization/application path and the User's `didit_internal_id`. Each User is keyed by `vendor_data` (case-sensitive, unique per application).

\## Endpoint catalog

\| Action | Method + path |
\|---|---|
\| List users | `GET /v3/users/` |
\| Get one user | `GET /v3/users/{vendor_data}/` |
\| Create user | `POST /v3/users/create/` |
\| Upload profile face | `POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/` |
\| Update profile | `PATCH /v3/users/{vendor_data}/` |
\| Change status | `PATCH /v3/users/{vendor_data}/update-status/` |
\| Batch delete | `POST /v3/users/delete/` |

\## List (with filters)

\```bash
curl -G https://verification.didit.me/v3/users/ \
-H "x-api-key: $DIDIT_API_KEY" \
\--data-urlencode "status=ACTIVE" \
\--data-urlencode "search=jane" \
\--data-urlencode "page_size=50"
\```

\## Get one user

\```bash
curl https://verification.didit.me/v3/users/user-42/ \
-H "x-api-key: $DIDIT_API_KEY"
\```

\## Create

\```bash
curl -X POST https://verification.didit.me/v3/users/create/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"vendor_data": "user-42",
"display_name": "Jane Doe",
"metadata": {"tier": "premium", "signup_source": "web"}
}'
\```

Not idempotent — retrying with the same `vendor_data` returns conflict. `GET` first or PATCH instead.

\## Upload an imported profile face

\```bash
\# First read didit_internal_id from GET /v3/users/{vendor_data}/
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 attaches a trusted face image to the User profile and enrolls it for duplicate detection and face search. It does not add the face to a blocklist.

\## Update profile

\```bash
curl -X PATCH https://verification.didit.me/v3/users/user-42/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"metadata": {"tier": "enterprise"}}'
\```

Mutable: `display_name`, `metadata`, `tags`. Read-only (verified): `full_name`, `date_of_birth`, `portrait_image`, all aggregate counters, `features` map.

\## Change status

\```bash
curl -X PATCH https://verification.didit.me/v3/users/user-42/update-status/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"status": "BLOCKED", "reason": "Chargeback fraud pattern"}'
\```

Valid statuses: `ACTIVE`, `FLAGGED`, `BLOCKED`. `BLOCKED` users have new sessions auto-declined.

\## Batch delete

\```bash
curl -X POST https://verification.didit.me/v3/users/delete/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"vendor_data_list": ["user-42", "user-43", "user-44"]}'
\```

Idempotent — already-deleted is a no-op. Returns a count, `{"deleted": <int>}`, not a per-item result. The user records and every biometric template retained for them are removed permanently. Verification sessions are not covered by this endpoint; delete those with the session delete endpoints.

\## Webhooks fired

\| Operation | Event |
\|---|---|
\| create | none for the create call itself — the first `user.data.updated` arrives when a session or a PATCH first fills the profile |
\| update (PATCH) | `user.data.updated` with `changed_fields` |
\| update-status | `user.status.updated` |
\| delete | none — record the deletion on your own side if you need to react to it |

\## Failure modes

\- `401` — missing / invalid `x-api-key`.
\- `403` — the API key is not valid for this application.
\- `409` on create — `vendor_data` already exists; switch to PATCH.
\- `404` — no entity for that `vendor_data` (case-sensitive!).
\- `429` — rate-limited; back off using `Retry-After`.

\## Response shape

See /reference/data-models and /entities/users/data-model for the full User schema.

\## Sources of truth

\- /management-api/users/list, /management-api/users/get, /management-api/users/create — per-endpoint reference
\- /entities/users/data-model — field-by-field schema
\- /entities/webhooks — entity event payloads
\- /integration/integration-prompt — canonical end-to-end prompt````

\</pre>



      
      

Incolla in

La gestione dell'entità utente principale avviene tramite endpoint pubblici sotto `/v3/users/`. Gli allegati del profilo, come il caricamento di un volto importato, usano il percorso dell'organizzazione/applicazione con `didit_internal_id`. Questa pagina offre una panoramica concettuale: consulta il [riferimento API](https://docs.didit.me/it/management-api/users/list.md) per gli schemi completi di richiesta e risposta.## Elenca gli utenti**`GET /v3/users/`**Restituisce un elenco paginato degli utenti della tua applicazione. Supporta filtri per stato, ricerca, intervallo di date e altro.```bash theme={null}
curl -G https://verification.didit.me/v3/users/ \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "status=ACTIVE" \
  --data-urlencode "search=jane" \
  --data-urlencode "page_size=50"
```Casi d'uso:- Sincronizzare ogni giorno un sottoinsieme di utenti con il tuo data warehouse.
- Trovare gli utenti segnalati per la coda di un analista.
- Cercare gli utenti per nome visualizzato.## Recupera un utente**`GET /v3/users/{vendor_data}/`**Recupera un singolo utente tramite `vendor_data`. Restituisce il [modello dati](https://docs.didit.me/it/entities/users/data-model.md) completo, inclusi i contatori aggregati.```bash theme={null}
curl https://verification.didit.me/v3/users/user-42/ \
  -H "x-api-key: YOUR_API_KEY"
```> [!NOTE]
>
> `vendor_data` nell'URL distingue tra maiuscole e minuscole. Passa sempre il valore esatto che hai usato alla creazione della sessione.## Crea un utente**`POST /v3/users/create/`**Crea un'entità utente prima che venga avviata qualsiasi sessione. Utile per:- Inserire metadati o campi personalizzati prima che il cliente effettui la verifica.
- Impostare uno stato iniziale (ad esempio `FLAGGED` mentre il team di onboarding esamina manualmente i documenti).
- Precaricare gli utenti da un database esistente per avere un elenco completo fin dal primo giorno.```bash theme={null}
curl -X POST https://verification.didit.me/v3/users/create/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data": "user-42",
    "display_name": "Jane Doe",
    "metadata": { "tier": "premium", "signup_source": "web" }
  }'
```Se esiste già un utente con quel `vendor_data`, la chiamata restituisce un errore di conflitto: usa `PATCH` per aggiornarlo.Puoi anche inviare i dati di contatto: `first_name` e `last_name` (uniti in `full_name` quando non ne invii uno), `email`, `phone_number` e `country`.
Didit memorizza `email` e `phone_number` in `metadata.contact`, e `country` in `metadata.address`.Per invitare la persona a effettuare la verifica nella stessa chiamata, aggiungi `send_verification_link: true` con un indirizzo `email` e un `workflow_id`.
Didit crea per la persona una sessione di verifica nel workflow indicato e le invia il link via email.
L'oggetto `verification_link` della risposta contiene `session_id`, `session_number`, `status`, `url`, `workflow_id` e `email` della sessione, ed è `null` quando non richiedi un link.
Consulta [Crea un utente](https://docs.didit.me/it/management-api/users/create.md#invia-un-link-di-verifica) per i controlli e gli errori.## Carica un volto importato**`POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/`**Allega un'immagine del volto attendibile a un profilo utente esistente. Questo è il passo successivo giusto quando importi utenti da un altro provider e vuoi che Didit conservi le prove del loro volto prima della prima sessione Didit.```bash theme={null}
# First create or retrieve the User and read didit_internal_id from the response.
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"
  }'
```Consulta [Carica il volto di un utente](https://docs.didit.me/it/management-api/users/upload-face.md) per i campi della richiesta, i limiti, gli endpoint di elenco ed eliminazione e la distinzione rispetto alla blocklist.## Aggiorna un utente**`PATCH /v3/users/{vendor_data}/`**Aggiorna i campi del profilo modificabili. La maggior parte dei campi derivati dalle sessioni verificate è di sola lettura: se tenti di modificarli tramite PATCH, verranno ignorati o segnalati nel registro di audit.**Campi modificabili:** `display_name`, `metadata`, `tags`.
**Di sola lettura dopo la verifica:** `full_name`, `date_of_birth`, `portrait_image`, tutti i contatori aggregati, la mappa `features`.```bash theme={null}
curl -X PATCH https://verification.didit.me/v3/users/user-42/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "tier": "enterprise" } }'
```Invia un webhook `user.data.updated` con l'array `changed_fields`.## Cambia stato**`PATCH /v3/users/{vendor_data}/update-status/`**Sposta un utente tra `ACTIVE`, `FLAGGED` e `BLOCKED`. Le modifiche di stato si applicano alle sessioni e alle transazioni future.```bash theme={null}
curl -X PATCH https://verification.didit.me/v3/users/user-42/update-status/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "BLOCKED",
    "reason": "Chargeback fraud pattern detected"
  }'
```| Da → a | Trigger comune |
| - | - |
| `ACTIVE` → `FLAGGED` | Regola sulle transazioni, revisione dell'analista, riscontro del monitoraggio AML continuo |
| `ACTIVE` → `BLOCKED` | Frode confermata, inserimento manuale in blocklist, corrispondenza con la blocklist |
| `FLAGGED` → `ACTIVE` | Revisione chiusa dall'analista |
| `BLOCKED` → `ACTIVE` | Sblocco manuale da parte di un analista |Invia un webhook `user.status.updated`.## Elimina utenti (in batch)**`POST /v3/users/delete/`**Elimina uno o più utenti. I record degli utenti vengono rimossi in modo permanente, insieme a ogni [modello biometrico](https://docs.didit.me/it/management-api/biometric-templates/overview.md) conservato per loro dopo l'eliminazione della sessione. Le loro sessioni di verifica non sono coperte da questo endpoint e restano, con il collegamento all'utente rimosso; eliminale con [Elimina sessione](https://docs.didit.me/it/sessions-api/delete-session.md) o [Elimina sessioni in batch](https://docs.didit.me/it/management-api/sessions/batch-delete.md). Anche le transazioni non sono coperte: eliminale dalla Console.```bash theme={null}
curl -X POST https://verification.didit.me/v3/users/delete/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data_list": ["user-42", "user-43", "user-44"]
  }'
```Seleziona gli utenti tramite `vendor_data_list`, tramite `didit_internal_id_list`, o tramite entrambi insieme; oppure passa `delete_all: true` per rimuovere tutti gli utenti dell'applicazione. I parametri batch `filter_*` della Console vengono rifiutati qui con un `400` anziché ignorati, così un intento ristretto non potrà mai trasformarsi in una cancellazione totale.Restituisce un conteggio, `{"deleted": <int>}`, non un risultato per ciascun elemento. Gli identificativi che non corrispondono a nulla vengono ignorati senza segnalazione, quindi, se vuoi confrontare `deleted` con il numero di identificativi inviati, invia un elenco senza duplicati.## Modello dei permessiLe chiavi API appartengono a una sola applicazione.
La chiave segreta principale e le chiavi con accesso completo possono chiamare ogni endpoint `/v3/users/*` di quell'applicazione, incluso `delete`.Una [chiave API con ambito limitato](https://docs.didit.me/it/console/api-keys.md) richiede l'accesso **Persone** (`users`): lettura per gli endpoint `GET`, e scrittura per creare, aggiornare, cambiare stato ed eliminare.
Creare un utente con `send_verification_link: true` richiede anche la scrittura su **Sessioni**, perché crea una sessione e ne invia il link via email.
Una chiave senza l'accesso necessario risponde con `403`.
Una chiave limitata ad alcuni workflow o alle sessioni approvate non può raggiungere affatto gli endpoint `/v3/users/*`.I ruoli sono un concetto della Console: la risorsa di autorizzazione `users` e i relativi claim determinano cosa può fare un membro del team nella Console, e non vengono valutati per le richieste con chiave API.
Consulta [Ruoli e autorizzazioni](https://docs.didit.me/it/console/roles-permissions.md) per la relativa matrice.Per impedire a un servizio di eliminare utenti, assegnagli una chiave con accesso in sola lettura a **Persone**, oppure nessun accesso a **Persone**.## Limiti di frequenza e idempotenza- Tutti gli endpoint `/v3/users/*` sono soggetti ai [limiti di frequenza](https://docs.didit.me/it/integration/rate-limiting.md) standard.
- `create` **non** è idempotente: ripetere la chiamata con lo stesso `vendor_data` restituisce un conflitto. Gestisci i duplicati lato tuo, oppure esegui sempre prima una `GET`.
- `delete` è idempotente: eliminare un utente già eliminato non ha effetto.## Webhook attivati da queste operazioni| Operazione | Webhook |
| - | - |
| `create` | nessuno per la chiamata create stessa: il primo `user.data.updated` arriva quando una sessione o un aggiornamento riempie per la prima volta il profilo |
| `update` | `user.data.updated` (con `changed_fields`) |
| `update-status` | `user.status.updated` |
| `delete` | nessuno: registra l'eliminazione nel tuo sistema se devi reagire |## Prossimi passi> [card] [Modello dati](https://docs.didit.me/it/entities/users/data-model.md)
>
> Riferimento completo dei campi.> [card] [API di elenco](https://docs.didit.me/it/management-api/users/list.md)
>
> Schema di GET /v3/users/.> [card] [API di creazione](https://docs.didit.me/it/management-api/users/create.md)
>
> Schema di POST /v3/users/create/.> [card] [Caricamento del volto](https://docs.didit.me/it/management-api/users/upload-face.md)
>
> Allega le immagini dei volti importati ai profili utente.


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