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_binaries	Boolean Opcional	Indica si la notificación del webhook debe incluir los archivos de la verificación. Por defecto true.
only_mobile_devices	Boolean Opcional	Indica si la verificación sólo puede realizarse en dispositivos móviles. Por defecto false.
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_binaries": false,
    "only_mobile_devices": true,
    "phone_number": "5512345678",
    "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_binaries": true,
        "custom_branding": {
            "primary_color": "#F54927",
            "secondary_color": "#8C2511",
            "logo": "https://tusitio.com/logo.png"
        },
        "redirect_url": "https://tusitio.com/finalizado",
        "result": null
    }

status 422

    {
        "message": "The given data was invalid.",
        "errors": {
            "validations.0": ["The selected validations.0 is invalid."]
        }
    }

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_binaries	Boolean	Confirma si el webhook incluirá los archivos de la verificación.
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ó.
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"
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