Saltar al contenido principal
POST
curl
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. 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.
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:

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:
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: 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.

Autorizaciones

x-api-key
string
header
requerido

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.

Cuerpo

application/json
country_code
string
requerido

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.

Maximum string length: 10
Ejemplo:

"GB"

name
string

Nombre de la empresa que se va a buscar. Se requiere name o registration_number.

Maximum string length: 255
Ejemplo:

"Tesco"

registration_number
string

Número de registro que se buscará en el registro. Se requiere name o registration_number.

Maximum string length: 100
tier
enum<string>
predeterminado:basic

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/.

Opciones disponibles:
basic,
shareholders,
ubo
Ejemplo:

"basic"

search_type
enum<string>
predeterminado:contains

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).

Opciones disponibles:
contains
vendor_data
string

Tu identificador de esta consulta; se devuelve en la respuesta y se incluye en el callback del webhook.

metadata
object | null

JSON libre; se devuelve en la respuesta y se incluye en el callback del webhook.

webhook_url
string<uri>

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.

Maximum string length: 500

Respuesta

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.

request_id
string<uuid>

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
object
vendor_data
string | null

Devuelve el vendor_data que enviaste.

metadata
object | null

Devuelve el metadata que enviaste.

created_at
string<date-time>
Última modificación el 1 de noviembre de 2026