> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vu-one.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Crear y gestionar enlaces de verificación
> Crea vínculos de verificación de un solo uso para compartir por email, WhatsApp, SMS o QR y monitorea su estado en tiempo real.
Un Link es un enlace de un solo uso que dirige al usuario final al flujo de verificación de VU Identity Link. Cada Link tiene un `linkId` único, una `linkUrl` para compartir y un `verificationId` asociado que te permite rastrear el resultado. Puedes crear Links de tipo FULL FLOW (documento + prueba de vida) o ID ONLY (solo documento).
## Crear un Link
Usa `POST /links` para generar un nuevo enlace de verificación.
### Parámetros del body
| Campo | Tipo | Requerido | Descripción |
| - | - | - | - |
| `type` | string | Sí | Tipo de flujo: `"FULL FLOW"` o `"ID ONLY"` |
| `callbackUrl` | string | No | URL a la que se redirige al usuario tras completar la verificación |
| `externalUserId` | string | No | Identificador externo del usuario. Si lo envías, el usuario no verá el prompt de email |
| `adaptiveFlow` | boolean | No | Permite que este Link omita la captura documental y re-verifique a un cliente conocido solo con selfie. Ver [Flujo adaptativo](#flujo-adaptativo) |
| `metadata` | object | No | Objeto JSON libre para asociar datos de negocio al Link |
### Ejemplo de petición
```bash curl theme={null}
CLIENT_ID="tu_client_id"
CLIENT_SECRET="tu_client_secret"
BASIC_AUTH=$(echo -n "$CLIENT_ID:$CLIENT_SECRET" | base64)
TOKEN=$(curl -s -X POST https://api.identity.vu-one.com/api/v1/oauth/token \
-H "Authorization: Basic $BASIC_AUTH" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials" | jq -r '.access_token')
curl -X POST https://api.identity.vu-one.com/api/v1/links \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"type": "FULL FLOW",
"callbackUrl": "https://tu-app.com/verificacion-completa",
"externalUserId": "usr_12345",
"adaptiveFlow": true,
"metadata": {"campaign": "onboarding_mayo", "channel": "whatsapp"}
}'
```
```javascript JavaScript theme={null}
const response = await fetch('https://api.identity.vu-one.com/api/v1/links', {
method: 'POST',
headers: {
'Authorization': 'Bearer eyJhbGciOiJSUzI1NiIs...',
'Content-Type': 'application/json',
},
body: JSON.stringify({
type: 'FULL FLOW',
callbackUrl: 'https://tu-app.com/verificacion-completa',
externalUserId: 'usr_12345',
adaptiveFlow: true,
metadata: { campaign: 'onboarding_mayo', channel: 'whatsapp' },
}),
});
const link = await response.json();
console.log(link.linkUrl);
```
```python Python theme={null}
import requests
response = requests.post(
"https://api.identity.vu-one.com/api/v1/links",
headers={
"Authorization": "Bearer eyJhbGciOiJSUzI1NiIs...",
"Content-Type": "application/json",
},
json={
"type": "FULL FLOW",
"callbackUrl": "https://tu-app.com/verificacion-completa",
"externalUserId": "usr_12345",
"adaptiveFlow": True,
"metadata": {"campaign": "onboarding_mayo", "channel": "whatsapp"},
},
)
link = response.json()
print(link["linkUrl"])
```
### Respuesta
```json theme={null}
{
"linkId": "550e8400-e29b-41d4-a716-446655440000",
"linkUrl": "https://identity.vu-one.com/v/abc123def456",
"verificationId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
}
```
## Flujo adaptativo
Introducido en la versión 2.2.0, el flujo adaptativo permite que un cliente que ya se verificó anteriormente vuelva a verificarse **solo con una selfie**, sin repetir la captura del documento.
`adaptiveFlow` es un campo de tres estados en `POST /links`:
| Valor enviado | Comportamiento |
| - | - |
| Omitido | Se aplica la configuración de la compañía (`linkConfig.adaptiveFlow`), que está desactivada salvo que la habilites |
| `true` | Este Link puede resolverse como selfie-only aunque la compañía no tenga la opción activada |
| `false` | Este Link ejecuta siempre el flujo documental completo, aunque la compañía tenga la opción activada |
Omitir el campo y enviar `false` **no** son equivalentes. `false` es una anulación explícita que garantiza el flujo documental completo.
`adaptiveFlow` requiere `externalUserId` para tener efecto. Sin ese identificador no hay forma de localizar la verificación previa del cliente, y el Link ejecuta silenciosamente el flujo completo.
Si no conoces el `externalUserId` al crear el Link, el usuario puede aportarlo durante el flujo mediante el endpoint público `PATCH /verifications/identify`. Consulta [Identificar a un usuario en curso](/identity-link/kyc#identificar-a-un-usuario-en-curso).
La rama efectivamente resuelta para una verificación se expone como `method` en `GET /verifications/{id}/status?include=operationGuid`, con valores `FACE` (rama adaptativa) o `DOCUMENT` (flujo completo).
## Compartir el enlace con el usuario
Una vez creado el Link, distribuye `linkUrl` por el canal que prefieras:
* **Email**: incluye el enlace en un correo de onboarding.
* **WhatsApp/SMS**: envía un mensaje corto con el link.
* **QR**: genera un código QR apuntando a `linkUrl` para lectura en persona.
## Listar todos los Links
```bash theme={null}
curl -X GET https://api.identity.vu-one.com/api/v1/links \
-H "Authorization: Bearer "
```
Devuelve un array de objetos con la misma estructura que `GET /links/{id}`.
## Obtener un Link por ID
```bash theme={null}
curl -X GET https://api.identity.vu-one.com/api/v1/links/550e8400-e29b-41d4-a716-446655440000 \
-H "Authorization: Bearer "
```
### Respuesta
```json theme={null}
{
"_id": "550e8400-e29b-41d4-a716-446655440000",
"verificationId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
"active": true,
"expiresAt": "2026-08-23T14:00:00Z",
"createdAt": "2026-08-22T14:00:00Z",
"callbackUrl": "https://tu-app.com/verificacion-completa",
"externalUserId": "usr_12345",
"metadata": { "campaign": "onboarding_mayo" },
"defaultTemplateVersion": "2026-07-01",
"adaptiveFlow": true,
"company": {
"name": "Mi Empresa",
"antiSpoofing": true,
"color": "#ff4e08",
"plan": "PRO",
"handoffMode": "suggest",
"gateRules": {
"version": "2026-07-01",
"rules": [
{
"id": "ios-legacy",
"reason": "unsupported_os",
"match": { "formFactor": "mobile", "platform": "ios", "osVersionMax": "14" }
}
]
},
"locationPermission": "optional"
}
}
```
### Campos de la respuesta
| Campo | Tipo | Descripción |
| - | - | - |
| `_id` | uuid | Identificador del Link |
| `verificationId` | uuid | Verificación asociada |
| `active` | boolean | Si el Link sigue siendo utilizable |
| `expiresAt` | date-time | Momento de expiración |
| `createdAt` | date-time | Momento de creación |
| `callbackUrl` | string | URL de redirección configurada |
| `externalUserId` | string | Identificador externo del usuario |
| `metadata` | object | Metadatos que enviaste al crear el Link |
| `defaultTemplateVersion` | string, nullable | Versión de la plantilla global de reglas de gateo activa. Es estado global, idéntico para todas las compañías. `null` si no hay plantilla activa |
| `adaptiveFlow` | boolean | Rama **ya resuelta** para este Link (`link.adaptiveFlow` si se envió, o la configuración de la compañía). Nunca el valor de tres estados que acepta `POST /links` |
| `company.name` | string | Nombre de la compañía |
| `company.antiSpoofing` | boolean | Si los controles anti-spoofing están activos |
| `company.color` | string | Color de marca |
| `company.plan` | string | Plan contratado |
| `company.handoffMode` | string | Si la compañía ofrece el traspaso de dispositivo y con qué insistencia: `never`, `suggest` o `require`. Por defecto `never` |
| `company.gateRules` | object | Conjunto de reglas resuelto y de solo lectura que decide qué dispositivos quedan gateados. Lo gestiona VU y nunca se acepta en un `PATCH` |
| `company.locationPermission` | string | Política efectiva de permiso de ubicación: `never`, `optional` o `required`. Siempre resuelta en el servidor |
`gateRules` es de solo lectura. Cada regla incluye `id`, `reason` y un bloque `match` con `formFactor`, `platform` y `osVersionMax`.
## Configuración a nivel de compañía
Dos ajustes de compañía afectan directamente a los Links que crees:
| Campo | Por defecto | Descripción |
| - | - | - |
| `linkConfig.expirationTime` | 1 | Validez del Link |
| `linkConfig.adaptiveFlow` | `false` | Si los Links pueden resolverse como selfie-only cuando el Link no lo anula explícitamente |
Consulta tu configuración actual con:
```bash theme={null}
curl -X GET https://api.identity.vu-one.com/api/v1/users/me/company \
-H "Authorization: Bearer "
```
Para modificarlos, usa `PATCH /users/me/company` enviando los nuevos valores dentro de `linkConfig`.
Si envías `externalUserId` al crear el Link, el usuario salta el paso de ingresar su email dentro del flujo de verificación. Esto mejora la conversión en integraciones donde ya conoces la identidad del usuario, y es además el requisito para que `adaptiveFlow` funcione.
Cada `linkUrl` es de un solo uso. Si el usuario abandona el flujo y vuelve a intentarlo, deberás crear un nuevo Link.
## Related topics
- [Inicio rápido: tu primera verificación de identidad](/quickstart.md)
- [Documentación técnica de VU](/index.md)
- [Planes de Identity Link](/identity-link/planes.md)
- [Identity Link API: guía de integración completa](/identity-link/introduccion.md)
- [Webhooks de Identity Link: eventos del ciclo de verificación](/identity-link/webhooks.md)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.