Tabla resumen
person_id — Identificación oficial (persona)
Tipos de identificación soportados según el país:
- ine_mx: Identificación oficial mexicana (INE).
- passport: Pasaporte (documento oficial de viaje).
- residence_mx: Tarjeta/documento de residencia en México (para no mexicanos).
- cc: Cédula de ciudadanía colombiana.
Estructura de respuesta
due_date, place_of_issue, sex, national_id_number y curp pueden ser null porque son campos opcionales y su presencia depende del tipo de person_id y de si el documento los incluye explícitamente (por ejemplo, curp solo aplica para documentos mexicanos; place_of_issue aplica para la cédula de ciudadanía colombiana).
Nombre separado en partes
Además del nombre completo ennames, Trébol devuelve el nombre separado en sus partes. Usa estos campos cuando necesites el nombre y los apellidos por separado, en lugar de partir names por tu cuenta.
La separación se basa en las etiquetas del propio documento:
NOMBRE(S) y PRIMER APELLIDO en el INE, APELLIDOS y NOMBRES en la cédula colombiana, Surname y Given names en el pasaporte. El campo names conserva el orden impreso en el documento, que en la mayoría de las identificaciones es apellidos primero. No asumas que las partes siguen ese orden.
Los cuatro campos siempre vienen en item_value: lo opcional es el valor, no su presencia. other_names llega en null cuando la persona tiene un solo nombre de pila, y other_last_names cuando tiene un solo apellido, algo común en documentos extranjeros. Un valor en null significa que esa parte no existe o que Trébol no pudo determinarla con certeza; nunca llega como cadena vacía ni se omite del objeto.
Estos campos usan la misma estructura que el objeto
basic_data de las personas clave. Consulta Objeto basic_data para ver dónde aparece a nivel de persona.person_id procesados antes del 7 de agosto de 2026 devuelven los cuatro campos en null.
Identificadores de la credencial INE
Elitem_value trae los identificadores tal como Trébol los extrae de la credencial: cic, ocr e identificador_ciudadano.
La diferencia con
ine_validation_data es cuándo llegan. Estos tres campos se completan apenas termina la extracción del documento, sin esperar la validación del INE, que consulta el listado nominal y puede demorar. Si lees el item en cuanto la extracción finaliza, es acá donde encuentras estos datos.
ocr e identificador_ciudadano son excluyentes. Los modelos de credencial más antiguos (B, C y D) imprimen “OCR”; los más nuevos (E, F, G y H) imprimen “Identificador del Ciudadano” en su lugar. Cada credencial trae uno de los dos, nunca ambos. Lee los dos campos y usa el que venga con valor.
Los tres campos siempre vienen en item_value: lo opcional es el valor, no su presencia. Llegan en null cuando el documento no es un INE (passport, residence_mx, cc) o cuando ese modelo de credencial no imprime ese dato. Los items procesados antes de este cambio también los devuelven: el dato ya se guardaba durante la extracción, así que no hace falta reprocesar nada.
cic y ocr no son lo mismo que ine_validation_data.data.cic y ine_validation_data.data.numero_ocr. Estos últimos los reporta el INE al validar, y solo existen si la validación terminó bien. Los de item_value salen de la extracción del documento y no dependen de ella. En un item ya validado ves ambos. identificador_ciudadano no tiene equivalente dentro de ine_validation_data: existe solo como campo extraído del documento.Validación del INE
Para un item de tipoperson_id, si su tipo es ine_mx, se realiza una validación del INE. Los datos de esta validación se encuentran dentro de item_value bajo la clave ine_validation_data. El estado de este proceso se puede identificar mediante dos claves: ine_validation_result y ine_validation_message.
Si lo que necesitas son los identificadores impresos en la credencial —el CIC, el OCR o el identificador del ciudadano— no esperes a esta validación: los tienes apenas termina la extracción, en Identificadores de la credencial INE. El identificador del ciudadano, además, solo existe ahí.
Estructura de ine_validation_data:
El objeto ine_validation_data.data contiene la siguiente información extraída del INE:
cic(string): Clave de Identificación Ciudadana (CIC).numero_ocr(string): Número OCR del documento.ano_de_emision(string): Año de emisión del documento.distrito_local(string): Distrito local electoral.ano_de_registro(string): Año de registro del documento.expiration_date(string): Fecha de expiración del documento.clave_de_elector(string): Clave de elector.distrito_federal(string): Distrito federal electoral.numero_de_emision(string): Número de emisión del documento.fecha_de_actualizacion_de_la_informacion(string): Fecha de actualización de la información.
La validación del INE solo se realiza cuando el
id_type del item person_id es ine_mx. Para otros tipos de identificación (como passport, residence_mx o cc), estos campos vendrán en null.Validación de CURP (RENAPO)
Cuando elitem_value del person_id incluye la llave curp con un valor no nulo (típicamente al procesar un ine_mx, un passport mexicano o un residence_mx), Trébol consulta automáticamente RENAPO. La consulta corre de forma asíncrona: el item_value inicial puede devolverse con los cuatro campos (curp_validation_data, curp_validation_result, curp_validation_message y curp_file) en null y Trébol los puebla cuando dispara el webhook verification_people.curp_search_completed. Para acceder a los datos, vuelve a consultar GET /verifications/{verification-id} tras recibir el webhook.
La respuesta usa el mismo conjunto de datos que el ítem dedicado curp_item, con tres diferencias en el item_value del person_id: (1) no incluye curp_validated_at, (2) no incluye curp_validation_status, y (3) curp_file queda al mismo nivel que curp_validation_data dentro de item_value (en curp_item está anidado dentro de curp_validation_data).
Estructura de curp_validation_data:
curp_validation_result — resultado de la consulta:
curp_found: Trébol encontró el CURP en RENAPO. La consulta fue exitosa.curp_not_found: Trébol no encontró el CURP en RENAPO. La consulta corrió sin error, pero el CURP no existe.
curp_validation_message — campo reservado para un mensaje legible asociado al resultado. Actualmente llega siempre en null para el item_value del person_id (a diferencia de curp_item, donde sí se puebla). Existe por consistencia con la convención de ine_validation_message y puede llevar texto descriptivo en el futuro. Para conocer el resultado de la consulta, lee curp_validation_result.
curp_file — URL firmada al PDF descargado de RENAPO con la constancia del CURP. Vive como campo de primer nivel dentro de item_value (no anidado dentro de curp_validation_data). La URL incluye un parámetro Expires=… y caduca; cuando expire, vuelve a consultar GET /verifications/{verification-id} para obtener una URL renovada.
Trébol solo dispara la consulta de RENAPO cuando el
person_id incluye un número CURP. Si el id_type no aporta un CURP (por ejemplo, una cédula colombiana o un pasaporte no mexicano), los cuatro campos llegan en null y nunca llega el webhook curp_search_completed.Si la consulta no corre (por ejemplo, porque no hay CURP en el documento) o si
curp_validation_result es curp_not_found, el objeto curp_validation_data y la URL curp_file pueden llegar en null. Verifica siempre que el objeto y la URL existan antes de leerlos.Ejemplo de salida para cédula de ciudadanía colombiana
Ejemplo de salida para pasaporte
proof_address — Comprobante de domicilio
bank_statement — Estado de cuenta bancario
trust_contract_fideicomiso_extractor — Contrato de fideicomiso
union_documents_extractor — Documentos de unión
financial_statements_any — Estados financieros
Item en fase Beta. La estructura de respuesta detallada se documentará próximamente.