> ## Documentation Index
> Fetch the complete documentation index at: https://gotrebol.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Crear una verificación

> Endpoint POST /verifications: variantes, atributos principales y cómo elegir tu forma de procesamiento.

Esta guía explica cómo usar el endpoint `POST /verifications` para crear verificaciones vía API. Para entender las 3 formas de procesar documentos (clasificación, validación, extracción), consulta [Cómo funciona Vía API](/guia-devs/crear-verificaciones/via-api/overview).

<Note>
  Para el schema técnico completo del endpoint con tipos, validaciones y ejemplos generados del OpenAPI spec, consulta [API Reference — Crear una nueva verificación](https://docs.gotrebol.com/api-reference/creacion-de-verificacion/crear-una-nueva-verificación).
</Note>

***

## Requisitos comunes

Cuando envías documentos con `file_url` (aplica a todas las formas de procesamiento):

<Warning>
  La URL debe estar **disponible por al menos 5 minutos** para garantizar la descarga exitosa por parte de Trébol.
</Warning>

<Info>
  **¿No tienes un `file_url`?** Si tus documentos están en almacenamiento privado o se generan dinámicamente, usa el flujo de [carga directa](/guia-devs/crear-verificaciones/via-api/carga-directa), donde Trébol te proporciona una `upload_url` para subir el archivo directamente.
</Info>

***

## Variantes del endpoint

`POST /verifications` acepta dos esquemas en el body, dependiendo de si usas un account-flow predefinido o envías los items directamente:

| Variante                             | Cuándo usar                                                                                                    | Campos requeridos                     |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| **Con `items`** (API sin flow)       | Cada verificación define sus propios items. Máxima flexibilidad. **Es la forma más común en integración API.** | `country`, `tag`, `items`             |
| **Con `flow_id`** (con account-flow) | Reutilizas una configuración de flow previamente creada. Más común en widget; poco frecuente en API directa.   | `country`, `tag`, `flow_id`, `tax_id` |

***

## Atributos principales

| Atributo        | Tipo     | Requerido | Descripción                                                                                                                                                 |
| --------------- | -------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `country`       | `string` | Sí        | Código del país. Valores soportados: `mx`, `co`. Otros valores se procesan como `not_specified`.                                                            |
| `tag`           | `string` | Sí        | Identificador único de la verificación (tu ID interno del cliente o solicitud).                                                                             |
| `tax_id`        | `string` | Depende   | RFC / NIT de la empresa. Requerido cuando usas `flow_id`.                                                                                                   |
| `friendly_name` | `string` | No        | Nombre descriptivo de la empresa o persona asociada a la verificación.                                                                                      |
| `email`         | `string` | No        | Email del cliente de la verificación.                                                                                                                       |
| `flow_id`       | `string` | Depende   | ID de un account-flow predefinido. Usar **sin** `items`.                                                                                                    |
| `items`         | `array`  | Depende   | Items a procesar. Usar **sin** `flow_id`. Ver las 3 formas en [Cómo funciona Vía API](/guia-devs/crear-verificaciones/via-api/overview).                    |
| `options`       | `object` | No        | Flags específicos del caso de uso (ej: `skip_siger`).                                                                                                       |
| `metadata`      | `object` | No        | Información adicional para tu integración (no procesada por Trébol).                                                                                        |
| `key_people`    | `array`  | No        | **Solo KYB México**. Apoderados con poderes legales. Ver [Overview KYB México](/guia-devs/uso-kyb/mexico/overview#key-people-y-scope-apoderados-y-poderes). |

Para el schema técnico completo con todos los atributos, tipos y ejemplos de request/response, consulta [API Reference](https://docs.gotrebol.com/api-reference/creacion-de-verificacion/crear-una-nueva-verificación).

***

## Siguiente paso: elige tu forma de procesamiento

Cada forma tiene ejemplos de payload completos y estructura de respuesta:

<CardGroup cols={3}>
  <Card title="Forma 1: Clasificación" href="/guia-devs/crear-verificaciones/via-api/forma-clasificacion">
    Trébol detecta el tipo del documento (item `generic`).
  </Card>

  <Card title="Forma 2: Validación" href="/guia-devs/crear-verificaciones/via-api/forma-validacion">
    Verifica tipo y reglas (item `doc_validation`).
  </Card>

  <Card title="Forma 3: Extracción" href="/guia-devs/crear-verificaciones/via-api/forma-extraccion">
    Extrae directamente con tipo directo.
  </Card>
</CardGroup>

## Ejemplos de payload por caso de uso

Cada caso de uso tiene su overview con **variaciones de creación** y ejemplos de payload completos copy-pasteables:

<CardGroup cols={2}>
  <Card title="KYB México" href="/guia-devs/uso-kyb/mexico/overview">
    Verificación de empresas mexicanas: SIGER, SAT, actas, apoderados.
  </Card>

  <Card title="KYB Colombia" href="/guia-devs/uso-kyb/colombia/overview">
    Verificación de empresas colombianas: RUES, RUT, Cámara de Comercio.
  </Card>

  <Card title="KYB Estados Unidos" href="/guia-devs/uso-kyb/eeuu/overview">
    Verificación de empresas en EEUU: certificate of incorporation, IRS EIN, FinCEN.
  </Card>

  <Card title="KYB Todos los países" href="/guia-devs/uso-kyb/todos-paises/items-documentos">
    Items universales para KYB: person\_id, proof\_address, bank\_statement, etc.
  </Card>

  <Card title="Hipotecas" href="/guia-devs/uso-hipotecas/overview">
    Escrituras de propiedad, certificados de gravámenes, avalúos.
  </Card>

  <Card title="Nómina" href="/guia-devs/uso-nomina/overview">
    Recibos de nómina y pensión.
  </Card>
</CardGroup>