Crear sesión de verificación (V3)

La versión 3 crea la sesión sobre la nueva plataforma de verificación de Verificamex, con una respuesta más simple y opciones de personalización de marca.

Realiza las mismas validaciones que la versión 2: extracción de datos por OCR y MRZ, prueba de vida y comparación facial, y consulta a RENAPO y a la Lista Nominal del INE.

¿Cuál versión debo usar?

La V2 sigue operando y no está descontinuada. Usa la V3 si necesitas personalizar la interfaz con los colores y el logo de tu marca, si quieres incluir la prueba de vida como validación independiente, o si prefieres recibir los archivos como enlaces de descarga en lugar de Base64. Si ya integraste la V2, revisa las diferencias antes de migrar.

Método: POST

Endpoint

https://api.verificamex.com/identity/v3/identity/sessions

Nota

Recuerda que debes tener un token válido para realizar la solicitud. Puedes obtener un token siguiendo los pasos descritos en la sección Generar tokens.

Encabezados de la Solicitud

Encabezado	Valor	Descripción
Accept	application/json	Tipo de contenido de la solicitud.
Content-Type	application/json	Formato del cuerpo de la solicitud.
Authorization	Bearer {tu_token}	Token generado para autenticar al usuario.

Cuerpo de la Solicitud

Todos los parámetros son opcionales. Puedes crear una sesión enviando un cuerpo vacío y se aplicarán los valores por defecto.

Parámetro	Tipo	Descripción
validations	Array Opcional	Validaciones a realizar. Valores permitidos: "INE", "CURP", "LIVENESS_DETECTION". Si se omite, se aplica ["INE", "CURP"].
redirect_url	String Opcional	URL a la que se redirigirá al usuario una vez finalizada la verificación.
webhook	String Opcional	URL a la que se enviará una petición POST cada vez que la sesión cambie de estado.
with_webhook_files	Boolean Opcional	Indica si la notificación del webhook debe incluir los archivos de la verificación (como URL firmada, nunca en Base64). Por defecto true. Ver Webhooks.
only_mobile_devices	Boolean Opcional	Indica si la verificación sólo puede realizarse en dispositivos móviles. Por defecto false.
qr_validation	Boolean Opcional Solo V3	Activa la lectura y validación de los códigos QR del reverso de la credencial. Por defecto false. Tiene un costo adicional. Ver Validación de QR.
capture_user_location	Boolean Opcional Solo V3	Pide la ubicación del dispositivo antes de abrir la cámara. Por defecto false. Tiene un costo adicional, solo si se obtiene la ubicación. Ver Ubicación del usuario.
political_affiliation	Boolean Opcional Solo V3	Al terminar la sesión, consulta en el INE si la persona está afiliada a un partido político. Por defecto false. Tiene un costo adicional, solo si el INE responde. Ver Afiliación a partidos políticos.
face_match_threshold	Number Opcional Solo V3	Similitud mínima (%) entre el rostro de la credencial y la selfie para aprobar la comparación facial. De 70 a 100. Por defecto 90. Ver Umbrales de biometría.
liveness_threshold	Number Opcional Solo V3	Confianza mínima (%) de la prueba de vida: aprueba si la confianza es mayor que este valor. De 50 a menos de 100. Por defecto 80.
qr_face_match_threshold	Number Opcional Solo V3	Similitud mínima (%) entre la fotografía del QR y el rostro de la credencial. Solo aplica con qr_validation: true. De 70 a 100. Por defecto 80.
phone_number	String Opcional	Número de teléfono para enviar la sesión por WhatsApp, en formato nacional de 10 dígitos.
optionals	Object Opcional	Objeto para guardar información relevante para tu sistema que no es necesaria para la validación. Se devuelve tal cual en el webhook y en el detalle.
custom_branding	Object Opcional	Objeto para personalizar la interfaz de verificación con tu marca.
custom_branding.primary_color	String Opcional	Color primario en formato hexadecimal.
custom_branding.secondary_color	String Opcional	Color secundario en formato hexadecimal.
custom_branding.logo	String Opcional	URL del logo, o el archivo como Data URI en Base64.

Ejemplo de Solicitud

JSON

{
    "validations": ["INE", "CURP"],
    "redirect_url": "https://tusitio.com/finalizado",
    "webhook": "https://tu-api.com/webhooks/verificamex",
    "with_webhook_files": false,
    "only_mobile_devices": true,
    "phone_number": "5512345678",
    "face_match_threshold": 92,
    "optionals": {
        "id_cliente": "A-10293"
    },
    "custom_branding": {
        "primary_color": "#F54927",
        "secondary_color": "#8C2511",
        "logo": "https://tusitio.com/logo.png"
    }
}

cURL

curl -X POST https://api.verificamex.com/identity/v3/identity/sessions \
  -H "Authorization: Bearer {TU_TOKEN}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "validations": ["INE", "CURP"],
    "redirect_url": "https://tusitio.com/finalizado",
    "webhook": "https://tu-api.com/webhooks/verificamex",
    "custom_branding": {
      "primary_color": "#F54927",
      "secondary_color": "#8C2511",
      "logo": "https://tusitio.com/logo.png"
    }
  }'

Mínimo

{}

Respuesta del Endpoint

status 201

    {
        "uuid": "870c7eee-3604-4995-aa98-bc8fa6aa1112",
        "status": "OPEN",
        "created_at": "2026-07-21T22:40:55+00:00",
        "updated_at": "2026-07-21T22:40:55+00:00",
        "verification_url": "https://kyc.verificamex.com/verify/870c7eee-3604-4995-aa98-bc8fa6aa1112?t=...",
        "webhook": "https://tu-api.com/webhooks/verificamex",
        "with_webhook_files": false,
        "qr_validation": false,
        "validacion_qr": false,
        "capture_user_location": false,
        "political_affiliation": false,
        "custom_branding": {
            "primary_color": "#F54927",
            "secondary_color": "#8C2511",
            "logo": "https://tusitio.com/logo.png"
        },
        "redirect_url": "https://tusitio.com/finalizado",
        "liveness_threshold": 80,
        "face_match_threshold": 92,
        "qr_face_match_threshold": 80,
        "result": null
    }

status 422

    {
        "message": "face_match_threshold debe ser de al menos 70.",
        "errors": {
            "face_match_threshold": ["face_match_threshold debe ser de al menos 70."]
        }
    }

status 401

    {
        "message": "Unauthorized"
    }

status 403

    {
        "message": "Las transacciones del usuario se han terminado"
    }

La respuesta no viene envuelta

A diferencia de la V2, la respuesta de este endpoint es un objeto plano: no incluye las llaves data ni meta. Si estás migrando desde la V2, tu código debe leer uuid en la raíz y no en data.id. Ten en cuenta que el detalle sí viene envuelto.

El cuerpo de la respuesta contiene los siguientes parámetros:

Parámetro	Tipo	Descripción
uuid	String	Identificador único de la sesión. Es el que debes guardar para consultarla después.
status	String	Estado de la sesión. Al crearla siempre es OPEN.
created_at	String	Fecha de creación en formato ISO-8601.
updated_at	String	Fecha de la última actualización en formato ISO-8601.
verification_url	String	URL a la que debes enviar al usuario para que realice la verificación.
webhook	String	URL de notificación configurada, o null si no se envió.
with_webhook_files	Boolean	Confirma si el webhook incluirá los archivos de la verificación.
qr_validation	Boolean	Confirma si la sesión pedirá la validación de QR. Igual a validacion_qr (alias retrocompatible del mismo parámetro).
capture_user_location	Boolean	Confirma si la sesión pedirá la ubicación del usuario.
political_affiliation	Boolean	Confirma si al terminar la sesión se consultará la afiliación a partidos políticos.
custom_branding	Object	Personalización de marca aplicada, o null si no se envió.
redirect_url	String	URL de redirección configurada, o null si no se envió.
liveness_threshold	Number	Umbral de la prueba de vida que se aplicará a la sesión: el que enviaste o el valor por defecto.
face_match_threshold	Number	Umbral de comparación facial que se aplicará a la sesión: el que enviaste o 90.
qr_face_match_threshold	Number	Umbral de la fotografía del QR que se aplicará si la sesión pide qr_validation: el que enviaste o el valor por defecto.
result	Integer	Resultado de la verificación. Siempre null al crear la sesión.

Consejo

Guarda el uuid: es el identificador con el que consultarás la sesión y el que llegará en la notificación del webhook. La verification_url es el enlace que debes abrir o compartir con el usuario final.

---

Estados de la sesión

1. OPEN — La sesión fue creada y espera a que el usuario complete el proceso en la verification_url.
2. VERIFYING — El usuario terminó de capturar sus documentos y se están ejecutando las consultas a Lista Nominal y RENAPO.
3. FINISHED — El proceso concluyó. El campo result indica si la verificación fue exitosa.

Si el proceso no puede completarse, la sesión pasa a FAILED y result queda en 0.

---

Diferencias con la V2

Aspecto	V2	V3
Código de respuesta	200	201
Formato de la respuesta	Envuelta en data y meta	Objeto plano
Identificador de la sesión	data.id	uuid
URL de verificación	data.form_url	verification_url
validations	Requerido	Opcional, por defecto ["INE", "CURP"]
redirect_url	Requerido	Opcional
Prueba de vida como validación	No disponible	"LIVENESS_DETECTION"
Umbrales de biometría	No configurables	face_match_threshold, liveness_threshold y qr_face_match_threshold
Ubicación del usuario	No disponible	capture_user_location
Afiliación a partidos políticos	No disponible	political_affiliation
Personalización	customization (5 colores) y logo	custom_branding (2 colores y logo)
Archivos en el detalle	Base64 y URL firmada	Sólo URL firmada
Creación, consulta y listado	Endpoints V2	Creación en V3, consulta y listado en V2