Pular para o conteúdo principal
POST
curl
Use este endpoint primeiro para encontrar candidatos correspondentes no registro de empresas. A busca não cria uma verificação manual salva. Buscas avulsas bem-sucedidas que usam uma fonte paga de dados de empresas custam $0.50 por requisição, independentemente do número de candidatos. Resultados vazios, buscas com falha e resultados fornecidos apenas por outras fontes não são cobrados. Uma recuperação posterior do perfil é faturada separadamente. Para uma busca que pode usar uma fonte paga, a Didit verifica e reserva o preço de busca aplicável antes de consultar o registro. Saldo insuficiente retorna 403 com code: "insufficient_credits". O faturamento por contrato segue a tarifa de busca acordada; a busca é rejeitada antes de ser realizada se a tarifa contratual não estiver configurada. Buscas no sandbox são gratuitas. Cada busca bem-sucedida repetida é uma nova requisição faturável; a entrega do callback não gera outra cobrança de busca. Se você enviar webhook_url, a Didit pode responder imediatamente enquanto o provedor resolve a busca e, depois, enviar os candidatos para sua URL de retorno quando estiverem prontos. O callback não é assinado intencionalmente, então você não precisa configurar um segredo de webhook para esta notificação de busca. Veja o exemplo de payload do callback de busca. Depois de escolher o kyb_response_id correto, chame POST /v3/kyb/select/ (Lite), POST /v3/kyb/shareholders/ ou POST /v3/kyb/ubo/ para recuperar o perfil faturável do registro no nível necessário.
O fetch_status de cada candidato é pending no momento da busca e permanece pending até você selecionar esse candidato: a busca apenas lista candidatos, e é a seleção que obtém o perfil completo. Não consulte a busca repetidamente esperando que ela seja concluída.kyb_response_id é um identificador opaco e efêmero, restrito a uma única requisição de busca: devolva-o exatamente como o recebeu, nunca o analise nem derive nada de seu conteúdo, e espere que repetir a mesma busca retorne novos IDs. Selecione o candidato logo após a busca e use registration_number quando precisar de um identificador estável para a própria empresa.

Nível de busca

tier seleciona o nível do registro em cuja cadeia de provedores a busca é executada: basic (o padrão, a cadeia Lite), shareholders ou ubo. A lista de candidatos vem da cadeia desse nível, que nem sempre é a fonte consultada pela busca Lite; por isso, uma busca Lite vazia não prova que o registro não contém a empresa. Busque novamente no nível de que você precisa. Quando o país não oferece o nível indicado, a busca é executada no nível mais alto disponível até o nível indicado. Um país sem nenhum dado de registro não é oferecido para verificações de registro; continue com o cadastro manual da empresa. Busque no nível que você pretende comprar e, depois, recupere o candidato por meio do endpoint que disponibiliza o candidato:

search_type

search_type aceita apenas contains, que é o padrão. As fontes de registros usadas na busca fazem a correspondência do nome da empresa por contenção, então start_with e fuzzy são rejeitados com 400 ("start_with" is not a valid choice) em vez de serem tratados silenciosamente como contains. Envie registration_number para uma correspondência exata com uma empresa.

Busca hospedada e busca independente

POST /v1/kyb/search/ é a busca executada por um fluxo de verificação hospedado: ela é autenticada pela sessão de verificação, retorna 403 para uma chave de API e não aceita tier, pois a configuração de registro KYB do fluxo de verificação (workflow) escolhe a cadeia. A API independente chama POST /v2/kyb/search/ ou POST /v3/kyb/search/ com seu x-api-key; o parâmetro tier e os endpoints de seleção por nível são a forma como uma integração independente chega aos mesmos candidatos, no nível de que precisa.

Lidar com indisponibilidades do registro

Se o provedor do registro estiver temporariamente indisponível, o endpoint retorna 502 com um código estável legível por máquina:
Ao receber esse código, permita que o usuário continue com o cadastro manual da empresa ou peça que ele tente novamente mais tarde. Trate os erros de validação separadamente: uma entrada de busca inválida retorna 400 e não usa esse código de indisponibilidade.

Lidar com países não suportados e limites de busca

Outros dois códigos estáveis indicam que você deve parar de tentar novamente e continuar com o cadastro manual da empresa: No fluxo hospedado, cada etapa de registro permite 3 buscas em uma fonte paga de dados de empresas. Após a terceira, o solicitante recebe a opção de cadastro manual. Selecionar um resultado que é um registro de marca, e não uma empresa, retorna 400 com code: "kyb_registry_entry_not_a_company". Em vez disso, escolha uma empresa nos resultados da busca.

Autorizações

x-api-key
string
header
obrigatório

Chave de API da sua aplicação, em Developers -> API keys no Business Console. A chave principal tem acesso total. Uma chave nomeada pode ter escopo restrito: nenhum acesso, leitura ou escrita por recurso, limitada a alguns fluxos ou a sessões aprovadas, a uma lista de endereços IP e a uma data de validade. 401 significa que a chave está errada, revogada ou expirada; 403 significa que nenhuma chave foi enviada, que a chave não tem acesso a este recurso ou ação, ou que a requisição veio de um endereço fora da sua lista de IPs; 404 em uma rota de sessão significa que a sessão está fora dos fluxos ou status da chave. Uma chave sem acesso a mídia recebe URLs de imagem, vídeo e PDF como null, e uma chave sem permissão de escrita em sessões recebe links e tokens de sessão como null. Consulte https://docs.didit.me/console/api-keys.

Corpo

application/json
country_code
string
obrigatório

Código ISO 3166-1 alpha-2 do país em cujo registro de empresas a busca será feita. Por exemplo, GB. Onde os registros de empresas operam em nível estadual ou provincial, acrescente o código de subdivisão ISO 3166-2 no formato XX-YY: US-CA busca no registro da Califórnia. Buscas nos Estados Unidos sempre exigem a subdivisão: um US sozinho é rejeitado. Não diferencia maiúsculas de minúsculas; é normalizado para maiúsculas.

Maximum string length: 10
Exemplo:

"GB"

name
string

Nome da empresa a pesquisar. É obrigatório informar name ou registration_number.

Maximum string length: 255
Exemplo:

"Tesco"

registration_number
string

Número de registro a ser pesquisado no registro. É obrigatório informar name ou registration_number.

Maximum string length: 100
tier
enum<string>
padrão:basic

Nível do registro em cuja cadeia de provedores esta pesquisa é executada. basic (padrão) pesquisa a cadeia Lite do país; shareholders e ubo pesquisam a cadeia de propriedade desse nível, que pode ser uma fonte diferente, portanto uma pesquisa Lite vazia não prova que o registro não tenha a empresa. Um país que não oferece o nível indicado é pesquisado no nível mais alto que oferece até esse nível. Obtenha o candidato pelo endpoint que vende o nível pesquisado: POST /v3/kyb/select/ (Lite), POST /v3/kyb/shareholders/ ou POST /v3/kyb/ubo/.

Opções disponíveis:
basic,
shareholders,
ubo
Exemplo:

"basic"

search_type
enum<string>
padrão:contains

Estratégia de correspondência de nomes aplicada pela busca no registro. contains é o único valor aceito: nenhuma fonte de registro por trás da busca oferece modo por prefixo ou aproximado, então start_with e fuzzy são rejeitados com 400 (not a valid choice).

Opções disponíveis:
contains
vendor_data
string

Seu identificador para esta consulta; retornado na resposta e incluído no callback do webhook.

metadata
object | null

JSON livre; retornado na resposta e incluído no callback do webhook.

webhook_url
string<uri>

Muda a busca para o modo assíncrono: a API retorna imediatamente e envia por POST um callback kyb.registry_search.resolved não assinado para esta URL quando a lista de candidatos estiver pronta.

Maximum string length: 500

Resposta

Pesquisa aceita. O modo síncrono retorna a lista de candidatos resolvida; o modo webhook retorna imediatamente (muitas vezes com search_status: "pending") e entrega a lista final por meio do callback kyb.registry_search.resolved.

request_id
string<uuid>

Com webhook_url: o id persistido da requisição de busca, retornado como request_id no callback kyb.registry_search.resolved. Sem webhook_url: um UUID de correlação transitório (a busca não é armazenada).

kyb_registry
object
vendor_data
string | null

Eco dos vendor_data que você enviou.

metadata
object | null

Eco do metadata que você enviou.

created_at
string<date-time>
Última modificação em 1 de novembro de 2026