> ## 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 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. ## OpenAPI ````yaml /api-reference/openapi.yaml post /verifications openapi: 3.0.0 info: title: Coleccion de API KYB MX description: > La Colección de API KYB MX proporciona puntos finales para crear y gestionar verificaciones de empresas en México. La verificación de empresas implica validar la información proporcionada por un cliente comercial, incluyendo documentos y fuentes de datos, para asegurar su legitimidad y precisión. Cada verificación de empresa puede incluir múltiples ítems, como Actas Constitutivas, Constancias de Situación Fiscal, Identificaciones Personales y Comprobantes de Domicilio. Trebol maneja automáticamente la clasificación de documentos, lo que te permite enviar todos los documentos requeridos como URLs descargables (por ejemplo, URLs prefirmadas de AWS o GCP). **Autenticación**: La API utiliza una clave API para la autenticación, pasada en el encabezado `x-api-key`. Para obtener una clave API, por favor [contáctanos](mailto:sales@gotrebol.com). version: 1.0.0 servers: - url: https://api.gotrebol.com - url: http://{{trebol_api_base_url}} security: [] tags: - name: Creacion de Verificacion description: Endpoints para crear nuevas verificaciones. - name: Leer información de la empresa description: >- Endpoints v2 para obtener información detallada de empresas y verificaciones. - name: Leer por Etiqueta description: >- Endpoints para obtener información detallada sobre empresas mediante etiquetas. - name: Leer por ID de Verificacion description: >- Endpoints para obtener información detallada sobre verificaciones mediante ID. - name: Gestión de IPs Permitidas description: >- Endpoints para gestionar la lista de IPs permitidas (whitelist) para la cuenta del cliente. - name: Gestión de API Keys description: Endpoints para crear, listar y eliminar API keys de la cuenta del usuario. - name: Gestion de item Ids description: Endpoints para gestionar items de verificaciones. - name: Invalidar un documento description: Endpoints para invalidar documentos de verificaciones. - name: Labels de Verificacion description: Endpoints para gestionar labels de verificaciones. - name: Actualizar personas clave de una verificacion description: Endpoints para actualizar personas clave de verificaciones. - name: Agregar items a una verificacion description: Endpoints para agregar items a verificaciones existentes. - name: Estado de validacion de documentos description: Endpoints para obtener el estado de validación de documentos. - name: Gestión de Flujos de Cuenta description: Endpoints para gestionar flujos de cuenta. - name: Gestión de Webhooks description: Endpoints para crear, listar, actualizar y eliminar webhooks de la cuenta. - name: Gestión de Política de Retención description: Endpoints para gestionar la política de retención de datos de la cuenta. - name: Exportación de Verificaciones description: >- Endpoints para exportar datos de verificaciones a documentos personalizados. - name: Leer información de la empresa v1 description: >- Endpoints v1 (legacy) para obtener información detallada de empresas y verificaciones. Te recomendamos migrar a los endpoints v2. - name: Tipos de Ítem Personalizados description: >- Endpoints para crear y gestionar tipos de ítem personalizados con procesos configurables de clasificación, validación y extracción. paths: /verifications: post: tags: - Creacion de Verificacion summary: Crear una nueva verificación description: > Inicia una nueva verificación con los documentos especificados. **Nota:** Este endpoint permite crear verificaciones de empresas con documentos y configuraciones personalizadas. operationId: crearNuevaVerificacion requestBody: description: > 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. content: application/json: schema: oneOf: - $ref: '#/components/schemas/VerificationWithFlowId' - $ref: '#/components/schemas/VerificationWithItems' examples: ConFlowId: summary: Usando flow_id value: 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 ConItems: summary: Usando items value: country: mx tag: etiqueta friendly_name: Juan Pérez López items: - type: generic options: file_url: https://www.somepresignedURL.com/withDownloadableFile client_item_type: ac_mx - type: generic options: file_url: https://www.somepresignedURL.com/withDownloadableFile people_scope: - powers client_item_type: person_id metadata: some: value key_people: - names: John Doe scope: - powers ConTipoItemPersonalizado: summary: Usando un tipo de ítem personalizado description: > Cuando tienes un tipo de ítem personalizado creado vía `/v2/custom-item-types`, usa su `name` como valor de `type` en el ítem. Consulta la guía [Tipos de ítem personalizados](/producto/guias/tipos-de-item-personalizados). value: country: mx tag: empresa-ejemplo-001 friendly_name: Empresa ACME S.A. de C.V. items: - type: cit_contrato_arrendamiento options: file_url: https://www.somepresignedURL.com/withDownloadableFile responses: '201': description: Verificación creada exitosamente. content: application/json: schema: type: object properties: id: type: string description: ID de la verificación creada. example: c8dc41fc-c477-404e-aff7-b9074f86d6d1 status: type: string description: Estado actual de la verificación. example: pending account_id: type: string format: uuid description: ID de la cuenta asociada. example: 99999999-9999-9999-9999-999999999999 created_at: type: string format: date-time description: Fecha y hora de creación de la verificación. example: '2025-04-28T20:10:06.840Z' updated_at: type: string format: date-time description: Fecha y hora de última actualización de la verificación. example: '2025-04-28T20:10:06.840Z' flow_id: type: string description: Identificador del flujo de verificación utilizado. example: documents-v2 documents_status: type: string enum: - pending_upload - partial_upload - pending_external - full_upload description: Estado de la colección de documentos. example: pending_upload onboarding_url: type: string format: uri description: Link de onboarding para el cliente. example: >- https://onboarding.gotrebol.com/verification/c8dc41fc-c477-404e-aff7-b9074f86d6d1/docs-v2?accessToken=accesstokenid32432434country=mx&client=99999999-9999-9999-9999-999999999999 details_url: type: string format: uri description: Link al reporte de la verificación. example: >- https://app.gotrebol.com/verifications/c8dc41fc-c477-404e-aff7-b9074f86d6d1 access_token: type: string description: Token de acceso JWT para la sesión de verificación. example: eyJhbGciOiJIUzI1NiJ9... items: type: array description: Lista de ítems/documentos a verificar. items: type: object properties: id: type: integer description: ID del ítem/documento. example: 25440 item_status: type: string description: Estado del ítem/documento. example: pending enum: - pending - complete item_type: type: string description: Tipo de ítem/documento. example: ubos item_internal_status: type: string description: Estado interno del ítem/documento. example: pending_validation nullable: true item_value: type: object description: Valores especificos del ítem/documento. validation_result: type: object description: Resultado de las validaciones del ítem/documento. nullable: true item_scope: type: string description: Alcance del ítem/documento. enum: - basic - advanced example: basic item_options: type: object description: >- Opciones adicionales del ítem/documento que afectan al proceso interno del mismo. properties: is_optional: type: boolean description: Indica si el ítem/documento es opcional. example: true nullable: true tag: type: string description: >- Etiqueta identificadora única del creador de la verificación. example: 33332-34-22 email: type: string format: email description: Correo electrónico asociado a la verificación. example: johndoe@mail.com country: type: string description: Código de país ISO 3166-1 alfa-2. example: mx tax_id: type: string description: RFC o número de identificación fiscal. example: SAG160927GIA business_name: type: string description: >- Nombre comercial de la empresa extraído automáticamente de los documentos. nullable: true example: Trebol OPCO SAS friendly_name: type: string nullable: true description: > 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: type: object description: Objeto reservado para opciones adicionales. created_by: type: string description: ID del usuario/cliente que creó la verificación. example: 99999999-9999-9999-9999-999999999999 onboarding_terms_and_conditions: type: string description: >- Lista de terminos y condiciones de onboarding aprobados por el cliente y asociados a la verificación. nullable: true '208': description: > Verificación duplicada detectada. Se retorna cuando se intenta crear una verificación que ya existe en el sistema para la misma empresa y flujo. **Condiciones para recibir este código:** - El parámetro `verify_duplicate_verification` debe ser `true` - Se debe proporcionar un `tax_id` (RFC/NIT) válido - Se debe proporcionar un `flow_id` válido - Ya existe una verificación activa con el mismo `tax_id`, `account_id` y `flow_id` **Comportamiento:** - Se envía automáticamente un enlace de acceso al email del creador original - Se retorna información básica sobre la verificación existente (con email enmascarado) - No se crea una nueva verificación content: application/json: schema: type: object properties: success: type: boolean description: >- Siempre será `false` para indicar que no se creó una nueva verificación example: false data: type: object description: Información sobre la verificación existente properties: creator_email: type: string description: > Email del creador de la verificación original, enmascarado por privacidad. Formato: primer_carácter + asteriscos + último_carácter + @dominio Ejemplo: "john.doe@example.com" → "j**********e@example.com" example: j***@domain.com business_name: type: string description: >- Nombre comercial de la empresa de la verificación existente example: Trebol OPCO required: - creator_email - business_name examples: DuplicateVerification: summary: Verificación duplicada detectada description: > Respuesta cuando se intenta crear una verificación que ya existe para la misma empresa y flujo. El sistema automáticamente envía un enlace de acceso al creador original. value: success: false data: creator_email: j***@trebol.com business_name: Empresa Ejemplo S.A. de C.V. '400': description: > Solicitud inválida. Posibles causas: - Un ítem referencia un tipo de ítem personalizado que no existe o fue eliminado. - Otros errores de validación del request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': $ref: '#/components/responses/UnauthorizedError' '422': description: | Un ítem referencia un tipo de ítem personalizado archivado. El tipo tiene `status = 'archived'`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': $ref: '#/components/responses/InternalServerError' security: - ApiKeyAuth: [] components: schemas: VerificationWithFlowId: title: Con Flow ID type: object required: - country - tag - flow_id - tax_id properties: flow_id: type: string description: > 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: type: string description: >- El código del país en formato ISO 3166-1 alfa-2. Actualmente soportado solo para México ('mx'). tag: type: string description: Una etiqueta única que identifica la verificación. tax_id: type: string description: El número de identificación fiscal de la empresa. friendly_name: type: string description: > 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. email: type: string format: email description: >- Dirección de correo electrónico del cliente que solicita el onboarding. example: jonh_doe@gmail.com metadata: type: object description: Información adicional o metadatos asociados a la verificación. additionalProperties: true options: type: object description: Opciones adicionales para la verificación. properties: creator_email: type: string format: email description: Email del creador de la verificacion, el usuario empresarial. VerificationWithItems: title: Con items predefinidos por el usuario type: object required: - country - tag - items properties: friendly_name: type: string description: > 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: Juan Pérez López items: type: array description: > Una lista de ítems o documentos que serán verificados, cada item debe tener un tipo y opciones. Esta opcion se utiliza cuando se quiere crear una verificacion con items personalizados, sin un flujo predefinido. items: type: object required: - type - options properties: type: type: string description: El tipo de documento o ítem a verificar. options: type: object required: - file_url description: >- Opciones adicionales para el ítem, como el alcance de las personas involucradas. properties: file_url: type: string description: >- URL de un archivo presignado que se puede descargar para el ítem a verificar. example: https://www.somepresignedURL.com/downloadableFile people_scope: type: array description: >- Especifica el alcance de las personas que deben ser consideradas en la verificación. items: type: string example: powers client_item_type: $ref: '#/components/schemas/ClientItemType' state_code: type: string description: > Código numérico de la entidad federativa para filtrar un ítem `siger` en la fase de `siger_documents` (valor `documents`). Usa uno de los valores aceptados (1–32). enum: - '1' - '2' - '3' - '4' - '5' - '6' - '7' - '8' - '9' - '10' - '11' - '12' - '13' - '14' - '15' - '16' - '17' - '18' - '19' - '20' - '21' - '22' - '23' - '24' - '25' - '26' - '27' - '28' - '29' - '30' - '31' - '32' example: '9' state_name: type: string description: > Nombre de la entidad federativa para filtrar un ítem `siger` en la fase de `siger_documents` (valor `documents`). Debe coincidir con uno de los nombres oficiales listados. enum: - Aguascalientes - Baja California - Baja California Sur - Campeche - Coahuila de Zaragoza - Colima - Chiapas - Chihuahua - Ciudad de México - Durango - Guanajuato - Guerrero - Hidalgo - Jalisco - México - Michoacán de Ocampo - Morelos - Nayarit - Nuevo León - Oaxaca - Puebla - Querétaro - Quintana Roo - San Luis Potosí - Sinaloa - Sonora - Tabasco - Tamaulipas - Tlaxcala - Veracruz de Ignacio de la Llave - Yucatán - Zacatecas example: Ciudad de México fme: type: string description: > Folio mercantil estatal para filtrar la búsqueda de la empresa en la fase de `siger_documents` (valor `documents`). Usa el folio tal como aparece en SIGER. example: FME-2024-001234 legal_name: type: string description: > Razón social para filtrar la búsqueda de la empresa en SIGER. Debe coincidir con la denominación en SIGER. example: EMPRESA EJEMPLO, S.A. DE C.V. country: type: string description: >- El código del país en formato ISO 3166-1 alfa-2. Actualmente soportado solo para México ('mx'). tag: type: string description: Una etiqueta única que identifica la verificación. tax_id: type: string description: El número de identificación fiscal de la empresa. email: type: string format: email description: >- Dirección de correo electrónico del cliente que solicita el onboarding. example: jonh_doe@gmail.com metadata: type: object description: Información adicional o metadatos asociados a la verificación. additionalProperties: true key_people: type: array description: >- Una lista de personas clave asociadas con la empresa que están sujetas a verificación. items: type: object properties: names: type: string description: El nombre completo de la persona clave. scope: type: array description: >- El alcance o las responsabilidades de la persona dentro de la empresa. items: type: string example: powers options: type: object description: Opciones adicionales para el ítem. properties: creator_email: type: string format: email description: Email del creador de la verificacion, el usuario empresarial. disable_siger: type: boolean description: >- Si el valor es true, el sersvicio de siger no se mostrará en la verificacion. siger_data_extraction: type: boolean description: > Si el valor es true, el sistema creará automáticamente items de tipo acta (ac_mx, aa_mx, fme_mx) solo para aquellos actos que contengan eventos relevantes de la empresa (cambios en administración, accionistas, capital social, etc.). El análisis FME se ejecuta para TODOS los actos independientemente del valor de este flag, almacenando los resultados en el item SIGER para consulta posterior. El flag solo controla si se crean los items de acta automáticamente. search_related_companies_siger: type: boolean description: >- Si el valor es true, se creará el item siger_shareholders que contiene información de las empresas relacionadas donde participan los accionistas de la compañía de la verificación. Útil para análisis de beneficiarios finales (UBOs) y estructuras corporativas relacionadas. require_files_for_generic_items: type: boolean description: >- Si el valor es true, los items de tipo generic que no tengan un file_url no se crearán. example: true ErrorResponse: type: object properties: success: type: boolean example: false message: type: string example: Descripción breve y accionable del error code: oneOf: - type: string enum: - VALIDATION_ERROR - BAD_REQUEST - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - CONFLICT - DUPLICATE_RESOURCE - INTERNAL_SERVER_ERROR - type: string description: Código de dominio específico (p.ej., items_not_provided) example: VALIDATION_ERROR timestamp: type: string format: date-time example: '2025-01-01T12:34:56.000Z' ClientItemType: type: string description: >- Especificacion del tipo de item segun el cliente. Consulta los valores disponibles en [Tipos de ítem](/guia-devs/referencia/tipos-item) responses: UnauthorizedError: description: No autorizado content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Unauthorized: summary: Falta API key o inválida value: success: false message: Unauthorized code: UNAUTHORIZED timestamp: '2025-01-01T12:34:56.000Z' InternalServerError: description: Error interno del servidor content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: ServerError: summary: Error inesperado value: success: false message: Internal server error code: INTERNAL_SERVER_ERROR timestamp: '2025-01-01T12:34:56.000Z' securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key ````