Crear y gestionar enlaces de verificación

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
`metadata`	object	No	Objeto JSON libre para asociar datos de negocio al Link

Ejemplo de petición

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"}
  }'

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);

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

{
  "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. 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

curl -X GET https://api.identity.vu-one.com/api/v1/links \
  -H "Authorization: Bearer <token>"

Devuelve un array de objetos con la misma estructura que GET /links/{id}.

Obtener un Link por ID

curl -X GET https://api.identity.vu-one.com/api/v1/links/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer <token>"

Respuesta

{
  "_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:

curl -X GET https://api.identity.vu-one.com/api/v1/users/me/company \
  -H "Authorization: Bearer <token>"

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.

Primeros Pasos

Conceptos Clave

Referencia

Crear y gestionar enlaces de verificación

Crear un Link

Parámetros del body

Ejemplo de petición

Respuesta

Flujo adaptativo

Compartir el enlace con el usuario

Listar todos los Links

Obtener un Link por ID

Respuesta

Campos de la respuesta

Configuración a nivel de compañía

​Crear un Link

​Parámetros del body

​Ejemplo de petición

​Respuesta

​Flujo adaptativo

​Compartir el enlace con el usuario

​Listar todos los Links

​Obtener un Link por ID

​Respuesta

​Campos de la respuesta

​Configuración a nivel de compañía

Crear un Link

Parámetros del body

Ejemplo de petición

Respuesta

Flujo adaptativo

Compartir el enlace con el usuario

Listar todos los Links

Obtener un Link por ID

Respuesta

Campos de la respuesta

Configuración a nivel de compañía