> ## 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 búsqueda en registros de empresas KYB > POST /v3/kyb/search/ de Didit busca empresas candidatas. Búsquedas exitosas en fuentes de pago: $0.50 por solicitud; el perfil se factura aparte. Usa este endpoint primero para encontrar candidatos coincidentes en el registro de empresas. La búsqueda no crea un Manual Check guardado. Las búsquedas independientes exitosas que usan una fuente de datos de empresas de pago cuestan **\$0.50 por solicitud**, sin importar el número de candidatos. Los resultados vacíos, las búsquedas fallidas y los resultados proporcionados únicamente por otras fuentes no se cobran. La obtención posterior de un perfil se factura por separado. En una búsqueda que puede usar una fuente de pago, Didit comprueba y reserva el precio de búsqueda aplicable antes de contactar con el registro. Si el saldo es insuficiente, se devuelve `403` con `code: "insufficient_credits"`. La facturación por contrato sigue la tarifa de búsqueda acordada; si la tarifa del contrato no está configurada, la búsqueda se rechaza antes de realizarse. Las búsquedas en sandbox son gratuitas. Cada búsqueda exitosa repetida es una nueva solicitud facturable; la entrega del callback no añade otro cargo de búsqueda. Si envías `webhook_url`, Didit puede responder de inmediato mientras el proveedor resuelve la búsqueda y, después, enviar los candidatos a tu URL de callback cuando estén listos. El callback no está firmado por diseño, así que no necesitas configurar un secreto de webhook para esta notificación de búsqueda. Consulta el [ejemplo de payload del callback de búsqueda](https://docs.didit.me/es/standalone-apis/kyb-registry.md#callback-de-búsqueda). Después de elegir el `kyb_response_id` correcto, invoca `POST /v3/kyb/select/` (Lite), `POST /v3/kyb/shareholders/` o `POST /v3/kyb/ubo/` para obtener el perfil facturable del registro en el nivel que necesites. > [!NOTE] > > El `fetch_status` de cada candidato es `pending` en el momento de la búsqueda y se mantiene en `pending` hasta que seleccionas ese candidato: la búsqueda solo lista candidatos, y es la selección la que obtiene el perfil completo. No consultes la búsqueda repetidamente esperando a que se resuelva. > > `kyb_response_id` es un identificador opaco y efímero, limitado a una única solicitud de búsqueda: devuélvelo exactamente como lo recibiste, nunca lo analices ni derives nada de su contenido, y ten en cuenta que repetir la misma búsqueda devolverá ids nuevos. Selecciona el candidato poco después de la búsqueda y usa `registration_number` cuando necesites un identificador estable para la propia empresa. ## Nivel de búsqueda `tier` selecciona el nivel de registro cuya cadena de proveedores usa la búsqueda: `basic` (el valor predeterminado, la cadena Lite), `shareholders` o `ubo`. La lista de candidatos procede de la cadena de ese nivel, que no siempre es la fuente que consulta la búsqueda Lite, por lo que una búsqueda Lite vacía no demuestra que el registro no tenga la empresa: vuelve a buscar en el nivel que necesites. Si el país no ofrece el nivel que indicas, la búsqueda se ejecuta en el nivel más alto que ofrezca hasta el nivel indicado. Un país sin ningún dato de registro no está disponible para comprobaciones de registro; continúa con la introducción manual de los datos de la empresa. Busca en el nivel que vas a comprar y, después, obtén el candidato desde el endpoint que lo vende: | `tier` que buscaste | Endpoint que obtiene el candidato | | - | - | | `basic` (predeterminado) | `POST /v3/kyb/select/` (Lite) | | `shareholders` | `POST /v3/kyb/shareholders/` | | `ubo` | `POST /v3/kyb/ubo/` | ## search\_type `search_type` solo acepta `contains`, que es el valor predeterminado. Las fuentes de registros en las que se basa la búsqueda buscan coincidencias por contención con el nombre de una empresa, por lo que `start_with` y `fuzzy` se rechazan con `400` (`"start_with" is not a valid choice`) en lugar de tratarse silenciosamente como `contains`. Envía `registration_number` para obtener una coincidencia exacta de la empresa. ## Búsqueda alojada e independiente `POST /v1/kyb/search/` es la búsqueda que ejecuta un flujo de verificación alojado: se autentica mediante la sesión de verificación, responde `403` cuando se usa una clave de API y no admite `tier`, ya que la configuración de registro KYB del flujo elige la cadena. La API independiente invoca `POST /v2/kyb/search/` o `POST /v3/kyb/search/` con tu `x-api-key`; el parámetro `tier` y los endpoints de selección por nivel son la forma en que una integración independiente accede a los mismos candidatos, en el nivel que necesita. ## Gestionar caídas del registro Si el proveedor del registro no está disponible temporalmente, el endpoint devuelve `502` con un código estable que puede leer una máquina: ```json theme={null} { "detail": "The company registry provider is temporarily unavailable.", "code": "kyb_registry_provider_unavailable" } ``` Cuando recibas este código, permite que el usuario continúe con la introducción manual de la empresa o pídele que vuelva a intentarlo más tarde. Mantén separados los errores de validación: una entrada de búsqueda no válida devuelve `400` y no usa este código de interrupción. ## Gestionar países no admitidos y límites de búsqueda Otros dos códigos estables te indican que dejes de reintentar y continúes con la introducción manual de la empresa: | Estado | `code` | Cuándo | | - | - | - | | `400` | `kyb_registry_country_unsupported` | El país no tiene ninguna fuente de registro de empresas en ningún nivel. La limitación es permanente, así que reintentar la misma búsqueda nunca tendrá éxito. | | `429` | `kyb_registry_search_limit_reached` | Tu aplicación ha agotado su cupo de 600 búsquedas por hora en fuentes de datos de empresas de pago y no queda ninguna fuente gratuita para el país. Espera a que pase el intervalo o introduce la empresa manualmente. | En el flujo alojado, cada paso de registro permite 3 búsquedas en una fuente de datos de empresas de pago. Después de la tercera, se ofrece al solicitante la opción de introducir la empresa manualmente. Seleccionar un candidato que es un registro de marca en lugar de una empresa devuelve `400` con `code: "kyb_registry_entry_not_a_company"`. En su lugar, elige una empresa de los resultados de búsqueda. ## OpenAPI ````yaml es/openapi-25.json POST /v3/kyb/search/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API de verificación de identidad. Autentícate con el encabezado x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/kyb/search/: post: tags: - Standalone APIs summary: Búsqueda de empresas en el registro KYB (independiente) description: >- Busca empresas candidatas en los registros oficiales de empresas por nombre y/o número de registro. Este es el paso 1 del flujo de registro en dos pasos: **search** devuelve candidatos ligeros y, después, `POST /v3/kyb/select/` obtiene el perfil completo de un candidato. **Facturación de la búsqueda.** Las búsquedas correctas que usan una fuente de datos de empresas de pago cuestan USD 0.50 por solicitud, sin importar el número de candidatos. No se cobran los resultados vacíos, los fallos ni los resultados que solo provienen de otras fuentes. El precio aplicable se reserva antes de buscar; si el saldo es insuficiente, se devuelve 403 con el código `insufficient_credits`. Se aplican las tarifas contractuales cuando se hayan acordado, y si la tarifa de búsqueda del contrato no está configurada, se devuelve 403. Las búsquedas en sandbox son gratuitas. Repetir una búsqueda correcta puede generar otro cargo; la entrega del callback no añade ningún cargo. La obtención del perfil se factura por separado. Esta tarifa de búsqueda también se aplica a v2. Los candidatos siempre se devuelven con `fetch_status: "pending"`: los datos completos de la empresa solo se obtienen (y se facturan) al seleccionar. **`kyb_response_id` es efímero.** Es un identificador por búsqueda, no un id estable de la empresa. Selecciona poco después de buscar y vuelve a buscar para obtener un identificador nuevo en lugar de almacenarlo. **`tier` elige la cadena de proveedores.** `tier` indica el nivel de registro en el que se ejecuta la búsqueda: `basic` (el valor predeterminado, la cadena Lite), `shareholders` o `ubo`. La búsqueda usa la cadena de proveedores que atiende ese nivel, y no siempre es la misma cadena que consulta la búsqueda Lite, por lo que una búsqueda Lite vacía no demuestra que el registro no contenga la empresa: vuelve a buscar en el nivel que necesites. En un país que no ofrece el nivel que indicas, se busca en el nivel más alto que ofrezca hasta ese. Obtén el candidato desde el endpoint que vende ese nivel: `POST /v3/kyb/select/` (Lite), `POST /v3/kyb/shareholders/` o `POST /v3/kyb/ubo/`. **Autenticación.** `POST /v3/kyb/search/` (y `/v2/`) recibe la clave de API de tu aplicación en el encabezado `x-api-key`. El `POST /v1/kyb/search/` alojado es la ruta autenticada por sesión a la que llama un flujo de verificación alojado: responde `403` a una clave de API y no acepta `tier`; la configuración de registro KYB del flujo elige la cadena. **Dos modos.** - *Síncrono (predeterminado):* la API consulta el registro hasta que la búsqueda se resuelve y devuelve la lista final de candidatos (`search_resolved: true`). - *Asíncrono:* pasa `webhook_url` y la API responde de inmediato (normalmente con `search_status: "pending"` y una lista de candidatos vacía) y luego envía por POST un callback `kyb.registry_search.resolved` a tu URL cuando el registro termina. El cuerpo del callback es `{"event_id", "event_type": "kyb.registry_search.resolved", "request_id", "vendor_data", "metadata", "search_status", "search_resolved", "kyb_registry", "timestamp", "created_at"}` (ten en cuenta que `timestamp` y `created_at` en el callback son enteros de tiempo epoch, a diferencia del `created_at` en formato ISO de este endpoint) y se envía **sin firmar** (encabezado `X-Didit-Unsigned-Callback: true`, sin `X-Signature`). **Códigos de país.** ISO 3166-1 alfa-2 (`GB`, `DE`), además de códigos de subdivisión `XX-YY` donde los registros son regionales, por ejemplo, `US-CA` para California. **Sandbox.** Las claves de aplicaciones de sandbox devuelven un único candidato estático sin contactar con ningún 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 alfa-2 del país en cuyo registro de empresas se busca. Por ejemplo, `GB`. Cuando los registros de empresas funcionan a nivel de estado o provincia, añade el código de subdivisión ISO 3166-2 con el formato `XX-YY`: `US-CA` busca en el registro de California. Las búsquedas en Estados Unidos siempre requieren la subdivisión: un `US` sin subdivisión se rechaza. No distingue mayúsculas y minúsculas; se normaliza a mayúsculas. example: GB name: type: string maxLength: 255 description: >- Nombre de la empresa que se va a buscar. Se requiere `name` o `registration_number`. example: Tesco registration_number: type: string maxLength: 100 description: >- Número de registro que se buscará en el registro. Se requiere `name` o `registration_number`. tier: type: string enum: - basic - shareholders - ubo default: basic description: >- Nivel de registro cuya cadena de proveedores usa esta búsqueda. `basic` (predeterminado) busca en la cadena Lite del país; `shareholders` y `ubo` buscan en la cadena de propiedad de ese nivel, que puede ser una fuente distinta, por lo que una búsqueda Lite vacía no demuestra que la empresa no figure en el registro. En un país que no ofrece el nivel indicado, la búsqueda se hace en el nivel más alto que ofrezca hasta ese. Obtén el candidato desde el endpoint que vende el nivel en el que buscaste: `POST /v3/kyb/select/` (Lite), `POST /v3/kyb/shareholders/` o `POST /v3/kyb/ubo/`. example: basic search_type: type: string enum: - contains default: contains description: >- Estrategia de coincidencia de nombres que aplica la búsqueda en el registro. `contains` es el único valor aceptado: ninguna fuente de registro detrás de la búsqueda ofrece un modo por prefijo o aproximado, por lo que `start_with` y `fuzzy` se rechazan con `400` (`not a valid choice`). vendor_data: type: string description: >- Tu identificador de esta consulta; se devuelve en la respuesta y se incluye en el callback del webhook. metadata: type: object nullable: true description: >- JSON libre; se devuelve en la respuesta y se incluye en el callback del webhook. webhook_url: type: string format: uri maxLength: 500 description: >- Cambia la búsqueda al modo asíncrono: la API responde de inmediato y envía mediante POST un callback `kyb.registry_search.resolved` sin firmar a esta URL cuando la lista de candidatos está lista. example: country_code: GB name: Tesco search_type: contains vendor_data: company-1234 responses: '200': description: >- Búsqueda aceptada. El modo síncrono devuelve la lista de candidatos resuelta; el modo webhook responde de inmediato (a menudo con `search_status: "pending"`) y entrega la lista final mediante el callback `kyb.registry_search.resolved`. content: application/json: schema: type: object properties: request_id: type: string format: uuid description: >- Con `webhook_url`: el id persistido de la solicitud de búsqueda, que se devuelve como `request_id` en el callback `kyb.registry_search.resolved`. Sin `webhook_url`: un UUID de correlación transitorio (la búsqueda no se almacena). kyb_registry: $ref: '#/components/schemas/KYBRegistrySearchResults' vendor_data: type: string nullable: true description: Devuelve el `vendor_data` que enviaste. metadata: type: object nullable: true description: Devuelve el `metadata` que enviaste. 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: >- Se proporcionó `webhook_url`: los candidatos llegan mediante el 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: >- Error de validación. Los problemas a nivel de campo usan el envoltorio estándar de DRF; la regla de nombre/número de registro informa en `non_field_errors`. Un país que los registros no cubren responde `400` con `code: kyb_registry_country_unsupported`. content: application/json: examples: Missing search criteria: summary: No se proporcionó ni `name` ni `registration_number` value: non_field_errors: - Either 'name' or 'registration_number' is required. Invalid country_code: summary: Debe ser `XX` (alpha-2) o una subdivisión `XX-YY` value: country_code: - country_code must be a 2-letter ISO code. Invalid search_type: summary: Solo se acepta `contains` value: search_type: - '"start_with" is not a valid choice.' Invalid webhook_url: summary: '`webhook_url` debe ser una URL válida' value: webhook_url: - Enter a valid URL. Country not covered: summary: Ningún registro de empresas cubre el 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: >- Permiso denegado. Se devuelve cuando falta el encabezado `x-api-key`; una clave incorrecta, revocada o expirada devuelve `401`. Si falta la clave, se devuelve `403` con `{"detail": ...}`; una clave incorrecta, revocada o expirada devuelve `401`. También se devuelve antes de la búsqueda cuando no se puede cubrir la tarifa de búsqueda aplicable (`code: "insufficient_credits"`) o cuando falta una tarifa de búsqueda en el contrato. content: application/json: examples: Missing or invalid API key: summary: >- Falta el encabezado `x-api-key`, o la clave no es válida o está revocada value: detail: You do not have permission to perform this action. '429': description: >- Límite de solicitudes superado o cupo de búsquedas agotado. Todos los endpoints POST/PATCH/DELETE comparten un presupuesto de 300 solicitudes de escritura por minuto por clave de API, con los encabezados `X-RateLimit-*` y `Retry-After`. Por separado, las búsquedas de pago en registros están limitadas a 600 por aplicación por hora: a partir de ese número, la respuesta es `429` con `code: kyb_registry_search_limit_reached`, y las búsquedas atendidas solo por fuentes gratuitas siguen funcionando. Espera y vuelve a buscar más tarde. content: application/json: examples: Write rate limit exceeded: summary: Más de 300 solicitudes de escritura en el minuto actual value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. Search allowance spent: summary: Más de 600 búsquedas de pago en la ú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: >- El proveedor de registros KYB no está disponible temporalmente: el registro de origen devolvió una respuesta 5xx, agotó el tiempo de espera o falló la conexión. La búsqueda no se factura. Vuelve a intentarlo más tarde o, en el flujo de verificación alojado de Didit, al usuario se le ofrece automáticamente introducir la empresa manualmente en lugar de un error que solo permite reintentar. content: application/json: examples: Registry provider outage: summary: El proveedor del registro no respondió a la búsqueda 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 de este candidato: pásalo a `POST /v3/kyb/select/` para obtener el perfil completo. Es efímero y está limitado a esta búsqueda: no lo almacenes a largo plazo; vuelve a buscar para obtener uno nuevo. example: 69aeeb95febb0f1704042259 name: type: string nullable: true description: Razón social registrada. example: Tesco PLC registration_number: type: string nullable: true description: Número de registro en el registro. example: '00445790' status: type: string nullable: true description: >- Estado normalizado de la empresa en el registro (por ejemplo, `active`, `dissolved`, `inactive`, `struck off`). example: active type: type: string nullable: true description: Forma jurídica según el registro. example: Public Limited Company registered_address: type: string nullable: true description: >- Dirección registrada del candidato, cuando el registro la devuelve. Úsala, junto con el número de registro, para distinguir empresas con el mismo nombre: en Estados Unidos, un candidato puede figurar en el estado donde opera la empresa y no en el estado en el que buscaste. example: >- Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, AL7 1GA risk_level: type: string nullable: true description: >- Nivel de riesgo según el registro, cuando está disponible. Normalmente es `null` en el momento de la búsqueda. fetch_status: type: string nullable: true description: >- Siempre `pending` para los candidatos de búsqueda: el perfil completo de la empresa solo se obtiene (y se factura) cuando seleccionas el candidato. example: pending description: >- Lista de candidatos sin duplicados. Vacía mientras `search_resolved=false` (modo webhook) o cuando no hubo coincidencias. pagination: type: object properties: total: type: integer description: Número de candidatos devueltos. page: type: integer per_page: type: integer example: 25 search_status: type: string nullable: true enum: - pending - resolved description: Estado del ciclo de vida de la búsqueda en el registro. search_resolved: type: boolean description: '`true` una vez que la lista de candidatos es definitiva.' securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- La clave de API de tu aplicación, que encontrarás en Developers -> API keys en la Business Console. La clave principal tiene acceso completo. Una clave con nombre puede tener un alcance limitado: ninguno, lectura o escritura por recurso, limitada a algunos flujos o a sesiones aprobadas, a una lista de direcciones IP y a una fecha de caducidad. 401 significa que la clave es incorrecta, se revocó o expiró; 403 significa que no se envió ninguna clave, que la clave no tiene acceso a este recurso o acción, o que la solicitud provino de una dirección fuera de su lista de IP; 404 en una ruta de sesión significa que la sesión está fuera de los flujos o estados de la clave. Una clave sin acceso a contenido multimedia recibe las URL de imágenes, videos y PDF como null, y una clave sin permiso de escritura en sesiones recibe los enlaces y tokens de sesión como null. Consulta https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.