# Crear sesión de verificación (V3)

Fuente: /identity-verification-v3/create-verification-session/

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](/identity-verification/create-verification-session/): 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](#diferencias-con-la-v2) 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](/authentication/generate-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](/identity-verification-v3/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](/identity-verification-v3/qr-validation/). |
| `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](/identity-verification-v3/user-location/). |
| `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](/identity-verification-v3/political-affiliation/). |
| `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](/identity-verification-v3/biometric-thresholds/). |
| `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**

```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**

```bash
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**

```json
{}
```

### Respuesta del Endpoint

**status 201**

```json
    {
        "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**

```json
    {
        "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**

```json
    {
        "message": "Unauthorized"
    }
```

**status 403**

```json
    {
        "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](/identity-verification-v3/show-verification-session/)
> 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 |