Vai al contenuto principale
POST
Python
L’API Look Up Users di Didit associa un elenco di massimo 20.000 identificativi agli utenti della tua applicazione con una sola chiamata, e indica quali identificativi non corrispondono a nessun utente. Usala quando hai un elenco di account, ad esempio i beneficiari di un lotto di pagamenti in uscita, gli account di un partner o il risultato di una query antifrode, e ti serve lo stato di verifica di ciascuno.

Come funziona

  1. Cerca l’elenco. POST /v3/users/lookup/ con i tuoi identificatori. La chiamata si limita a leggere e restituisce un lookup_id, i conteggi e gli identificatori che non corrispondono a nessun utente.
  2. Leggi gli utenti. Passa il lookup_id come lookup a Elenca gli utenti. Restituisce solo gli utenti trovati, nell’ordine in cui hai inviato gli identificatori.

Regole di corrispondenza

Ogni identificativo viene confrontato all’interno della tua applicazione, in quest’ordine:
  • Le voci vuote vengono scartate, e i duplicati vengono rimossi mantenendo la prima occorrenza.
  • Una richiesta può contenere al massimo 100.000 voci. Dopo la rimozione delle voci vuote e dei duplicati, devono restare da 1 a 20.000 identificativi. Il superamento di uno dei due limiti restituisce 400 con code: too_many_identifiers.
  • La ricerca interessa solo la tua applicazione.

Richiesta

Risposta

Lettura degli utenti corrispondenti

  • Gli utenti vengono restituiti nell’ordine dell’identificativo nella tua lista, paginati con limit e offset. Quando una stessa email corrisponde a più utenti, sono elencati a partire dall’account più vecchio.
  • Il risultato viene conservato per 24 ore, solo per la tua applicazione. Trascorso questo periodo, lookup restituisce 404 con code: lookup_not_found: invia di nuovo la lista.

Recuperare un lookup

GET /v3/users/lookup/{lookup_id}/ restituisce lo stesso corpo del lookup, con in più identifiers: l’elenco che hai inviato, dopo la rimozione dei valori vuoti e dei duplicati, nell’ordine originale. Risponde con 404 e code: lookup_not_found quando il lookup è scaduto, non esiste o appartiene a un’altra applicazione.

Errori

Autorizzazioni

La chiave API deve avere l’accesso read agli utenti, e l’endpoint non modifica mai i dati. Una chiave senza questo accesso, o una chiave revocata, riceve 403. Gli ambiti delle chiavi si impostano per ogni chiave in chiavi API; i ruoli e le autorizzazioni della Console stabiliscono cosa può fare una persona nella Console e non vengono valutati per il traffico API. Nella Console, Cerca un elenco richiede solo l’autorizzazione per leggere gli utenti.

Correlati

Autorizzazioni

x-api-key
string
header
obbligatorio

Your application's API key, from Developers -> API keys in the Business Console. The primary key has full access. A named key can be scoped: none, read or write per resource, limited to some workflows or to approved sessions, to a list of IP addresses, and to an expiry date. 401 means the key is wrong, revoked or expired; 403 means no key was sent, the key has no access to this resource or action, or the request came from an address outside its IP list; 404 on a session route means the session is outside the key's workflows or statuses. A key without media access receives image, video and PDF URLs as null, and a key without sessions write receives session links and tokens as null. See https://docs.didit.me/console/api-keys.

Corpo

application/json
identifiers
string[]
obbligatorio

Each entry is a vendor_data value, a Didit user ID or a verified email. Send at most 100,000 entries. Blank entries are dropped and duplicates removed, keeping the first, and at most 20,000 identifiers must remain. Either limit exceeded is a 400 with code: too_many_identifiers, and an empty list is a 400 too.

Maximum array length: 100000
Esempio:

Risposta

The lookup was read. Use lookup_id with List users.

lookup_id
string<uuid>
obbligatorio

Pass it as lookup to List users.

requested
integer
obbligatorio

Identifiers read, after blanks and duplicates were removed.

found
integer
obbligatorio

Identifiers that matched at least one user.

not_found
object[]
obbligatorio
expires_at
string<date-time>
obbligatorio

When the result expires (24 hours after the lookup).

Ultima modifica il 20 novembre 2026