Pular para o conteúdo principal
POST
Python
A API de consulta de usuários da Didit associa uma lista de até 20.000 identificadores aos usuários da sua aplicação em uma única chamada e informa quais identificadores não correspondem a nenhum usuário. Use a API quando você tiver uma lista de contas, como os beneficiários de um lote de pagamentos, as contas de um parceiro ou o resultado de uma consulta de fraude, e precisar do status de verificação de cada uma delas.

Como funciona

  1. Consulte a lista. POST /v3/users/lookup/ com seus identificadores. A chamada apenas lê e responde com um lookup_id, as contagens e os identificadores que não correspondem a nenhum usuário.
  2. Leia os usuários. Passe o lookup_id como lookup para Listar usuários. Ela retorna somente os usuários correspondentes, na ordem em que você enviou os identificadores.

Regras de correspondência

Cada identificador é comparado dentro da sua aplicação, nesta ordem:
  • As entradas em branco são descartadas, e as duplicatas são removidas, mantendo a primeira ocorrência.
  • Uma requisição envia no máximo 100.000 entradas. Depois que as entradas em branco e as duplicatas são removidas, devem restar de 1 a 20.000 identificadores. Se qualquer um dos limites for excedido, a resposta é 400 com code: too_many_identifiers.
  • A busca considera somente a sua aplicação.

Requisição

Response

Leia os usuários correspondentes

  • Os usuários são retornados na ordem do identificador na sua lista, paginados com limit e offset. Quando um e-mail corresponde a vários usuários, eles são listados começando pela conta mais antiga.
  • O resultado é mantido por 24 horas, apenas para a sua aplicação. Depois disso, lookup retorna 404 com code: lookup_not_found: envie a lista novamente.

Recuperar uma consulta

GET /v3/users/lookup/{lookup_id}/ retorna o mesmo corpo da consulta, além de identifiers: a lista que você enviou, depois de remover os valores em branco e os duplicados, na mesma ordem. Retorna 404 com code: lookup_not_found quando a consulta expirou, não existe ou pertence a outra aplicação.

Errors

Permissions

A chave de API precisa de acesso de leitura a usuários, e o endpoint nunca altera dados. Uma chave sem esse acesso, ou uma chave revogada, recebe 403. Os escopos são definidos individualmente para cada chave em chaves de API; as funções e permissões do Console determinam o que uma pessoa pode fazer no Console e não são avaliadas no tráfego da API. No Console, Consultar uma lista precisa apenas da permissão para ler usuários.

Relacionados

Autorizações

x-api-key
string
header
obrigatório

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[]
obrigatório

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

Resposta

The lookup was read. Use lookup_id with List users.

lookup_id
string<uuid>
obrigatório

Pass it as lookup to List users.

requested
integer
obrigatório

Identifiers read, after blanks and duplicates were removed.

found
integer
obrigatório

Identifiers that matched at least one user.

not_found
object[]
obrigatório
expires_at
string<date-time>
obrigatório

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

Última modificação em 20 de novembro de 2026