curl --request POST \
  --url https://api.gotrebol.com/verifications \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "country": "mx",
  "tag": "etiqueta",
  "flow_id": "some-flow-id",
  "friendly_name": "Empresa ACME S.A. de C.V.",
  "metadata": {
    "some": "value"
  },
  "key_people": [
    {
      "names": "John Doe",
      "scope": [
        "powers"
      ]
    }
  ]
}
'

{
  "id": "c8dc41fc-c477-404e-aff7-b9074f86d6d1",
  "status": "pending",
  "account_id": "99999999-9999-9999-9999-999999999999",
  "created_at": "2025-04-28T20:10:06.840Z",
  "updated_at": "2025-04-28T20:10:06.840Z",
  "flow_id": "documents-v2",
  "documents_status": "pending_upload",
  "onboarding_url": "https://onboarding.gotrebol.com/verification/c8dc41fc-c477-404e-aff7-b9074f86d6d1/docs-v2?accessToken=accesstokenid32432434&country=mx&client=99999999-9999-9999-9999-999999999999",
  "details_url": "https://app.gotrebol.com/verifications/c8dc41fc-c477-404e-aff7-b9074f86d6d1",
  "access_token": "eyJhbGciOiJIUzI1NiJ9...",
  "items": [
    {
      "id": 25440,
      "item_status": "pending",
      "item_type": "ubos",
      "item_internal_status": "pending_validation",
      "item_value": {},
      "validation_result": {},
      "item_scope": "basic",
      "item_options": {
        "upload_url": "<string>",
        "is_optional": true
      }
    }
  ],
  "tag": "33332-34-22",
  "email": "johndoe@mail.com",
  "country": "mx",
  "tax_id": "SAG160927GIA",
  "business_name": "Trebol OPCO SAS",
  "friendly_name": "Empresa ACME S.A. de C.V.",
  "options": {},
  "created_by": "99999999-9999-9999-9999-999999999999",
  "onboarding_terms_and_conditions": "<string>"
}

{
  "success": false,
  "data": {
    "creator_email": "j***@trebol.com",
    "business_name": "Empresa Ejemplo S.A. de C.V."
  }
}

{
  "success": false,
  "message": "Descripción breve y accionable del error",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-01-01T12:34:56.000Z"
}

{
  "success": false,
  "message": "Unauthorized",
  "code": "UNAUTHORIZED",
  "timestamp": "2025-01-01T12:34:56.000Z"
}

{
  "success": false,
  "message": "Descripción breve y accionable del error",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-01-01T12:34:56.000Z"
}

{
  "success": false,
  "message": "Internal server error",
  "code": "INTERNAL_SERVER_ERROR",
  "timestamp": "2025-01-01T12:34:56.000Z"
}

Creacion de Verificacion

Crear una nueva verificación

Inicia una nueva verificación con los documentos especificados.

Nota: Este endpoint permite crear verificaciones de empresas con documentos y configuraciones personalizadas.

RFC de prueba: con tax_id igual a TRB010101OK1, TRB010101NF1, TRB010101ER1, TRB010101DV1 o TRB010101RF1, la verificación se resuelve con una respuesta fija de KYB México, sin consultar fuentes externas y sin cobro. Trébol reemplaza los items enviados por los del escenario. Ver RFC de prueba.

POST

verifications

curl --request POST \
  --url https://api.gotrebol.com/verifications \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "country": "mx",
  "tag": "etiqueta",
  "flow_id": "some-flow-id",
  "friendly_name": "Empresa ACME S.A. de C.V.",
  "metadata": {
    "some": "value"
  },
  "key_people": [
    {
      "names": "John Doe",
      "scope": [
        "powers"
      ]
    }
  ]
}
'

{
  "id": "c8dc41fc-c477-404e-aff7-b9074f86d6d1",
  "status": "pending",
  "account_id": "99999999-9999-9999-9999-999999999999",
  "created_at": "2025-04-28T20:10:06.840Z",
  "updated_at": "2025-04-28T20:10:06.840Z",
  "flow_id": "documents-v2",
  "documents_status": "pending_upload",
  "onboarding_url": "https://onboarding.gotrebol.com/verification/c8dc41fc-c477-404e-aff7-b9074f86d6d1/docs-v2?accessToken=accesstokenid32432434&country=mx&client=99999999-9999-9999-9999-999999999999",
  "details_url": "https://app.gotrebol.com/verifications/c8dc41fc-c477-404e-aff7-b9074f86d6d1",
  "access_token": "eyJhbGciOiJIUzI1NiJ9...",
  "items": [
    {
      "id": 25440,
      "item_status": "pending",
      "item_type": "ubos",
      "item_internal_status": "pending_validation",
      "item_value": {},
      "validation_result": {},
      "item_scope": "basic",
      "item_options": {
        "upload_url": "<string>",
        "is_optional": true
      }
    }
  ],
  "tag": "33332-34-22",
  "email": "johndoe@mail.com",
  "country": "mx",
  "tax_id": "SAG160927GIA",
  "business_name": "Trebol OPCO SAS",
  "friendly_name": "Empresa ACME S.A. de C.V.",
  "options": {},
  "created_by": "99999999-9999-9999-9999-999999999999",
  "onboarding_terms_and_conditions": "<string>"
}

{
  "success": false,
  "data": {
    "creator_email": "j***@trebol.com",
    "business_name": "Empresa Ejemplo S.A. de C.V."
  }
}

{
  "success": false,
  "message": "Descripción breve y accionable del error",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-01-01T12:34:56.000Z"
}

{
  "success": false,
  "message": "Unauthorized",
  "code": "UNAUTHORIZED",
  "timestamp": "2025-01-01T12:34:56.000Z"
}

{
  "success": false,
  "message": "Descripción breve y accionable del error",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-01-01T12:34:56.000Z"
}

{
  "success": false,
  "message": "Internal server error",
  "code": "INTERNAL_SERVER_ERROR",
  "timestamp": "2025-01-01T12:34:56.000Z"
}

Authorizations

x-api-key

string

header

required

Body

application/json

Hay dos formas de crear una verificacion, usando un flujo predefinido, el cual ya contiene todos los items y configuraciones necesarias o bien pasando un array de items a verificar, la cual permite crear una verificacion con items personalizados, sin un flujo predefinido.

Con Flow ID
Con items predefinidos por el usuario

flow_id

string

required

Identificador para el flujo de verificación específico, este creara una verificacion con los items y validaciones ya definidas en el flujo. No es necesario incluir el campo items si se usa este campo.

Example:

"documents-v2"

country

string

required

El código del país en formato ISO 3166-1 alfa-2. Actualmente soportado solo para México ('mx').

tag

string

required

Una etiqueta única que identifica la verificación.

tax_id

string

required

El número de identificación fiscal de la empresa.

friendly_name

string

Nombre descriptivo de la empresa o persona que será procesada en la verificación. Este campo es opcional y se recomienda usarlo para facilitar la búsqueda e identificación de verificaciones, ya que el sistema no siempre puede extraer automáticamente el nombre de la empresa o persona a partir de los documentos cargados.

Example:

"Empresa ACME S.A. de C.V."

string<email>

Dirección de correo electrónico del cliente que solicita el onboarding.

Example:

"jonh_doe@gmail.com"

metadata

object

Información adicional o metadatos asociados a la verificación.

options

object

Opciones adicionales para la verificación.

Show child attributes

Response

Verificación creada exitosamente.

string

ID de la verificación creada.

Example:

"c8dc41fc-c477-404e-aff7-b9074f86d6d1"

status

string

Estado actual de la verificación.

Example:

"pending"

account_id

string<uuid>

ID de la cuenta asociada.

Example:

"99999999-9999-9999-9999-999999999999"

created_at

string<date-time>

Fecha y hora de creación de la verificación.

Example:

"2025-04-28T20:10:06.840Z"

updated_at

string<date-time>

Fecha y hora de última actualización de la verificación.

Example:

"2025-04-28T20:10:06.840Z"

flow_id

string

Identificador del flujo de verificación utilizado.

Example:

"documents-v2"

documents_status

enum<string>

Estado de la colección de documentos.

Available options:

pending_upload,

partial_upload,

pending_external,

full_upload

Example:

"pending_upload"

onboarding_url

string<uri>

Link de onboarding para el cliente. Usa el dominio default de Trébol, o el dominio personalizado de la cuenta cuando está verificado (ver "Personalizar el widget").

Example:

"https://onboarding.gotrebol.com/verification/c8dc41fc-c477-404e-aff7-b9074f86d6d1/docs-v2?accessToken=accesstokenid32432434&country=mx&client=99999999-9999-9999-9999-999999999999"

details_url

string<uri>

Link al reporte de la verificación.

Example:

"https://app.gotrebol.com/verifications/c8dc41fc-c477-404e-aff7-b9074f86d6d1"

access_token

string

Token de acceso JWT para la sesión de verificación.

Example:

"eyJhbGciOiJIUzI1NiJ9..."

items

object[]

Lista de ítems/documentos a verificar.

Show child attributes

tag

string

Etiqueta identificadora única del creador de la verificación.

Example:

"33332-34-22"

string<email>

Correo electrónico asociado a la verificación.

Example:

"johndoe@mail.com"

country

string

Código de país ISO 3166-1 alfa-2.

Example:

"mx"

tax_id

string

RFC o número de identificación fiscal.

Example:

"SAG160927GIA"

business_name

string | null

Nombre comercial de la empresa extraído automáticamente de los documentos.

Example:

"Trebol OPCO SAS"

friendly_name

string | null

Nombre descriptivo asignado por el usuario al crear la verificación. Permite identificar fácilmente la empresa o persona asociada a la verificación.

Example:

"Empresa ACME S.A. de C.V."

options

object

Objeto reservado para opciones adicionales.

created_by

string

ID del usuario/cliente que creó la verificación.

Example:

"99999999-9999-9999-9999-999999999999"

onboarding_terms_and_conditions

string | null

Lista de terminos y condiciones de onboarding aprobados por el cliente y asociados a la verificación.

Leer información de la empresa

Creacion de Verificacion

Gestion de item Ids

Invalidar un documento

Exportación de Verificaciones

Síntesis de Dictamen

Labels de Verificacion

Actualizar personas clave de una verificacion

Agregar items a una verificacion

Estado de validacion de documentos

Gestión de Flujos de Cuenta

Gestión de Esquemas de Formularios

Gestión de IPs Permitidas

Gestión de API Keys

Gestión de Política de Retención

Gestión de Webhooks

Tipos de Ítem Personalizados

Leer información de la empresa v1

Crear una nueva verificación

Authorizations

Body

Response