/v1/ine/sessions
Crea una sesión de verificación y recibe una liga. La persona la abre en su teléfono y nuestra página la guía para fotografiar su credencial para votar y grabar un video corto de su rostro. Recibes un solo resultado: los datos de la credencial, sus verificaciones y si la persona es real y es la titular.
Es /v1/ine/card más una prueba de vida y comparación de rostro, con la captura alojada por nosotros: sin aplicación que instalar, sin código de cámara que escribir y sin nada que tengas que subir. Una sesión cuesta 30 créditos.
Cómo funciona
- Creas una sesión con este endpoint y recibes su url. Envíala a la persona por SMS, WhatsApp o correo, muéstrala como código QR, o ábrela en un web view o con un redireccionamiento.
- La persona abre la liga en Safari o Chrome en su teléfono y permite el uso de la cámara. La página solo funciona en un teléfono o tableta: abierta en una computadora, muestra el código QR de la liga y le pide a la persona continuar en su teléfono, a menos que hayas enviado allow_desktop. Toma una foto del frente de la credencial y luego del reverso. Cada foto se revisa en el momento y se repite si no se puede leer.
- Graba un video corto de su rostro dentro de un círculo, como cuando un teléfono configura el desbloqueo facial: la página pide un giro de cabeza, un anillo alrededor del rostro se llena conforme gira y la siguiente instrucción llega cuando el giro ya se vio. Los giros son un reto aleatorio nuevo en cada grabación, y la persona tiene hasta tres grabaciones.
- La grabación termina con unos cinco segundos sin moverse. La página le pide a la cámara un acercamiento breve, donde la cámara puede hacerlo, y luego ilumina la pantalla en cuatro colores, en un orden aleatorio elegido para esa grabación y a menos de tres cambios por segundo. Ambos se buscan después en el video; consulta las verificaciones de captura más abajo.
- El resultado se envía a tu webhook y se puede leer con GET durante 15 minutos. La página muestra una pantalla de cierre, con un botón Continuar hacia tu redirect_url si diste una.
Todo se captura con la cámara en vivo. No se puede elegir nada de la galería del teléfono, así que no es posible enviar una foto guardada de la credencial de otra persona ni un video grabado con anticipación.
Cuerpo de la solicitud
JSON. Todos los campos son opcionales; un cuerpo vacío crea una sesión con los valores predeterminados.
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
verify |
boolean | No | Envía true para consultar también al INE sobre la credencial, como lo hace /v1/ine/verify. Suma 10 créditos y 4 a 15 segundos al final. |
verify_curp |
boolean | No | Envía true para consultar también a RENAPO sobre la CURP de la credencial, como lo hace /v1/curp/lookup. Suma 5 créditos y unos 2 segundos. |
allow_desktop |
boolean | No | Envía true para que la página también funcione con la cámara de una computadora. Por defecto solo funciona en un teléfono o tableta, y en una computadora se muestra el código QR de la liga para continuar en un teléfono. |
webhook_url |
string | Recomendado | A dónde se envía el resultado cuando la persona termina. Debe ser una dirección http o https pública. |
redirect_url |
string | No | A dónde lleva a la persona el botón Continuar de la pantalla de cierre. Se agrega session_id a su cadena de consulta. |
reference |
string | No | Tu propia etiqueta para la sesión, de hasta 200 bytes: un id de pedido o de usuario. Regresa en la sesión. No pongas datos personales en ella; es lo único de la sesión que conservamos tal como lo enviaste. |
locale |
string | No | El idioma de la página alojada: es_MX (el predeterminado; es también funciona) o en. |
expires_in |
integer | No | Cuánto tiempo funciona la liga, en segundos: de 60 a 259200 (tres días). El valor predeterminado es 3600, una hora. |
Solicitud de ejemplo
curl -X POST https://inecheck.com/v1/ine/sessions \
-H "x-api-key: rfc_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"verify": true,
"webhook_url": "https://example.com/webhooks/ine",
"redirect_url": "https://example.com/onboarding/done",
"reference": "order-42"
}'
Respuesta (201)
{
"id": "ines_H_n67vkCEhvcEfPZ",
"status": "pending",
"reference": "order-42",
"expires_at": "2026-11-12T05:39:01Z",
"completed_at": null,
"result": null,
"url": "https://inecheck.com/verify/2bRlbq2oaymofQ8RmtcJ63OsJrq1szdzp35JyzxDivM",
"qr_url": "https://inecheck.com/verify/2bRlbq2oaymofQ8RmtcJ63OsJrq1szdzp35JyzxDivM/qr.svg"
}
url es la liga para la persona. Solo se devuelve aquí, así que guárdala si necesitas enviarla de nuevo. Quien tenga la liga puede completar la sesión: envíala a la persona a la que va dirigida.
qr_url es la misma liga como código QR, una imagen SVG que puedes poner directamente en una etiqueta img. Muéstrala cuando la persona empiece en una computadora, para que la escanee y continúe en su teléfono. La página alojada muestra el mismo código por sí sola cuando se abre en una pantalla ancha.
El resultado
Cuando la persona termina, el estatus de la sesión pasa a completed y result trae cuatro cosas. El ejemplo usa datos tipo espécimen, basados en la credencial espécimen publicada por el INE.
{
"verified": true,
"card": {
"read": true,
"source": "photo",
"consistent": true,
"message": "The credential was read and its data agrees.",
"credential": {
"nombre": "GOMEZ VELAZQUEZ MARGARITA",
"clave_elector": "GMVLMR80070501M100",
"curp": "GOVM800705MDFMLR06",
"cic": "183657717",
"id_ciudadano": "011111110"
},
"checks": {
"name_matches_back": true,
"mrz_check_digits": true,
"registered_with_ine": true,
"ine_record_matches_card": true
},
"ine": {"cic": "183657717", "found": true, "status": "vigente"}
},
"liveness": {
"live": true,
"match": true,
"liveness_score": 0.997,
"similarity": 0.612,
"continuous": true,
"challenge": {
"actions": ["left", "right", "left"],
"observed": ["left", "right", "left"],
"passed": true
},
"message": "A live person who matches the credential photo."
},
"capture": {
"on_phone": true,
"camera_genuine": true,
"flash_followed": true,
"camera_responded": true
}
}
-
verified: la respuesta en una línea. true cuando card.consistent es true (lo que incluye las verificaciones del INE y RENAPO que pediste), liveness.live es true, liveness.match es true y ninguna de las verificaciones de captura camera_genuine, flash_followed y camera_responded es false. false en cualquier otro caso. -
card: la respuesta completa de /v1/ine/card, abreviada en el ejemplo: todos los campos de la credencial, todas las verificaciones y las respuestas ine y renapo. -
liveness: las revisiones de la última grabación de la persona, con message diciendo en una línea lo que encontraron:-
live: true cuando el rostro parece una persona y no una foto o una pantalla, el video muestra a una sola persona todo el tiempo, no está armado con clips unidos, y el reto, si se envió, se cumplió. message indica cuál de estos falló. -
match: true cuando el rostro del video es el de la credencial. Se reporta aunque live sea false. -
liveness_score: De 0 a 1, la mediana de los cuadros en los que la persona mira a la cámara. live necesita 0.5 o más. Exige una puntuación más alta si prefieres rechazar a más personas reales antes que dejar pasar una suplantación. -
similarity: De -1 a 1. match necesita 0.363 o más. El retrato de una credencial es pequeño y suele tener años, así que las coincidencias reales quedan más abajo que entre dos selfies de la misma persona. -
continuous: true, false o null. false cuando la imagen salta de un cuadro al siguiente como lo hacen dos clips separados unidos: el fondo se desplaza de un solo paso, o la cabeza aparece de pronto en otro lugar. Hace que live sea false. null cuando el video es demasiado corto para saberlo. -
challenge: los giros de cabeza que pidió la página (actions), los giros vistos en el video (observed) y si son los mismos, en el mismo orden (passed).
-
-
capture: cuatro verificaciones sobre cómo se capturó esa grabación, descritas más abajo.
verified: false no es un veredicto de fraude. Una persona que no logró hacer los giros de cabeza en tres grabaciones, una credencial desgastada cuyos datos se leyeron mal, un rostro en un entorno muy iluminado al que no llegaron los colores de la pantalla, o que el INE no esté disponible dan false. Revisa card.checks, liveness y capture para ver cuál fue, y decide si envías una nueva liga.
Las verificaciones de captura
capture trata del video en sí: ¿lo grabó una cámara frente a esta pantalla, o se le entregó a la página en su lugar, como hace una cámara virtual que reproduce una grabación? Cada verificación es true, false o null cuando no se pudo hacer. Una grabación que falla alguna se repite igual que una que falla los giros de cabeza, hasta tres grabaciones en total; la última es la que cuenta.
| Consulta | true cuando |
|---|---|
on_phone |
el navegador reporta un teléfono o tableta. Solo informativo: no afecta a verified, y es false en una sesión que creaste con allow_desktop y que se hizo en una computadora. |
camera_genuine |
el nombre de la cámara no es el de un programa conocido de cámara virtual, y el navegador no está siendo controlado por automatización. null cuando la cámara no reporta nombre. |
flash_followed |
el rostro en el video tomó los colores que mostró la pantalla, en el orden que el servidor eligió para esa grabación. Un video que no fue iluminado por esta pantalla no sigue una secuencia inventada un momento antes. |
camera_responded |
la imagen creció cuando se le pidió a la cámara un acercamiento. null en una cámara que no puede acercar desde una página web, como la de un iPhone en Safari; en ese caso no hay nada que pedirle. |
Cómo recibir el resultado
Por webhook
Si la sesión tiene webhook_url, la sesión con su resultado se envía ahí una sola vez, cuando la persona termina, en el mismo sobre que los demás webhooks:
{
"status": 200,
"body": {
"id": "ines_H_n67vkCEhvcEfPZ",
"status": "completed",
"reference": "order-42",
"expires_at": "2026-11-12T05:39:01Z",
"completed_at": "2026-11-12T04:52:17Z",
"result": {"verified": true, "card": {}, "liveness": {}, "capture": {}}
}
}
Responde con un 2xx. La entrega no se reintenta; consulta Webhooks para conocer las direcciones que se aceptan. El webhook es la entrega duradera: el resultado no se guarda de nuestro lado.
El webhook va firmado. Revisa su firma antes de dar a una persona por verificada; si no, cualquiera que conozca la URL de tu webhook podría enviar un resultado inventado. Verifica la firma
Consultando la sesión
/v1/ine/sessions/:id
curl https://inecheck.com/v1/ine/sessions/ines_H_n67vkCEhvcEfPZ \
-H "x-api-key: rfc_your_api_key"
Gratis. Devuelve el mismo objeto de sesión. result viene lleno durante 15 minutos después de que la persona termina, mientras se mantiene en memoria; después siguen llegando el estatus y las fechas, con result: null. Úsalo para consultar mientras la persona está en la página, o cuando el redireccionamiento la regrese con session_id.
Estatus
-
pending: la liga aún no se ha completado. Puede que la persona no la haya abierto, o que esté en la página. -
completed: la persona terminó y se generó el resultado. Una sesión se completa una sola vez; la liga deja de funcionar. -
expired: pasó expires_at sin que la sesión se completara. Sus créditos se reembolsaron. Crea una sesión nueva para intentarlo otra vez.
Precios
30 créditos: una lectura de credencial y una prueba de vida. verify suma 10 y verify_curp suma 5. La sesión se cobra al crearla y se reembolsa completa si vence sin completarse, así que una liga que nadie abre no cuesta nada.
A diferencia de /v1/ine/card, los créditos de verify y verify_curp son parte del precio de la sesión, hayan respondido o no el INE o RENAPO. Si no se pudo consultar un registro, card.ine.found o card.renapo.found es null y las verificaciones correspondientes son null.
Qué puede decirte y qué no
La cámara en vivo y los giros de cabeza aleatorios detienen los ataques comunes: una foto de una credencial que la persona no tiene en las manos, una foto impresa o una pantalla frente a la cámara, un video grabado antes. Los datos de la credencial se verifican contra sí mismos y, cuando lo pides, contra el INE y RENAPO.
Las verificaciones de captura apuntan al video que se le entrega a la página en lugar de una cámara, como una cámara virtual que reproduce una grabación: ese video no recibió la petición de acercamiento ni fue iluminado por esta pantalla. liveness.continuous añade una verificación de que el video es una sola grabación y no clips separados unidos; ve un corte seco, no clips fundidos entre sí a lo largo de varios cuadros.
Estas verificaciones corren en el navegador de la otra persona, donde un atacante decidido controla lo que se reporta, así que elevan el costo de un ataque; no prueban nada. La verificación de destellos necesita que la pantalla sea una luz notoria sobre el rostro: un entorno muy iluminado puede hacerla fallar, y la página pide entonces otra grabación. Su umbral es provisional, fijado con video simulado y aún por confirmar en distintos teléfonos. Un rostro sustituido en vivo y reiluminado correctamente no se detecta.
No es un producto certificado de detección de ataques de presentación ni de inyección, y una foto no puede probar que el plástico sea auténtico: los hologramas y las tintas de seguridad requieren tener la credencial en la mano. Úsalo junto con tus propios controles de riesgo.
Privacidad
Las fotos y el video se procesan en memoria en nuestros propios servidores mientras la persona está en la página y no se guardan; ningún tercero los recibe. Con verify, solo el CIC y el identificador ciudadano se envían al INE; con verify_curp, solo la CURP se envía a RENAPO. Conservamos las opciones, el estatus y las fechas de la sesión, y tu referencia. Obtener el consentimiento de la persona para procesar su credencial y su imagen es tu responsabilidad, antes de enviarle la liga.
Límites
- La página necesita un navegador de teléfono o tableta con acceso a la cámara: Safari en iOS, Chrome en Android. Una computadora solo se admite con allow_desktop. Los navegadores dentro de otras aplicaciones (una liga abierta dentro de un chat o una red social) pueden bloquear la cámara; la página le indica a la persona que abra la liga en Safari o Chrome.
- Se leen los modelos de credencial E a J. Si la conexión se cae mientras la persona está en la página, los pasos empiezan de nuevo.
- Las sesiones se crean con una API key en /v1. No están disponibles a través del listado de RapidAPI.
Errores
-
422 invalid_fields: fields indica qué corregir: un webhook_url que no es una dirección pública, un redirect_url que no es http o https, un locale desconocido, un expires_in fuera de rango, un reference demasiado largo, o un indicador verify o allow_desktop que no es booleano. No se cobra. -
404 not_found: en GET, ninguna sesión con ese id pertenece a la cuenta de la API key.