Saltar al contenido principal
POST
Python
La API de búsqueda de usuarios de Didit asocia una lista de hasta 20,000 identificadores con los usuarios de tu aplicación en una sola llamada, e indica qué identificadores no coincidieron con ningún usuario. Úsala cuando tengas una lista de cuentas, como los beneficiarios de un lote de pagos, las cuentas de un socio o el resultado de una consulta de fraude, y necesites el estado de verificación de cada una.

Cómo funciona

  1. Consulta la lista. POST /v3/users/lookup/ con tus identificadores. La llamada solo lee y responde con un lookup_id, los recuentos y los identificadores que no coincidieron con ningún usuario.
  2. Lee los usuarios. Pasa el lookup_id como lookup a Listar usuarios. Devuelve solo los usuarios coincidentes, en el orden en que enviaste los identificadores.

Reglas de coincidencia

Cada identificador se compara dentro de tu aplicación, en este orden:
  • Las entradas vacías se descartan, y los duplicados se eliminan conservando el primero.
  • Una solicitud envía como máximo 100,000 entradas. Después de eliminar las vacías y los duplicados, deben quedar entre 1 y 20,000 identificadores. Si se supera cualquiera de los dos límites, se devuelve 400 con code: too_many_identifiers.
  • La búsqueda solo abarca tu aplicación.

Solicitud

Respuesta

Leer los usuarios coincidentes

  • Los usuarios se devuelven en el orden de su identificador en tu lista, paginados con limit y offset. Cuando un correo electrónico coincide con varios usuarios, se listan primero las cuentas más antiguas.
  • El resultado se conserva durante 24 horas, solo para tu aplicación. Después, lookup devuelve 404 con code: lookup_not_found: vuelve a enviar la lista.

Recuperar una búsqueda

GET /v3/users/lookup/{lookup_id}/ devuelve el mismo cuerpo que la búsqueda, además de identifiers: la lista que enviaste después de eliminar los valores vacíos y los duplicados, en el mismo orden. Responde con 404 y code: lookup_not_found cuando la búsqueda ha expirado, no existe o pertenece a otra aplicación.

Errores

Permisos

La clave de API necesita acceso de lectura a los usuarios, y el endpoint nunca modifica datos. Una clave sin ese acceso, o una clave revocada, recibe 403. Los ámbitos de acceso se establecen para cada clave en Claves de API; los roles y permisos de la Console determinan lo que una persona puede hacer en la Console y no se evalúan para el tráfico de la API. En la Console, Consultar una lista solo necesita el permiso para leer usuarios.

Relacionados

Autorizaciones

x-api-key
string
header
requerido

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.

Cuerpo

application/json
identifiers
string[]
requerido

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
Ejemplo:

Respuesta

The lookup was read. Use lookup_id with List users.

lookup_id
string<uuid>
requerido

Pass it as lookup to List users.

requested
integer
requerido

Identifiers read, after blanks and duplicates were removed.

found
integer
requerido

Identifiers that matched at least one user.

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

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

Última modificación el 20 de noviembre de 2026