> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # API de busca em registro de empresas (KYB) > POST /v3/kyb/search/ da Didit encontra empresas candidatas. Buscas bem-sucedidas em fontes pagas custam $0.50 por requisição; perfil cobrado à parte. 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](https://docs.didit.me/pt-br/standalone-apis/kyb-registry.md#callback-de-pesquisa). 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. > [!NOTE] > > 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: | `tier` buscado | Endpoint que recupera o candidato | | - | - | | `basic` (padrão) | `POST /v3/kyb/select/` (Lite) | | `shareholders` | `POST /v3/kyb/shareholders/` | | `ubo` | `POST /v3/kyb/ubo/` | ## 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: ```json theme={null} { "detail": "The company registry provider is temporarily unavailable.", "code": "kyb_registry_provider_unavailable" } ``` 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: | Status | `code` | Quando | | - | - | - | | `400` | `kyb_registry_country_unsupported` | O país não tem fonte de registro de empresas em nenhum nível. A limitação é permanente, então repetir a mesma busca nunca terá sucesso. | | `429` | `kyb_registry_search_limit_reached` | Sua aplicação esgotou a cota de 600 buscas por hora em fontes pagas de dados de empresas e não resta nenhuma fonte gratuita para o país. Aguarde o fim da janela ou cadastre a empresa manualmente. | 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. ## OpenAPI ````yaml pt-br/openapi-25.json POST /v3/kyb/search/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API de verificação de identidade. Autentique-se com o cabeçalho x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/kyb/search/: post: tags: - Standalone APIs summary: Busca de empresa no registro KYB (avulsa) description: >- Pesquise registros oficiais de empresas em busca de empresas candidatas por nome e/ou número de registro. Esta é a etapa 1 do fluxo de registro em duas etapas: a **busca** retorna candidatos resumidos e, em seguida, `POST /v3/kyb/select/` recupera o perfil completo de um candidato. **Faturamento da busca.** Buscas bem-sucedidas que usam uma fonte paga de dados de empresas custam USD 0.50 por requisição, independentemente do número de candidatos. Resultados vazios, falhas e resultados fornecidos apenas por outras fontes não são cobrados. O preço aplicável é reservado antes da busca; saldo insuficiente retorna 403 com o código `insufficient_credits`. Tarifas contratuais se aplicam quando acordadas, e uma tarifa contratual de busca não configurada retorna 403. Buscas no sandbox são gratuitas. Repetir uma busca bem-sucedida pode gerar outra cobrança; a entrega do callback não gera cobrança adicional. A recuperação do perfil é cobrada separadamente. Esta tarifa de busca também se aplica à v2. Os candidatos sempre retornam com `fetch_status: "pending"`: os dados completos da empresa só são obtidos (e cobrados) na seleção. **`kyb_response_id` é efêmero.** É um identificador por busca, não um ID estável da empresa. Faça a seleção logo após a busca e busque novamente para obter um novo identificador, em vez de armazená-lo. **`tier` define a cadeia de provedores.** `tier` indica o nível de registro em que a busca é executada: `basic` (o padrão, a cadeia Lite), `shareholders` ou `ubo`. A busca usa a cadeia de provedores que atende a esse nível, e ela nem sempre é a mesma cadeia que a busca Lite consulta; portanto, 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. Um país que não oferece o nível indicado é pesquisado no nível mais alto que ele oferece até esse nível. Recupere o candidato no endpoint que vende esse nível: `POST /v3/kyb/select/` (Lite), `POST /v3/kyb/shareholders/` ou `POST /v3/kyb/ubo/`. **Autenticação.** `POST /v3/kyb/search/` (e `/v2/`) recebe a chave de API da sua aplicação no cabeçalho `x-api-key`. O `POST /v1/kyb/search/` hospedado é a rota autenticada por sessão que um fluxo de verificação hospedado chama: ele responde `403` a uma chave de API e não aceita `tier` — a configuração de registro KYB do fluxo define a cadeia. **Dois modos.** - *Síncrono (padrão):* a API consulta o registro repetidamente até que a busca seja resolvida e retorna a lista final de candidatos (`search_resolved: true`). - *Assíncrono:* passe `webhook_url` e a API retorna imediatamente — geralmente com `search_status: "pending"` e uma lista de candidatos vazia — e depois envia via POST um callback `kyb.registry_search.resolved` para a sua URL quando o registro terminar. O corpo do callback é `{"event_id", "event_type": "kyb.registry_search.resolved", "request_id", "vendor_data", "metadata", "search_status", "search_resolved", "kyb_registry", "timestamp", "created_at"}` — observe que `timestamp` e `created_at` no callback são inteiros epoch, ao contrário do `created_at` em ISO deste endpoint — e é enviado **sem assinatura** (cabeçalho `X-Didit-Unsigned-Callback: true`, sem `X-Signature`). **Códigos de país.** ISO 3166-1 alpha-2 (`GB`, `DE`), além de códigos de subdivisão `XX-YY` onde os registros são regionais — por exemplo, `US-CA` para a Califórnia. **Sandbox.** Chaves de aplicações de sandbox retornam um candidato estático sem contatar nenhum registro. operationId: post_v3_kyb_search parameters: [] requestBody: required: true content: application/json: schema: type: object required: - country_code properties: country_code: type: string maxLength: 10 description: >- 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. example: GB name: type: string maxLength: 255 description: >- Nome da empresa a pesquisar. É obrigatório informar `name` ou `registration_number`. example: Tesco registration_number: type: string maxLength: 100 description: >- Número de registro a ser pesquisado no registro. É obrigatório informar `name` ou `registration_number`. tier: type: string enum: - basic - shareholders - ubo default: basic description: >- 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/`. example: basic search_type: type: string enum: - contains default: contains description: >- 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`). vendor_data: type: string description: >- Seu identificador para esta consulta; retornado na resposta e incluído no callback do webhook. metadata: type: object nullable: true description: >- JSON livre; retornado na resposta e incluído no callback do webhook. webhook_url: type: string format: uri maxLength: 500 description: >- 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. example: country_code: GB name: Tesco search_type: contains vendor_data: company-1234 responses: '200': description: >- 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`. content: application/json: schema: type: object properties: request_id: type: string format: uuid description: >- 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: $ref: '#/components/schemas/KYBRegistrySearchResults' vendor_data: type: string nullable: true description: Eco dos `vendor_data` que você enviou. metadata: type: object nullable: true description: Eco do `metadata` que você enviou. created_at: type: string format: date-time examples: Resolved search: summary: Modo síncrono — lista final de candidatos value: request_id: 0c7e9a40-3a13-4f7e-8a44-9d2e2f1c5b6a kyb_registry: companies: - kyb_response_id: 69aeeb95febb0f1704042259 name: Tesco PLC registration_number: '00445790' status: active type: Public Limited Company risk_level: null fetch_status: pending - kyb_response_id: 69aeeb95febb0f170404225a name: E-TESCO LTD registration_number: '15168476' status: active type: Private Limited Company risk_level: null fetch_status: pending pagination: total: 2 page: 1 per_page: 25 search_status: resolved search_resolved: true vendor_data: company-1234 metadata: null created_at: '2026-06-11T10:40:00.000000+00:00' Pending search (webhook mode): summary: >- `webhook_url` informado: os candidatos chegam pelo callback kyb.registry_search.resolved value: request_id: 5f2d8c1b-7e4a-4b9c-9f0d-3a6e8c2b1d4f kyb_registry: companies: [] pagination: total: 0 page: 1 per_page: 25 search_status: pending search_resolved: false vendor_data: company-1234 metadata: source: onboarding created_at: '2026-06-11T10:41:00.000000+00:00' '400': description: >- Erro de validação. Problemas no nível de campo usam o envelope padrão do DRF; a regra de nome/número de registro é informada em `non_field_errors`. Um país que os registros não cobrem responde `400` com `code: kyb_registry_country_unsupported`. content: application/json: examples: Missing search criteria: summary: Nem `name` nem `registration_number` foram informados value: non_field_errors: - Either 'name' or 'registration_number' is required. Invalid country_code: summary: Deve ser `XX` (alpha-2) ou uma subdivisão `XX-YY` value: country_code: - country_code must be a 2-letter ISO code. Invalid search_type: summary: Somente `contains` é aceito value: search_type: - '"start_with" is not a valid choice.' Invalid webhook_url: summary: '`webhook_url` deve ser uma URL válida' value: webhook_url: - Enter a valid URL. Country not covered: summary: Nenhum registro de empresas cobre o país value: detail: >- Company registry search is not available for this country. Enter the company details manually to continue. code: kyb_registry_country_unsupported '403': description: >- Permissão negada. Retornado quando o cabeçalho `x-api-key` está ausente; uma chave incorreta, revogada ou expirada retorna `401`. Uma chave ausente retorna `403` com `{"detail": ...}`; uma chave incorreta, revogada ou expirada retorna `401`. Também é retornado antes da busca quando a tarifa de busca aplicável não pode ser coberta (`code: "insufficient_credits"`) ou quando falta uma tarifa de busca contratual. content: application/json: examples: Missing or invalid API key: summary: Nenhum cabeçalho `x-api-key`, ou a chave é inválida/revogada value: detail: You do not have permission to perform this action. '429': description: >- Limite de requisições excedido ou cota de buscas esgotada. Todos os endpoints POST/PATCH/DELETE compartilham uma cota de 300 requisições de escrita por minuto por chave de API, com os cabeçalhos `X-RateLimit-*` e `Retry-After`. Separadamente, as buscas pagas em registros são limitadas a 600 por aplicação por hora: acima disso, a resposta é `429` com `code: kyb_registry_search_limit_reached`, e as buscas atendidas apenas por fontes gratuitas continuam funcionando. Aguarde e busque novamente mais tarde. content: application/json: examples: Write rate limit exceeded: summary: Mais de 300 requisições de escrita no minuto atual value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. Search allowance spent: summary: Mais de 600 buscas pagas na última hora value: detail: >- The maximum number of company registry searches for this session has been reached. Enter the company details manually to continue. code: kyb_registry_search_limit_reached schema: type: object properties: detail: type: string code: type: string '502': description: >- O provedor de registro de empresas do KYB está temporariamente indisponível - uma resposta 5xx, timeout ou falha de conexão do registro de origem. A busca não é cobrada. Tente novamente mais tarde ou, no fluxo de verificação hospedado da Didit, o usuário recebe automaticamente a opção de inserir os dados da empresa manualmente, em vez de um erro que só permite tentar novamente. content: application/json: examples: Registry provider outage: summary: O provedor do registro não respondeu à busca value: detail: >- The KYB registry provider is temporarily unavailable. Please try again shortly. code: kyb_registry_provider_unavailable schema: type: object properties: detail: type: string code: type: string security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: |- curl -X POST https://verification.didit.me/v3/kyb/search/ \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "country_code": "GB", "name": "Tesco", "search_type": "contains", "vendor_data": "company-1234" }' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.kyb.search( country_code="GB", name="Tesco", search_type="contains", vendor_data="company-1234", ) print(result) - lang: javascript label: Node.js source: |- import Didit from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.kyb.search({ country_code: "GB", name: "Tesco", search_type: "contains", vendor_data: "company-1234", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.KYB.Search(ctx, didit.KYBSearchParams{\n\tCountryCode: \"GB\",\n\tName: didit.String(\"Tesco\"),\n\tSearchType: didit.Some(didit.KYBSearchParamsSearchType(\"contains\")),\n\tVendorData: didit.String(\"company-1234\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: |- import me.didit.Didit; import me.didit.types.KybSearchParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.kyb().search(KybSearchParams.builder() .countryCode("GB") .name("Tesco") .searchType(KybSearchParams.SearchType.of("contains")) .vendorData("company-1234") .build()); System.out.println(result); - lang: php label: PHP source: |- kyb->search([ 'country_code' => 'GB', 'name' => 'Tesco', 'search_type' => 'contains', 'vendor_data' => 'company-1234', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.kyb.search( country_code: "GB", name: "Tesco", search_type: "contains", vendor_data: "company-1234" ) puts result.to_h - lang: csharp label: .NET source: |- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.Kyb.SearchAsync(new KybSearchParams { CountryCode = "GB", Name = "Tesco", SearchType = new KybSearchParamsSearchType("contains"), VendorData = "company-1234", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: KYBRegistrySearchResults: type: object properties: companies: type: array items: type: object properties: kyb_response_id: type: string nullable: true description: >- Identificador deste candidato: passe-o para `POST /v3/kyb/select/` para obter o perfil completo. É efêmero e restrito a esta busca: não o armazene a longo prazo; faça uma nova busca para obter um novo identificador. example: 69aeeb95febb0f1704042259 name: type: string nullable: true description: Razão social registrada. example: Tesco PLC registration_number: type: string nullable: true description: Número de registro no registro. example: '00445790' status: type: string nullable: true description: >- Status normalizado da empresa no registro (por exemplo, `active`, `dissolved`, `inactive`, `struck off`). example: active type: type: string nullable: true description: Forma jurídica conforme informada pelo registro. example: Public Limited Company registered_address: type: string nullable: true description: >- Endereço registrado do candidato, quando o registro retorna um. Use-o, junto com o número de registro, para distinguir empresas com o mesmo nome: nos Estados Unidos, um candidato pode estar listado no estado onde a empresa opera, e não no estado pesquisado. example: >- Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, AL7 1GA risk_level: type: string nullable: true description: >- Nível de risco informado pelo registro, quando disponível. Geralmente `null` no momento da pesquisa. fetch_status: type: string nullable: true description: >- Sempre `pending` para candidatos da busca: o perfil completo da empresa só é obtido (e cobrado) quando você seleciona o candidato. example: pending description: >- Lista de candidatos sem duplicatas. Vazia enquanto `search_resolved=false` (modo webhook) ou quando nada correspondeu. pagination: type: object properties: total: type: integer description: Número de candidatos retornados. page: type: integer per_page: type: integer example: 25 search_status: type: string nullable: true enum: - pending - resolved description: Status do ciclo de vida da pesquisa no registro. search_resolved: type: boolean description: '`true` quando a lista de candidatos é final.' securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.