Skip to main content
Una vez que una verificación se finaliza (verification_status: finished), puedes consultar la información extraída a través de la API. Trébol ofrece varias formas de acceder a los datos según lo que necesites.
Los endpoints de lectura aplican a todos los casos de uso — KYB, Hipotecas, Nómina, etc. Lo que cambia es el contenido del reporte según los items que incluiste en la verificación.

​
1. Listar verificaciones

Consulta todas las verificaciones de tu cuenta, opcionalmente filtrando por estado. Útil para obtener un listado general o para encontrar verificaciones en un estado específico. 
curl -X GET "https://api.gotrebol.com/verifications?status=finished&page_size=10" \
     -H "x-api-key: {api_key}"

​
Parámetros de consulta

ParámetroTipoRequeridoDescripción
statusstringNoFiltra por estado de la verificación: pending, finished, error, pending_validation.
page_sizeintegerNoCantidad de verificaciones por página. Por defecto 10, máximo 20.
nextstringNoToken de paginación para obtener la siguiente página de resultados.
La respuesta incluye un arreglo data con las verificaciones y un campo next (si hay más páginas) que puedes usar como parámetro en la siguiente llamada. Para la estructura completa de la respuesta, consulta Listar verificaciones de la cuenta en el API Reference.

​
2. Obtener una verificación por ID

Consulta una verificación específica usando su verification_id o el tag (etiqueta) que asignaste al crearla.

​
Por verification_id

curl -X GET "https://api.gotrebol.com/verifications/{verification_id}" \
     -H "x-api-key: {api_key}"

​
Por etiqueta (tag)

curl -X GET "https://api.gotrebol.com/companies/{etiqueta}" \
     -H "x-api-key: {api_key}"
La respuesta incluye el estado de la verificación, sus items con su item_status y los item_value con la información extraída.
Si la verificación tiene consultas a fuentes externas (SAT, RENAPO, INE, SIGER), la respuesta puede incluir lookups_report con una URL firmada para descargar el reporte PDF de auditoría. El campo se omite cuando no hay reporte. Ver Consultas públicas externas.
Para la estructura completa de la respuesta, consulta Obtener una verificación por su ID en el API Reference.

​
3. Leer por sección de la empresa

Para consultas más granulares, puedes leer una sección específica de los datos de la empresa. Esto es útil cuando solo necesitas una parte de la información (por ejemplo, solo los accionistas o solo los documentos). Hay dos formas de consultar por sección:

​
Por ID de verificación

curl -X GET "https://api.gotrebol.com/v2/verifications/{verification_id}/{seccion}" \
     -H "x-api-key: {api_key}"

​
Por etiqueta de empresa (tag)

curl -X GET "https://api.gotrebol.com/v2/companies/{tag}/{seccion}" \
     -H "x-api-key: {api_key}"

​
Secciones disponibles

SecciónDescripciónAplica a
detailsInformación de la empresa: constitución, datos fiscales, domicilio, etc.KYB México
shareholdersAccionistas: nombres, participación, RFC.KYB México
peoplePersonas clave: apoderados, representantes legales, poderes y roles.KYB México
documentsDocumentos asociados a la verificación.Todos los casos de uso
sourcesFuentes de información (items) que alimentan la verificación y datos extraídos.Todos los casos de uso
external-lookupsEvidencia de auditoría de las consultas a fuentes públicas (SAT, RENAPO, INE, SIGER). Ver Consultas públicas externas.KYB México
Las secciones documents y sources están disponibles para cualquier caso de uso (KYB, Hipotecas, Nómina, etc.). Las secciones details, shareholders y people aplican específicamente al caso de uso KYB México.Puedes agregar ?with_citations=true en los siguientes endpoints para obtener URLs firmadas a los artifacts de coordenadas:
  • GET /v2/verifications/{id}/{section} y /v2/companies/{tag}/{section}: para las secciones de people y shareholders devuelven data.citations.url (un artifact por sección).
  • GET /v2/verifications/{id}/{section} y /v2/companies/{tag}/{section}: para la seccion de sources cada item de tipo acta en data.sources recibe su propio campo citations.url.
  • GET /verifications/{id}: cada item de acta en items[] recibe citations.url.
  • GET /verification-items/{id}: el campo citations.url aparece en el objeto raíz si el item es de tipo acta.
Ver Coordenadas de citas.
Para la estructura completa de cada sección, consulta los endpoints en el API Reference:

​
4. Estado de validación de documentos (widget)

Cuando una verificación se crea vía widget con un flow_id que tiene un record_validation_schema, puedes consultar el estado de validación de cada documento requerido. Esto te permite saber qué documentos se han subido, cuáles están pendientes y cuáles han sido validados. 
curl -X GET "https://api.gotrebol.com/verifications/{verification_id}/record_validation" \
     -H "x-api-key: {api_key}"
La respuesta muestra el estado de cada requerimiento definido en el record_validation_schema del flujo, incluyendo si el documento fue subido, clasificado correctamente y validado.
Este endpoint aplica únicamente a verificaciones creadas a través del widget de onboarding que tienen un flujo con record_validation_schema configurado. Para más detalle sobre los estados del expediente, consulta Estados del expediente.
Para la estructura completa de la respuesta, consulta Obtener estado de validación de documentos en el API Reference.

​
Siguientes pasos

Estados de verificación

Ciclo de vida de una verificación: cuándo está lista para consultar.

Webhooks

Recibe eventos automáticos cuando una verificación termina.

Notificaciones

Notificaciones por email, Slack, Teams o Google Workspace.