> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fraudeg.com/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /verifications

> Crear una verificación de identidad

```
POST {API_BASE}/v1/verifications
```

`{API_BASE}` es la URL base de tu [entorno](/entornos):
`https://sandbox-api.fraudeg.com/api` o `https://api.fraudeg.com/api`.

Crea una verificación y te devuelve la `url` a la que mandas a la persona. Requiere el
scope `KYC_WRITE`. La API key va en tu servidor, nunca en el navegador. Ver
[Cómo funciona](/identidad/como-funciona).

## Headers

| Header         | Obligatorio        |
| -------------- | ------------------ |
| `X-Api-Key`    | Sí                 |
| `Content-Type` | `application/json` |

No hay `X-Idempotency-Key`. La clave de reintento es tu `customer_ref`: mientras haya una
verificación en curso para esa referencia, una segunda llamada te devuelve **la misma**, no
cobra de nuevo, y te da una `url` para seguir.

## Request

```json theme={null}
{
  "customer_ref": "CUS-48213",
  "language": "es",
  "callback_url": "https://tu-app.example.com/kyc/volver"
}
```

| Campo           | Obligatorio      | Detalle                                                                 |
| --------------- | ---------------- | ----------------------------------------------------------------------- |
| `customer_ref`  | No, pero mándalo | Tu identificador de la persona. Máximo 128 caracteres                   |
| `template_code` | No               | Qué flujo correr. Sin él se usa el que tengas por defecto               |
| `language`      | No               | ISO 639-1, para las pantallas que ve la persona                         |
| `callback_url`  | No               | A dónde vuelve la persona al terminar. `https`, o `http` en `localhost` |

**Manda siempre `customer_ref`.** Sin él se genera uno, y entonces la verificación no se
puede unir a tu propio registro.

## Response

El envelope es `{ data, timestamp, status }`. En una creación exitosa, `status` es
`CREATED`.

```json theme={null}
{
  "data": {
    "id": 4821,
    "customer_ref": "CUS-48213",
    "session_token": "…",
    "url": "https://…",
    "status": "PENDING"
  },
  "timestamp": "2026-09-13T14:02:11",
  "status": "CREATED"
}
```

| Campo           | Qué haces con él                                                                |
| --------------- | ------------------------------------------------------------------------------- |
| `id`            | Lo guardas en tu registro                                                       |
| `customer_ref`  | Tu identificador, o el que se generó si no mandaste uno                         |
| `url`           | Se la das al navegador de la persona, y solo eso                                |
| `session_token` | Credencial. No la registres, no la guardes, no la pongas en una URL compartible |
| `status`        | Al crear, `PENDING`. Ver [Decisiones de identidad](/identidad/decisiones)       |

## Errores

| HTTP  | Cuándo                                                         |
| ----- | -------------------------------------------------------------- |
| `400` | Cuerpo mal formado                                             |
| `401` | Falta la key, o está mal formada, desconocida o revocada       |
| `403` | La key no puede usar esta ruta, o le falta `KYC_WRITE`         |
| `422` | La petición se entendió y se rechazó (validación, no sintaxis) |

El envelope de error es el de plataforma (`error_code`, `message`, `details`). Ver
[Códigos de error](/referencia/codigos-de-error).

Siguiente: [GET /verifications](/referencia/verificacion).