Gestione utenti via API: operazioni CRUD

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

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 completo, inclusi i contatori aggregati.

curl https://verification.didit.me/v3/users/user-42/ \
  -H "x-api-key: YOUR_API_KEY"

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.

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

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

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.

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 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 o Elimina sessioni in batch. Anche le transazioni non sono coperte: eliminale dalla Console.

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 permessi

Le 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 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 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 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

Modello dati

Riferimento completo dei campi.

API di elenco

Schema di GET /v3/users/.

API di creazione

Schema di POST /v3/users/create/.

Caricamento del volto

Allega le immagini dei volti importati ai profili utente.

Panoramica

Prezzi

Workflow e verifica

Revisione e operazioni

Entità (utenti e aziende)

Impostazioni e personalizzazione

Sicurezza e compliance

Didit Academy

Risorse

Gestione utenti via API: operazioni CRUD

Elenca gli utenti

Recupera un utente

Crea un utente

Carica un volto importato

Aggiorna un utente

Cambia stato

Elimina utenti (in batch)

Modello dei permessi

Limiti di frequenza e idempotenza

Webhook attivati da queste operazioni

Prossimi passi

Modello dati

API di elenco

API di creazione

Caricamento del volto

​Elenca gli utenti

​Recupera un utente

​Crea un utente

​Carica un volto importato

​Aggiorna un utente

​Cambia stato

​Elimina utenti (in batch)

​Modello dei permessi

​Limiti di frequenza e idempotenza

​Webhook attivati da queste operazioni

​Prossimi passi

Modello dati

API di elenco

API di creazione

Caricamento del volto

Elenca gli utenti

Recupera un utente

Crea un utente

Carica un volto importato

Aggiorna un utente

Cambia stato

Elimina utenti (in batch)

Modello dei permessi

Limiti di frequenza e idempotenza

Webhook attivati da queste operazioni

Prossimi passi