Extraer Apoderados de Actas y Poderes

API KYB: Verificación de Firmantes y Administradores

Este endpoint permite extraer información detallada de los firmantes y administradores de una empresa para el proceso de onboarding de empresas y API KYB. Utiliza OCR de actas constitutivas y otros documentos relevantes para validar la identidad y los roles clave dentro de la entidad.

Esta página documenta la respuesta de GET /v2/verifications/{verification-id}/people (auth con header x-api-key). Para el detalle del endpoint y ejemplos de request consulta Obtener sección por ID de verificación y la guía Leer información.

Estructura de la Respuesta

La respuesta incluye tres listas de personas:

key_people: Lista de firmantes.
signatory_groups: Administradores agrupados por tipo (executives, board_members, etc.). Ver Información de signatory_groups.
full_list: Lista completa de todas las personas detectadas.

Información de Personas Clave

1. Datos Personales

Nombre	Campo JSON	Descripción
Nombres	`names`	Nombre completo del firmante o administrador
Identificación	`id_number`	RFC o CURP detectado
RFC explícito	`id_number_rfc`	RFC cuando difiere de `id_number`
Tipo de ID	`id_type`	`"rfc"` o `"curp"` (o `null`)
Tipo de entidad	`type`	`"person"` o `"business"`
Género	`gender`	Género reportado
Nacionalidad	`nationality`	Nacionalidad (toma valor de CURP cuando existe)
Código de país	`iso_country_code`	ISO 3166-1 alpha-2 (p. ej. `MX`, `US`)
Fecha de nacimiento	`birth_date`	Fecha de nacimiento
Entidad de nacimiento	`birth_entity`	Entidad de nacimiento
ID interno	`people_id`	ID interno de la persona en Trébol
Sugerido por IA	`ai_suggested`	`true` si fue detectada por IA
Revisado por humano	`human_reviewed`	`true` si fue revisada manualmente

2. Roles y Poderes

Nombre	Campo JSON	Descripción
Roles	`roles`	Lista de roles asignados dentro de la empresa

3. Documentación Adicional

identity, fiscal, address y ubo_forms son objetos abiertos cuya estructura depende del documento extraído. Consulta Items de documentos para los esquemas por tipo.

Nombre	Campo JSON	Descripción
Identificación	`identity`	Datos extraídos de documentos de identidad (INE/Pasaporte)
Datos básicos	`basic_data`	Nombre y apellidos normalizados de la persona
Información Fiscal	`fiscal`	Datos extraídos del CSF u otros comprobantes fiscales
Domicilio	`address`	Datos extraídos de comprobantes de domicilio
Formularios UBO	`ubo_forms`	Datos extraídos de formularios UBO
Identidades externas	`external_identities`	Datos obtenidos de fuentes externas (p. ej. consulta CURP en RENAPO)

Detalles de Roles y Poderes

Información del Rol

Cada persona puede tener varios roles, cada rol puede tener varios poderes asociados. La estructura de los roles y poderes es la siguiente:

Nombre	Campo JSON	Descripción
ID del Rol	`id`	Identificador único del rol
Nombre del Rol	`role_name`	Nombre del rol (ej: presidente, secretario)
Grupo	`group_name`	Categoría del rol
Evento	`event`	Evento que originó el rol (`addition`, `mentioned`, `renewal`, `removal`)
Duración	`duration`	Duración en años (-1 = indefinido)
Poderes	`powers`	Lista de poderes otorgados
Fuente	`source`	Detalles del documento validador (ver tabla abajo)
Vencimiento de Poderes	`powers_due_date`	Fecha de vencimiento de los poderes
Origen del Vencimiento	`powers_due_date_source`	Origen de la fecha (`legal` o `document`)

Objeto `source`

Estructura del documento validador:

Campo JSON	Descripción
`item_id`	ID del item documental
`item_type`	Tipo del documento (`ac_mx`, `person_id`, etc.)
`document_url`	URL firmada al PDF original
`document_date`	Fecha del documento
`document_number`	Número/folio del documento
`entity_name`	Nombre de la entidad
`extra_fields`	Datos adicionales específicos del tipo de documento

Poderes Legales

Este es el objeto que describe los poderes legales del representante legal:

Nombre	Campo JSON	Descripción
Duración	`duration`	Duración del poder (-1 = indefinido)
Tiene Poder	`has_power`	Indica si tiene el poder
Tiene Límites	`has_limits`	Indica si existen limitaciones
Nombre del Poder	`power_name`	Tipo de poder otorgado
Tipo de Firma	`signature_type`	Tipo de firma requerida: `"joint"` para firma mancomunada o `"individual"` para firma individual
Descripción de Límites	`limits_description`	Descripción de limitaciones

Tipos de Poderes

Trebol soporta los siguientes tipos de poderes:

Nombre	Campo JSON	Descripción
Títulos de Crédito	`loans`	Poder para firmar titulos de créditos empresariales
Poder de Dominio	`assets_management`	Poder para otorgar garantías, comproventa de activos, etc
Poder de Administración	`administration`	Poder para la gestión operativa general
Poder de Cuentas Bancarias	`bank_accounts`	Poder para abrir o cerrar cuentas bancarias
Poder de Delegación	`delegate`	Poder que permite delegar poderes
Poder de Pleitos y Cobranzas	`lawsuits_and_collections`	Poder que permite hacer la gestión de pleitos y cobranzas

Grupos de Roles

Ya que las empresas deciden tener distintos nombres para los roles, Trebol estandariza los distintos cargos en los siguientes grupos:

Nombre	Campo JSON	Descripción
Consejo	`board_members`	Son los miembros del consejo
Administradores	`executives`	Es el administrador único o equivalentes
Apoderados	`proxies`	Son los apoderados de la empresa
Vigilancia	`auditors`	Son los comisarios o auditores de la empresa

Información de `signatory_groups`

Cada elemento dentro de signatory_groups[group] (p. ej. signatory_groups.executives[]) aparece de forma plana: el rol y sus folios viven al mismo nivel que los datos de la persona, no anidados dentro de un arreglo roles. Comparte la mayoría de campos con key_people, pero tiene 7 propios:

Nombre	Campo JSON	Tipo	Descripción
ID del rol	`role_id`	string \| null	Identificador único del rol asignado a esta persona.
Nombre del rol	`role_name`	string	Nombre del rol (ej. `presidente`, `secretario`).
Evento	`event`	enum	Evento que originó el rol (`addition`, `mentioned`, `renewal`, `removal`).
Duración	`duration`	number	Duración en años del rol (`-1` = indefinido).
Número de folio	`folio_number`	string \| null	Folio del documento que valida el rol.
Fecha del folio	`folio_date`	string \| null	Fecha del folio (`YYYY-MM-DD`).
Fecha de inscripción	`folio_inscription_date`	string \| null	Fecha de inscripción del folio.

Los campos names, id_number, id_number_rfc, id_type, type, identity, fiscal, address, external_identities, ubo_forms, iso_country_code y source siguen la misma semántica que en Información de Personas Clave.

Información de Identidad

Cuando se sube un documento de identificación, domicilio, o comprobante fiscal, Trebol lo valida y extrae la información relevante.

Objeto `identity.person_id`

Datos extraídos del documento de identidad:

Nombre	Campo JSON	Descripción
Descripción	`description`	Tipo de identificación (p. ej. `ine_mx - DASJ850405HSPRVN02`)
Dirección	`address`	Dirección registrada en el documento
Fecha del Documento	`document_date`	Fecha del documento
Fecha de Vencimiento	`due_date`	Vencimiento del documento
Fecha de Emisión	`issued_date`	Emisión del documento
Fecha de Nacimiento	`birth_date`	Fecha de nacimiento
Ciudad de Nacimiento	`birth_city`	Ciudad de nacimiento
País de Nacimiento	`birth_country`	País de nacimiento
Número Nacional	`national_id_number`	Número nacional de identificación
Género	`gender`	Género
Nacionalidad	`nationality`	Nacionalidad
Campos Extra	`extra_fields`	Datos adicionales (CURP, RFC, etc.)
Validaciones	`validations`	Validaciones aplicadas al documento (ver tabla abajo)
Fuente	`source`	Datos del documento (ver `source` en la sección anterior)
Dirección Estructurada	`mx_address`	Dirección desagregada cuando aplica para México

Cada item de `validations`

Campo JSON	Descripción
`validated_at`	Timestamp de la validación
`validation_result`	Resultado (p. ej. `valid_id`)
`source`	Origen de la validación (p. ej. `ine`)

Objeto `basic_data`

Nombre y apellidos normalizados de la persona:

Campo JSON	Descripción
`first_name`	Nombre
`other_names`	Otros nombres
`first_last_name`	Primer apellido
`other_last_names`	Otros apellidos

Información de Domicilio

El objeto address contiene los datos extraídos de comprobantes de domicilio. Es un mapa libre cuya estructura depende del tipo de documento. Consulta Items de documentos para los esquemas por tipo.

Información Fiscal

El objeto fiscal contiene los datos extraídos del CSF u otros comprobantes fiscales (RFC, CURP, dirección fiscal, actividades económicas, etc.). Es un mapa libre cuya estructura depende del documento. Consulta Items de documentos para los esquemas por tipo.

Identidades externas

Trébol consulta RENAPO de forma automática cuando uno de los documentos de la persona (person_id) aporta un número CURP (típicamente extraído de un ine_mx, un passport mexicano o un residence_mx). Cuando la consulta termina, Trébol expone los datos en el item_value del person_id y en external_identities.curp dentro de cada elemento de full_list y key_people. La consulta corre de forma asíncrona. El endpoint devuelve external_identities poblado solo después de que Trébol dispara el webhook verification_people.curp_search_completed. Antes de ese webhook, la llave curp puede no existir o venir en null. Para detalles sobre los campos equivalentes disponibles en el item_value de cada person_id, consulta Items de documentos — Validación de CURP (RENAPO).

Nombre	Campo JSON	Descripción
Número de búsqueda	`search_number`	CURP utilizado para la consulta.
Éxito	`success`	`true` si Trébol logró completar la consulta.
Mensaje	`message`	Mensaje legible cuando `success` es `false`. Llega en `null` cuando todo va bien.
Datos del solicitante	`applicant_data`	Datos personales reportados por RENAPO. Puede llegar en `null` cuando `success` es `false`.
Datos del documento probatorio	`evidentiary_document_data`	Datos del acta de nacimiento o documento probatorio. Puede llegar en `null` cuando `success` es `false`.
Archivo CURP	`curp_file`	URL firmada al PDF descargado de RENAPO. La URL incluye `Expires=…` y caduca: cuando expire, vuelve a consultar `GET /v2/verifications/{verification-id}/people` para obtener una URL renovada.

Cuando success es false, los objetos applicant_data y evidentiary_document_data pueden llegar en null y message describe la causa. Verifica siempre success antes de leer los campos anidados.

Ejemplo de Respuesta

El siguiente ejemplo es una versión recortada para ilustrar la forma general. Para la respuesta completa con todos los campos y un ejemplo navegable, consulta Obtener sección por ID de verificación en el API Reference y selecciona el ejemplo people.

{
    "success": true,
    "data": {
        "key_people": [
            {
                "names": "DANIEL SERVITJE",
                "id_number": "DASJ850405XX1",
                "id_type": "rfc",
                "type": "person",
                "iso_country_code": "MX",
                "birth_date": "1985-04-05",
                "roles": [
                    {
                        "id": "role-1",
                        "role_name": "presidente",
                        "group_name": "executives",
                        "event": "addition",
                        "duration": -1,
                        "powers": [
                            {
                                "power_name": "administration",
                                "has_power": true,
                                "has_limits": false,
                                "signature_type": "joint",
                                "duration": -1,
                                "limits_description": ""
                            }
                        ],
                        "source": {
                            "item_id": 94852,
                            "item_type": "ac_mx",
                            "document_date": "2015-06-15",
                            "entity_name": "ACME MEXICO"
                        }
                    }
                ],
                "identity": {
                    "person_id": {
                        "description": "ine_mx - DASJ850405HSPRVN02",
                        "extra_fields": {
                            "curp": "DASJ850405HSPRVN02",
                            "rfc": "DASJ850405XX1"
                        },
                        "source": {
                            "item_id": 84856,
                            "item_type": "person_id"
                        }
                    }
                },
                "fiscal": {},
                "address": {},
                "ubo_forms": {},
                "external_identities": {
                    "curp": {
                        "search_number": "DASJ850405HSPRVN02",
                        "success": true,
                        "message": null,
                        "applicant_data": {
                            "curp": "DASJ850405HSPRVN02",
                            "names": "DANIEL",
                            "gender": "HOMBRE",
                            "birth_date": "1985-04-05",
                            "birth_entity": "DISTRITO FEDERAL",
                            "nationality": "MEXICO",
                            "first_surname": "SERVITJE",
                            "second_surname": "MONTULL",
                            "evidentiary_document": "Acta de nacimiento"
                        },
                        "evidentiary_document_data": {
                            "act_number": "00452",
                            "registry_date": "1985",
                            "register_entity": "09 DISTRITO FEDERAL",
                            "register_municipality": "016 MIGUEL HIDALGO"
                        },
                        "curp_file": "https://files.gotrebol.com/mx/curps/DASJ850405HSPRVN02_file.pdf?Expires=…&Signature=…"
                    }
                },
                "people_id": 3025,
                "ai_suggested": false,
                "human_reviewed": false
            }
        ],
        "signatory_groups": {
            "executives": [
                {
                    "role_id": "role-1",
                    "names": "DANIEL SERVITJE",
                    "id_number": "DASJ850405XX1",
                    "id_number_rfc": "DASJ850405XX1",
                    "id_type": "rfc",
                    "role_name": "presidente",
                    "event": "addition",
                    "duration": -1,
                    "folio_number": "00452",
                    "folio_date": "2015-06-15",
                    "folio_inscription_date": "2015-06-20",
                    "iso_country_code": "MX",
                    "type": "person",
                    "source": {
                        "item_id": 94852,
                        "item_type": "ac_mx",
                        "document_date": "2015-06-15",
                        "entity_name": "ACME MEXICO"
                    },
                    "identity": {},
                    "fiscal": {},
                    "address": {},
                    "external_identities": {},
                    "ubo_forms": {}
                }
            ]
        },
        "full_list": []
    },
    "meta": {
        "section": "people",
        "verification": {
            "id": "09786e1d-92b7-4503-b84d-d455375be01d",
            "tag": "id-trebol-demo-01",
            "status": "finished"
        }
    }
}

​API KYB: Verificación de Firmantes y Administradores

​Estructura de la Respuesta

​Información de Personas Clave

​1. Datos Personales

​2. Roles y Poderes

​3. Documentación Adicional

​Detalles de Roles y Poderes

​Información del Rol

​Objeto source

​Poderes Legales

​Tipos de Poderes

​Grupos de Roles

​Información de signatory_groups

​Información de Identidad

​Objeto identity.person_id

​Cada item de validations

​Objeto basic_data

​Información de Domicilio

​Información Fiscal

​Identidades externas

​Ejemplo de Respuesta

API KYB: Verificación de Firmantes y Administradores

Estructura de la Respuesta

Información de Personas Clave

1. Datos Personales

2. Roles y Poderes

3. Documentación Adicional

Detalles de Roles y Poderes

Información del Rol

Objeto `source`

Poderes Legales

Tipos de Poderes

Grupos de Roles

Información de `signatory_groups`

Información de Identidad

Objeto `identity.person_id`

Cada item de `validations`

Objeto `basic_data`

Información de Domicilio

Información Fiscal

Identidades externas

Ejemplo de Respuesta