API de registro KYB: búsqueda y selección de empresas

Endpoints y facturación

Las búsquedas independientes que se completan correctamente con una fuente de pago de datos de empresas cuestan $0.50 por solicitud, sin importar el número de candidatos. No se cobran los resultados vacíos, las búsquedas fallidas ni los resultados que solo proceden de otras fuentes. La obtención posterior de un perfil se factura aparte. La obtención se ofrece en tres niveles de datos, cada uno con su propio endpoint y con precio por país (precios por país):

Endpoint	Qué obtienes	Precio
`POST /v3/kyb/search/`	Empresas candidatas: nombre, número de registro, estado y tipo	$0.50 cuando se devuelven resultados de fuentes de pago
`POST /v3/kyb/select/`	Lite: el perfil de la empresa (identificadores, estado, forma jurídica, fecha de constitución, domicilio social, actividad y datos de contacto) y sus cargos directivos	Precio Lite: $2.00-$3.00 según el país
`POST /v3/kyb/shareholders/`	Lite más los accionistas directos con sus tramos de participación	Precio Shareholders: $5.00-$22.00 según el país
`POST /v3/kyb/ubo/`	Shareholders más los beneficiarios finales identificados a lo largo de la cadena de propiedad	Precio UBO: $9.00-$96.00 según el país

select es el nivel Lite: es lo que factura un flujo KYB alojado por una comprobación de registro en el nivel Lite, y mantiene el mismo contrato de siempre. Europa comprende el EEE, el Reino Unido y Suiza. Una búsqueda Shareholders o UBO consulta la fuente de propiedad asociada a ese nivel. Cuando esa fuente responde que no dispone de información sobre la empresa, la búsqueda consulta también las demás fuentes de registro del país, de modo que una empresa que no figura en la fuente de propiedad se sigue ofreciendo como candidata en lugar de acabar en introducción manual. Los candidatos encontrados de esa forma conservan el nivel que solicitaste: al recuperar sus perfiles se vuelve a consultar la fuente de propiedad y, si sigue sin disponer de información sobre la empresa, se entrega y se factura el perfil Lite, con registry_ownership_status: "not_held".

Pagas por el nivel entregado. Cada respuesta incluye registry_tier_requested y registry_tier_delivered. Cuando los registros del país no tienen datos de propiedad, o el registro no tiene ningún dato de propiedad de la empresa seleccionada, una solicitud de datos de propiedad se entrega y se factura como el nivel más alto disponible (normalmente Lite), y registry_ownership_status indica el motivo. Una solicitud UBO cuyo informe resuelto no identifica a ninguna persona física como beneficiario final se entrega y se factura como Shareholders.

Versiones. Los endpoints Shareholders y UBO solo existen en /v3/. La tarifa de búsqueda independiente también se aplica a /v2/kyb/search/; la obtención del perfil se factura aparte.

Estado de la propiedad

registry_ownership_status indica qué ocurrió con la parte de propiedad de una solicitud de Shareholders o UBO:

Valor	Significado
`not_requested`	La llamada fue una obtención Lite, así que no se solicitó la propiedad.
`delivered`	El registro entregó los datos de propiedad, y el nivel indicado en `registry_tier_delivered` es el que pagas.
`not_held`	El registro de propiedad respondió y no incluye esta empresa, así que no tiene ningún registro de propiedad que entregar: la empresa se encontró a través de otra de las fuentes de registro del país. En su lugar se entrega y factura el perfil Lite, con `registry_data.ownership_error: "company_not_found"`.
`unavailable`	Los datos de propiedad no se entregaron por cualquier otro motivo: el registro que obra en poder del registro no nombra a ningún propietario, el registro no devolvió la sección de propiedad o no se pudo consultar. `registry_data.ownership_error` indica cuál. En su lugar se entrega y factura el perfil Lite.
`pending`	La sección de propiedad aún no se ha obtenido del registro. No se factura nada y `registry_tier_delivered` es `null` hasta que se obtenga.

not_held y unavailable se entregan y facturan como Lite, pero no son el mismo hallazgo: not_held significa que la fuente de propiedad no cubre la empresa (una laguna de cobertura), mientras que unavailable significa que los datos no se entregaron, por una caída o por una sección que el registro dejó vacía. registry_data.ownership_error indica el motivo. Las selecciones que antes devolvían unavailable porque el registro de propiedad no incluía la empresa ahora devuelven not_held; si tu lógica depende del estado, trata ambos como la misma entrega Lite. Dos de sus valores significan cosas distintas y no deben interpretarse como el mismo hallazgo:

`ownership_error`	Significado
`no_owners_on_record`	El registro respondió la sección de propiedad y no nombra a ningún propietario. La empresa no tiene una tabla de capitalización registrada en ese registro.
`ownership_section_unavailable`	El registro no devolvió la sección de propiedad, así que no se entregó nada para ella. La lista falta, no está vacía: no dice nada sobre quién es el propietario de la empresa.

Una sección que el registro no devolvió también se registra de forma estructurada, en registry_data.section_errors, con la sección como clave (officers, shareholders, group_structure) y el estado con el que respondió el registro:

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

section_errors describe la respuesta que tienes, no el historial que hay detrás. Una sección que no se devolvió en la primera solicitud y se entrega en una pasada posterior (consulta la obtención asíncrona más abajo) pierde su entrada, así que registry_ownership_status, ownership_error y section_errors siempre coinciden: una sección delivered nunca tiene entrada, y no_owners_on_record nunca va acompañado de una para shareholders. Además, una sección nunca se entrega de forma parcial: si el registro entrega la primera página de una lista y luego no entrega una posterior, la obtención no se completa en ese intento (una obtención pending se reintenta en su siguiente pasada, y una nueva solicitud recibe como respuesta el error de registro no disponible), de modo que una lista officers o de accionistas entregada es siempre la lista completa que tiene el registro. Trata una sección incluida en section_errors como datos que nunca se entregaron, nunca como un resultado vacío: una lista officers o de accionistas vacía junto a una entrada de section_errors para ella no dice nada sobre la empresa.

Propiedad obtenida de forma asíncrona

Algunos registros se consultan bajo demanda: la primera solicitud sobre una empresa acerca de la cual nunca se ha consultado esa fuente no devuelve ninguna sección de propiedad mientras esta se obtiene, y los datos llegan en un par de minutos. Informar de ello como “sin propiedad registrada” infravaloraría a una empresa que sí tiene accionistas, así que la solicitud se devuelve con el estado pending. Mientras una obtención está en pending, fetch_status también es pending y el estado de la respuesta es 202 Accepted. Didit reintenta la sección por su cuenta y completa la obtención sin que tengas que realizar ninguna otra solicitud:

cuando llegan los datos de propiedad, los accionistas y beneficiarios finales aparecen en la comprobación guardada, registry_tier_delivered pasa a ser el nivel entregado y el uso se cobra en ese nivel;
si la sección sigue vacía cuando se cierra la ventana de reintentos, el estado pasa a unavailable y la solicitud se entrega y factura como Lite.

Guarda el request_id y consulta GET /v3/session/{request_id}/decision/ hasta que registry_checks[0].company.fetch_status sea resolved. No repitas la solicitud de obtención mientras esté en pending: cada nuevo POST es una solicitud independiente que se factura por separado. Usa POST /v3/kyb/search/ para encontrar empresas candidatas. La búsqueda no crea una comprobación guardada. El parámetro tier de la búsqueda elige la cadena en la que se busca; consulta nivel de búsqueda. Las búsquedas en registros pueden tardar unos 90 segundos. Envía webhook_url cuando quieras que Didit responda de inmediato y notifique a tu URL cuando los candidatos estén listos. El callback de búsqueda no está firmado a propósito, así que no necesitas configurar un secreto compartido para esta notificación ligera. Usa POST /v3/kyb/select/, POST /v3/kyb/shareholders/ o POST /v3/kyb/ubo/ con el kyb_response_id devuelto para obtener el perfil en el nivel que necesites. La obtención se factura y guarda el resultado como Manual Check en la Business Console.

Flujo habitual

Busca por nombre de la empresa, número de registro y país, en el tier que piensas comprar (basic es la cadena Lite predeterminada; shareholders y ubo buscan en la cadena de ese nivel).
Si search_resolved=false, espera el callback opcional de webhook_url en lugar de consultar periódicamente.
Muestra los candidatos devueltos a tu operador o cliente.
Obtén el kyb_response_id correspondiente en el nivel que necesites (select para Lite, shareholders o ubo).
Guarda el request_id devuelto y úsalo para obtener el resultado guardado de la verificación de empresa.

Callback de búsqueda

Cuando el proveedor le comunica a Didit que la búsqueda ha finalizado, Didit envía un único POST a tu 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
}

Trata el callback como una notificación de entrega. Usa el kyb_response_id devuelto con POST /v3/kyb/select/, POST /v3/kyb/shareholders/ o POST /v3/kyb/ubo/ para recuperar el perfil del registro, una operación facturable.

Última modificación el 1 de noviembre de 2026

​Endpoints y facturación

​Estado de la propiedad

​Propiedad obtenida de forma asíncrona

​Flujo habitual

​Callback de búsqueda

Endpoints y facturación

Estado de la propiedad

Propiedad obtenida de forma asíncrona

Flujo habitual

Callback de búsqueda