> ## 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 Pesquisa KYB no Registo de Empresas > Didit: POST /v3/kyb/search/ encontra empresas candidatas. Pesquisas bem-sucedidas em fontes pagas custam $0.50 por pedido; perfis à parte. Use este endpoint primeiro para encontrar candidatos correspondentes no registo de empresas. A pesquisa não cria uma Verificação manual guardada. As pesquisas autónomas bem-sucedidas que usem uma fonte de dados de empresas paga custam **\$0.50 por pedido**, independentemente do número de candidatos. Resultados vazios, pesquisas falhadas e resultados fornecidos apenas por outras fontes não são cobrados. A obtenção posterior de um perfil é faturada à parte. Para uma pesquisa que possa usar uma fonte paga, a Didit verifica e reserva o preço de pesquisa aplicável antes de contactar o registo. Um saldo insuficiente devolve `403` com `code: "insufficient_credits"`. A faturação contratual segue a tarifa de pesquisa acordada; uma tarifa contratual não configurada é rejeitada antes da pesquisa. As pesquisas em sandbox são gratuitas. Cada pesquisa repetida bem-sucedida é um novo pedido faturável; a entrega do callback não acrescenta outra cobrança de pesquisa. Se enviar `webhook_url`, a Didit pode responder de imediato enquanto o fornecedor resolve a pesquisa e, depois, envia os candidatos para o seu URL de retorno quando estiverem prontos. O callback não é assinado por conceção, por isso não precisa de configurar um segredo do webhook para esta notificação de pesquisa. Consulte o [exemplo de payload do callback da pesquisa](https://docs.didit.me/pt/standalone-apis/kyb-registry.md#callback-da-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 obter o perfil faturável do registo no nível de que precisa. > [!NOTE] > > O `fetch_status` de cada candidato é `pending` no momento da pesquisa e mantém-se `pending` até selecionar esse candidato. A pesquisa apenas lista candidatos, e a seleção é que obtém o perfil completo. Não faça polling à pesquisa à espera que isto se resolva. > > O `kyb_response_id` é um identificador opaco e efémero, limitado a um único pedido de pesquisa: devolva-o exatamente como o recebeu, nunca o interprete nem derive nada do seu conteúdo, e espere que repetir a mesma pesquisa devolva novos IDs. Selecione o candidato logo após a pesquisa e use `registration_number` quando precisar de um identificador estável para a própria empresa. ## Nível de pesquisa `tier` seleciona o nível do registo cuja cadeia de fornecedores a pesquisa usa: `basic` (o predefinido, a cadeia Lite), `shareholders` ou `ubo`. A lista de candidatos vem da cadeia desse nível, que nem sempre é a fonte que a pesquisa Lite consulta; por isso, uma pesquisa Lite vazia não prova que o registo não tem a empresa. Pesquise novamente no nível de que precisa. Quando o país não oferece o nível indicado, a pesquisa é executada no nível mais alto que ele oferece até esse. Um país sem qualquer dado de registo não é oferecido para verificações de registo; continue com a introdução manual da empresa. Pesquise no nível que pretende comprar e, depois, obtenha o candidato no endpoint que o vende: | `tier` pesquisado | Endpoint que obtém o candidato | | - | - | | `basic` (predefinido) | `POST /v3/kyb/select/` (Lite) | | `shareholders` | `POST /v3/kyb/shareholders/` | | `ubo` | `POST /v3/kyb/ubo/` | ## search\_type `search_type` aceita apenas `contains`, que é também o predefinido. As fontes de registo por detrás da pesquisa procuram o nome da empresa por inclusão, por isso `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 da empresa. ## Pesquisa alojada e autónoma `POST /v1/kyb/search/` é a pesquisa que um fluxo de verificação alojado executa: é autenticada pela sessão de verificação, responde `403` a uma chave de API e não aceita `tier`, pois a configuração do registo KYB do fluxo escolhe a cadeia. As chamadas autónomas à API usam `POST /v2/kyb/search/` ou `POST /v3/kyb/search/` com o seu `x-api-key`; o parâmetro `tier` e os endpoints de seleção por nível são a forma de uma integração autónoma chegar aos mesmos candidatos, no nível de que precisa. ## Tratar indisponibilidades do registo Se o fornecedor do registo estiver temporariamente indisponível, o endpoint devolve `502` com um código estável e legível por máquina: ```json theme={null} { "detail": "The company registry provider is temporarily unavailable.", "code": "kyb_registry_provider_unavailable" } ``` Quando receber este código, deixe o utilizador continuar com a introdução manual da empresa ou peça-lhe que tente novamente mais tarde. Mantenha os erros de validação separados: parâmetros de pesquisa inválidos devolvem `400` e não usam este código de indisponibilidade. ## Tratar países não suportados e limites de pesquisa Dois outros códigos estáveis indicam que deve parar de tentar novamente e continuar com a introdução manual da empresa: | Estado | `code` | Quando | | - | - | - | | `400` | `kyb_registry_country_unsupported` | O país não tem fonte de registo de empresas em nenhum nível. A limitação é permanente, por isso repetir a mesma pesquisa nunca tem sucesso. | | `429` | `kyb_registry_search_limit_reached` | A sua aplicação esgotou a quota de 600 pesquisas por hora em fontes de dados de empresas pagas, e não resta nenhuma fonte gratuita para o país. Aguarde que a janela passe ou introduza a empresa manualmente. | No fluxo alojado, cada passo de registo permite 3 pesquisas numa fonte de dados de empresas paga. Após a terceira, o requerente recebe a opção de introdução manual. Selecionar um candidato que é um registo de marca comercial e não uma empresa devolve `400` com `code: "kyb_registry_entry_not_a_company"`. Escolha, em vez disso, uma empresa dos resultados da pesquisa. ## OpenAPI ````yaml pt/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: Pesquisa de empresa no registo KYB (autónoma) description: >- Pesquise registos de empresas oficiais para encontrar empresas candidatas por nome e/ou número de registo. Este é o passo 1 do fluxo de registo de dois passos: a **pesquisa** devolve candidatos simplificados e, em seguida, o `POST /v3/kyb/select/` obtém o perfil completo de um candidato. **Faturação de pesquisas.** Pesquisas bem-sucedidas que utilizem uma fonte de dados empresariais paga custam USD 0.50 por pedido, 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 de pesquisar; saldo insuficiente devolve 403 com o código `insufficient_credits`. As tarifas contratuais aplicam-se quando acordadas, e uma tarifa contratual de pesquisa não configurada devolve 403. As pesquisas em sandbox são gratuitas. Repetir uma pesquisa bem-sucedida pode implicar uma nova cobrança; a entrega do callback não adiciona qualquer cobrança. A obtenção do perfil é faturada separadamente. Esta taxa de pesquisa também se aplica à v2. Os candidatos são sempre devolvidos com `fetch_status: "pending"`: os dados completos da empresa só são obtidos (e faturados) na seleção. **`kyb_response_id` é efémero.** É um identificador por pesquisa, não um ID de empresa estável. Selecione prontamente após pesquisar e pesquise novamente para obter um identificador recente em vez de o armazenar. **`tier` escolhe a cadeia de fornecedores.** `tier` indica o nível de registo no qual a pesquisa é executada: `basic` (a predefinição, a cadeia Lite), `shareholders` ou `ubo`. A pesquisa utiliza a cadeia de fornecedores que serve esse nível, e nem sempre é a mesma cadeia que a pesquisa Lite consulta, pelo que uma pesquisa Lite vazia não é prova de que o registo não contenha a empresa — pesquise novamente no nível de que necessita. Um país que não disponibilize o nível indicado é pesquisado no nível mais elevado que disponibilizar até esse. Obtenha o candidato a partir do endpoint que fornece 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 endpoint alojado `POST /v1/kyb/search/` é a rota autenticada por sessão que um fluxo de verificação alojado chama: responde com `403` a uma chave de API e não aceita `tier` — a configuração do registo KYB do fluxo escolhe a cadeia. **Dois modos.** - *Síncrono (predefinição):* a API consulta o registo até que a pesquisa seja resolvida e devolve a lista final de candidatos (`search_resolved: true`). - *Assíncrono:* passe `webhook_url` e a API responde imediatamente — normalmente com `search_status: "pending"` e uma lista de candidatos vazia — e, em seguida, envia um pedido POST com o callback `kyb.registry_search.resolved` para o seu URL quando o registo 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"}` — note que `timestamp` e `created_at` no callback são números inteiros epoch, ao contrário do `created_at` em formato ISO deste endpoint — e é enviado **não assinado** (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 registos são regionais — por exemplo, `US-CA` para a Califórnia. **Sandbox.** Chaves de aplicações em sandbox devolvem um candidato estático sem contactar nenhum registo. 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 cujo registo de empresas deve ser pesquisado. Por exemplo, `GB`. Onde os registos de empresas operam a nível estadual ou provincial, anexe o código de subdivisão ISO 3166-2 como `XX-YY`: `US-CA` pesquisa o registo da Califórnia. As pesquisas nos Estados Unidos requerem sempre a subdivisão — um simples `US` é rejeitado. Insensível a maiúsculas e minúsculas; normalizado para maiúsculas. example: GB name: type: string maxLength: 255 description: >- Nome da empresa a pesquisar. É obrigatório indicar `name` ou `registration_number`. example: Tesco registration_number: type: string maxLength: 100 description: >- Número de registo a pesquisar. É obrigatório indicar `name` ou `registration_number`. tier: type: string enum: - basic - shareholders - ubo default: basic description: >- Nível do registo de empresas cuja cadeia de fornecedores executa esta pesquisa. `basic` (predefiniçã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, pelo que uma pesquisa Lite vazia não prova que a empresa não conste do registo de empresas. Um país que não disponibilize o nível indicado é pesquisado no nível mais elevado disponível até esse. Obtenha o candidato a partir do endpoint que comercializa 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 pesquisa no registo. `contains` é o único valor aceite: nenhuma fonte de registo por detrás da pesquisa disponibiliza um modo de prefixo ou aproximado (fuzzy), pelo que `start_with` e `fuzzy` são rejeitados com `400` (`not a valid choice`). vendor_data: type: string description: >- O seu identificador para esta consulta; devolvido e incluído no callback do webhook. metadata: type: object nullable: true description: >- JSON de formato livre; devolvido na resposta e incluído no callback do webhook. webhook_url: type: string format: uri maxLength: 500 description: >- Muda a pesquisa para o modo assíncrono: a API responde imediatamente e envia um callback POST não assinado `kyb.registry_search.resolved` para este 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 aceite. O modo síncrono devolve a lista final de candidatos; o modo webhook devolve imediatamente (frequentemente `search_status: "pending"`) e entrega a lista final através 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 do pedido de pesquisa, devolvido como `request_id` no callback `kyb.registry_search.resolved`. Sem `webhook_url`: um UUID de correlação transitório (a pesquisa não é armazenada). kyb_registry: $ref: '#/components/schemas/KYBRegistrySearchResults' vendor_data: type: string nullable: true description: Eco do `vendor_data` que enviou. metadata: type: object nullable: true description: Eco do objeto `metadata` que 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` fornecido — os candidatos chegam através do 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 ao nível do campo utilizam o envelope padrão do DRF; a regra de nome/número de registo é reportada sob `non_field_errors`. Um país não abrangido pelos registos responde com `400` e `code: kyb_registry_country_unsupported`. content: application/json: examples: Missing search criteria: summary: Nem `name` nem `registration_number` foram fornecidos value: non_field_errors: - Either 'name' or 'registration_number' is required. Invalid country_code: summary: Tem de ser `XX` (alfa-2) ou subdivisão `XX-YY` value: country_code: - country_code must be a 2-letter ISO code. Invalid search_type: summary: Apenas `contains` é aceite value: search_type: - '"start_with" is not a valid choice.' Invalid webhook_url: summary: '`webhook_url` tem de ser um URL válido' value: webhook_url: - Enter a valid URL. Country not covered: summary: Nenhum registo de empresas abrange 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. Devolvido quando o cabeçalho `x-api-key` está em falta; uma chave incorreta, revogada ou expirada devolve `401`. Uma chave em falta devolve `403` com `{"detail": ...}`; uma chave incorreta, revogada ou expirada devolve `401`. Também é devolvido antes de pesquisar quando a taxa de pesquisa aplicável não pode ser coberta (`code: "insufficient_credits"`), ou quando falta uma taxa de pesquisa por contrato. content: application/json: examples: Missing or invalid API key: summary: Sem 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 pedidos excedido, ou o limite de pesquisas foi esgotado. Os endpoints POST/PATCH/DELETE partilham um orçamento de 300 pedidos de escrita por minuto por chave de API (as criações de transações e a ingestão de eventos têm um orçamento separado de 600), com cabeçalhos `X-RateLimit-*` e `Retry-After`. Separadamente, as pesquisas pagas no registo estão limitadas a 600 por aplicação por hora: acima disso, a resposta é `429` com `code: kyb_registry_search_limit_reached`, e as pesquisas disponibilizadas apenas por fontes gratuitas continuam a funcionar. Aguarde e pesquise novamente mais tarde. content: application/json: examples: Write rate limit exceeded: summary: Mais de 300 pedidos 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 pesquisas 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 fornecedor de registo de KYB está temporariamente indisponível - uma resposta 5xx, tempo limite esgotado ou falha de ligação do registo a montante. A pesquisa não é faturada. Tente novamente mais tarde ou, no fluxo de verificação alojado da Didit, é oferecida automaticamente ao utilizador a introdução manual da empresa em vez de um erro que apenas permite tentar novamente. content: application/json: examples: Registry provider outage: summary: O fornecedor do registo de empresas não respondeu à pesquisa 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 para este candidato — passe-o para `POST /v3/kyb/select/` para obter o perfil completo. Efémero e limitado a esta pesquisa: não o guarde a longo prazo; pesquise novamente para obter um novo. example: 69aeeb95febb0f1704042259 name: type: string nullable: true description: Nome registado da empresa. example: Tesco PLC registration_number: type: string nullable: true description: Número de registo. example: '00445790' status: type: string nullable: true description: >- Estado normalizado da empresa no registo de empresas (por exemplo, `active`, `dissolved`, `inactive`, `struck off`). example: active type: type: string nullable: true description: Forma jurídica comunicada pelo registo. example: Public Limited Company registered_address: type: string nullable: true description: >- Morada registada do candidato, quando o registo devolve uma. Utilize-a, juntamente com o número de registo, para distinguir empresas com o mesmo nome: nos Estados Unidos, um candidato pode constar sob o estado onde a empresa opera em vez do estado que pesquisou. example: >- Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, AL7 1GA risk_level: type: string nullable: true description: >- Nível de risco reportado pelo registo de empresas, quando disponível. Geralmente `null` no momento da pesquisa. fetch_status: type: string nullable: true description: >- Sempre `pending` para candidatos de pesquisa — o perfil completo da empresa só é obtido (e faturado) quando seleciona o candidato. example: pending description: >- Lista desduplicada de candidatos. Vazia enquanto `search_resolved=false` (modo webhook) ou quando não houver correspondências. pagination: type: object properties: total: type: integer description: Número de candidatos devolvidos. page: type: integer per_page: type: integer example: 25 search_status: type: string nullable: true enum: - pending - resolved description: Estado do ciclo de vida da pesquisa no registo de empresas. search_resolved: type: boolean description: '`true` assim que a lista de candidatos for final.' securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- A chave de API da sua aplicação, a partir de Programadores -> Chaves de API na Business Console. A chave principal tem acesso total. Uma chave nomeada pode ter o âmbito definido: nenhum, 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á incorreta, 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 o pedido veio de um endereço fora da sua lista de IP; 404 numa rota de sessão significa que a sessão está fora dos fluxos ou estados da chave. Uma chave sem acesso a multimédia recebe URLs de imagens, vídeos e PDFs como nulos, e uma chave sem permissão de escrita em sessões recebe ligações de sessão e tokens como nulos. Consulte https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.