API de registro KYB: busca e seleção de empresas

Endpoints e faturamento

Buscas avulsas bem-sucedidas que usam uma fonte paga de dados de empresas custam $0.50 por requisição, independentemente do número de empresas candidatas. Resultados vazios, buscas com falha e resultados fornecidos apenas por outras fontes não são cobrados. A obtenção posterior de um perfil é faturada à parte. A obtenção de dados é vendida em três níveis, cada um com seu endpoint e com preço por país (preços por país):

Endpoint	O que você recebe	Preço
`POST /v3/kyb/search/`	Empresas candidatas: nome, número de registro, status, tipo	$0.50 quando são retornados resultados de fontes pagas
`POST /v3/kyb/select/`	Lite: o perfil da empresa (identificadores, status, forma jurídica, data de constituição, endereço registrado, atividade, dados de contato) e os administradores	Preço Lite: $2.00-$3.00 conforme o país
`POST /v3/kyb/shareholders/`	Lite mais os acionistas diretos com suas faixas de propriedade	Preço Shareholders: $5.00-$22.00 conforme o país
`POST /v3/kyb/ubo/`	Shareholders mais os beneficiários finais identificados ao longo da cadeia de propriedade	Preço UBO: $9.00-$96.00 conforme o país

select é o nível Lite: é o que um fluxo de verificação (workflow) KYB hospedado cobra por uma consulta ao registro no nível Lite, e ele mantém o mesmo contrato de sempre. Europa significa o EEE, o Reino Unido e a Suíça. Uma busca Shareholders ou UBO consulta a fonte de dados de propriedade que atende ao nível. Quando essa fonte responde que não possui dados sobre a empresa, a busca consulta também as outras fontes de registro do país, de modo que uma empresa que a fonte de propriedade não lista ainda é oferecida como candidata, em vez de terminar em entrada manual. As candidatas encontradas dessa forma mantêm o nível solicitado: ao recuperar seus perfis, a fonte de propriedade é consultada novamente e, se ainda não possuir dados sobre ela, o perfil Lite é entregue e faturado, com registry_ownership_status: "not_held".

Você paga pelo nível entregue. Toda resposta traz registry_tier_requested e registry_tier_delivered. Quando os registros do país não têm dados de propriedade, ou o registro não tem informações de propriedade da empresa selecionada, uma requisição de propriedade é entregue e faturada no nível mais alto disponível (geralmente Lite), e registry_ownership_status indica o motivo. Uma requisição UBO cujo relatório final não aponta nenhuma pessoa física como beneficiário final é entregue e faturada como Shareholders.

Versionamento. Os endpoints Shareholders e UBO estão disponíveis apenas em /v3/. A tarifa de busca avulsa também se aplica a /v2/kyb/search/; a obtenção do perfil é faturada à parte.

Status da propriedade

registry_ownership_status indica o que aconteceu com a parte de propriedade de uma requisição Shareholders ou UBO:

Valor	Significado
`not_requested`	A chamada foi uma consulta Lite, portanto nenhum dado de propriedade foi solicitado.
`delivered`	O registro forneceu os dados de propriedade, e o nível em `registry_tier_delivered` é o que você paga.
`not_held`	O registro de propriedade respondeu e não lista esta empresa, então não tem nenhum registro de propriedade para fornecer. A empresa foi encontrada por outra das fontes de registro do país. Em vez disso, o perfil Lite é entregue e faturado, com `registry_data.ownership_error: "company_not_found"`.
`unavailable`	Os dados de propriedade não foram fornecidos por qualquer outro motivo: o registro mantido pelo órgão não indica nenhum proprietário, o registro não retornou a seção de propriedade ou não foi possível consultá-lo. `registry_data.ownership_error` indica qual foi o caso. Em vez disso, o perfil Lite é entregue e faturado.
`pending`	A seção de propriedade ainda não foi obtida do registro. Nada é faturado e `registry_tier_delivered` permanece `null` até que isso aconteça.

not_held e unavailable são ambos entregues e faturados como Lite, mas não representam a mesma constatação. not_held significa que a fonte de propriedade não cobre a empresa, ou seja, uma lacuna de cobertura. Já unavailable significa que os dados não foram fornecidos, seja por uma indisponibilidade, seja por uma seção que o registro deixou vazia. registry_data.ownership_error indica o motivo. Seleções que antes informavam unavailable porque o registro de propriedade não listava a empresa agora informam not_held. Se a sua lógica se ramifica com base no status, trate ambos como a mesma entrega Lite. Dois dos valores desse campo têm significados diferentes e não devem ser interpretados como a mesma constatação:

`ownership_error`	Significado
`no_owners_on_record`	O registro respondeu à seção de propriedade e ela não indica nenhum proprietário. A empresa não tem quadro societário arquivado nesse registro.
`ownership_section_unavailable`	O registro não retornou a seção de propriedade, portanto nada foi entregue para ela. A lista está ausente, não vazia: ela não diz nada sobre quem é o proprietário da empresa.

Uma seção que o registro não retornou também fica registrada de forma estruturada em registry_data.section_errors, com chaves por seção (officers, shareholders, group_structure), com o status com que o registro respondeu:

{
  "section_errors": {
    "shareholders": {
      "status_code": 404
    }
  }
}

section_errors descreve a resposta que você tem em mãos, não o histórico por trás dela. Uma seção que não foi retornada na primeira requisição e é fornecida em uma tentativa posterior (veja a obtenção assíncrona abaixo) perde sua entrada. Assim, registry_ownership_status, ownership_error e section_errors estão sempre de acordo: uma seção delivered nunca tem entrada, e no_owners_on_record nunca vem acompanhado de uma entrada para shareholders. Uma seção também nunca é entregue pela metade: se o registro fornece a primeira página de uma lista e depois falha ao fornecer uma página seguinte, a obtenção não é concluída nessa tentativa. Uma obtenção pending é tentada novamente na próxima tentativa, e uma nova requisição recebe como resposta o erro de registro indisponível. Por isso, uma lista de officers ou de acionistas entregue é sempre a lista completa mantida pelo registro. Trate uma seção listada em section_errors como dados que nunca foram entregues, e nunca como um resultado vazio: uma lista de officers ou de acionistas vazia ao lado de uma entrada em section_errors para ela não diz nada sobre a empresa.

Propriedade obtida de forma assíncrona

Alguns registros são consultados sob demanda: a primeira requisição sobre uma empresa que nunca foi consultada nessa fonte não retorna a seção de propriedade enquanto ela é buscada, e os dados chegam em poucos minutos. Informar isso como “nenhuma propriedade registrada” subestimaria uma empresa que de fato tem acionistas, por isso a requisição retorna pending. Enquanto uma obtenção está pending, fetch_status também fica pending e o status da resposta é 202 Accepted. A Didit tenta obter a seção novamente por conta própria e conclui a obtenção sem nenhuma outra chamada da sua parte:

assim que os dados de propriedade chegam, os acionistas e beneficiários finais aparecem na verificação salva, registry_tier_delivered passa a ser o nível fornecido e o uso é cobrado nesse nível;
se a seção ainda estiver vazia quando a janela de novas tentativas terminar, o status passa a ser unavailable e a requisição é entregue e faturada como Lite.

Guarde o request_id e consulte GET /v3/session/{request_id}/decision/ periodicamente até que registry_checks[0].company.fetch_status seja resolved. Não repita a requisição de obtenção enquanto ela estiver pending: cada novo POST é uma requisição separada, faturada separadamente. Use POST /v3/kyb/search/ para encontrar empresas candidatas. A busca não cria uma verificação salva. O parâmetro tier da busca define a cadeia em que ela pesquisa. Veja nível de busca. As buscas no registro podem levar cerca de 90 segundos. Envie webhook_url quando quiser que a Didit responda imediatamente e notifique sua URL assim que os candidatos estiverem prontos. O callback de busca não é assinado de propósito, então você não precisa configurar um segredo compartilhado para essa notificação simples. Use POST /v3/kyb/select/, POST /v3/kyb/shareholders/ ou POST /v3/kyb/ubo/ com o kyb_response_id retornado para obter o perfil no nível de que você precisa. A obtenção é faturável e salva o resultado como um Manual Check no Business Console.

Fluxo típico

Busque pelo nome da empresa, número de registro e país, no tier que você pretende comprar (basic é a cadeia Lite padrão; shareholders e ubo pesquisam a cadeia desse nível).
Se search_resolved=false, aguarde o callback opcional de webhook_url em vez de fazer consultas periódicas.
Mostre os candidatos retornados ao seu operador ou cliente.
Obtenha o kyb_response_id correspondente no nível de que você precisa (selecione Lite, shareholders ou ubo).
Armazene o request_id retornado e use-o para obter o resultado salvo da verificação de empresa.

Callback de pesquisa

Quando o provedor informa à Didit que a pesquisa foi concluída, a Didit envia um único POST para a sua webhook_url:

{
  "event_id": "7f5a1c93-6a44-4f0e-9f2b-3d8a1c6f2e91",
  "event_type": "kyb.registry_search.resolved",
  "request_id": "b5ef9df5-bd9e-4d61-bbe5-5eb7a8fb6f85",
  "vendor_data": "business-123",
  "metadata": {
    "source": "onboarding"
  },
  "search_status": "resolved",
  "search_resolved": true,
  "kyb_registry": {
    "companies": [
      {
        "kyb_response_id": "kyb_resp_123",
        "name": "TESCO PLC",
        "registration_number": "00445790",
        "status": "active",
        "type": "Public Limited Company",
        "registered_address": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, AL7 1GA",
        "risk_level": null,
        "fetch_status": "pending"
      }
    ],
    "pagination": {
      "total": 1,
      "page": 1,
      "per_page": 25
    },
    "search_status": "resolved",
    "search_resolved": true
  },
  "timestamp": 1767225600,
  "created_at": 1767225600
}

Trate o callback como uma notificação de entrega. Use o kyb_response_id retornado com POST /v3/kyb/select/, POST /v3/kyb/shareholders/ ou POST /v3/kyb/ubo/ para executar a consulta faturável do perfil no registro de empresas.

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

​Endpoints e faturamento

​Status da propriedade

​Propriedade obtida de forma assíncrona

​Fluxo típico

​Callback de pesquisa

Endpoints e faturamento

Status da propriedade

Propriedade obtida de forma assíncrona

Fluxo típico

Callback de pesquisa