> ## 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.

# Tu primera verificación

> Un curl contra la API de tu entorno, la respuesta y qué hacer con cada campo

Con tu API key creada en el [entorno](/entornos) que te corresponde, esta es la única
llamada que necesitas para empezar. El ejemplo usa pre-official-integration
(`sandbox-api.fraudeg.com`). En producción cambia el host a `https://api.fraudeg.com/api`;
el path es el mismo. No existe `/verifications/sandbox`.

## Request

```bash theme={null}
curl -X POST https://sandbox-api.fraudeg.com/api/v1/verifications \
  -H "X-Api-Key: tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "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` |

La llamada requiere el scope `KYC_WRITE`.

**Manda siempre `customer_ref`.** Sin él generamos uno, y entonces la verificación no se puede
unir a tu propio registro. Además es lo que hace barato reintentar: 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 donde la persona iba.

## Respuesta

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

Con esta respuesta haces exactamente dos cosas:

1. **Guardas `id`** en tu registro.
2. **Mandas a la persona a `url`**, o se la entregas a tu página para que la abra.

**`session_token` es una credencial.** No lo registres en logs, no lo guardes y no lo pongas en
una URL que la persona pueda compartir. Si tu framework serializa respuestas enteras a los logs,
excluye esta.

## Mientras la persona se verifica

No necesitas preguntar nada: la decisión llega a tu backend por
[webhook](/identidad/webhooks). Si quieres consultar el estado igualmente —para una pantalla
interna, o para reconciliar— usa:

```bash theme={null}
curl https://sandbox-api.fraudeg.com/api/v1/verifications/4821 \
  -H "X-Api-Key: tu_api_key"
```

Esa lectura requiere el scope `KYC_READ`. Una key con solo ese scope no puede crear nada, que es
lo que conviene darle a un proceso que únicamente reconcilia.

## Probando desde tu máquina

Las dos URLs que nos das las alcanzan cosas distintas, y solo una necesita un túnel.

|                        | Quién hace la petición         | En localhost                                                                 |
| ---------------------- | ------------------------------ | ---------------------------------------------------------------------------- |
| `callback_url`         | El navegador **de la persona** | Funciona. `http://localhost:3000/kyc/volver` se acepta en todos los entornos |
| Tu endpoint de webhook | **Nuestros servidores**        | No te alcanzan. Usa un túnel y registra la URL `https` que te dé             |

## Siguiente paso

[Decisiones de identidad](/identidad/decisiones): qué significa cada estado y qué hacer con él.