Guía rápida

De cero a tu primera verificación en dos llamadas. No hay que crear aplicaciones ni plantillas antes del primer envío.

Antes de empezar

Necesitas una clave de API y un backend desde donde llamar. La clave viaja en cada petición como Authorization: Bearer <clave> y nunca debe llegar al navegador ni a una app móvil.

🚧

Atención

Una clave live_ envía mensajes reales y factura las verificaciones aprobadas. Para probar las llamadas sin enviar nada, usa una clave test_ con los destinatarios del entorno de pruebas: una clave test_ rechaza los números reales.

Tu cuenta ya trae una política por defecto (longitud del código, vigencia, intentos y cascada de canales), así que el primer envío no requiere configurar nada.

📘

Nota

Los mensajes de error de la API (detail y hint) pueden mejorar con el tiempo. Decide con el code numérico, nunca con el texto.

1. Envía el código

Indica el destinatario: un teléfono en formato E.164 o, si el correo está configurado para tu aplicación, una dirección de correo. Opcionalmente, la cascada de canales en orden de preferencia.

📘

Nota

Si WhatsApp todavía no está habilitado para tu aplicación, ese paso se salta al instante y el código sale por el siguiente canal de la cascada, SMS en el ejemplo. Con ["whatsapp"] solo, la verificación termina en failed. No tienes que cambiar nada en tu integración. Detalles en Cascada de canales.

curl https://verify-api.inalambria.com/v1/verifications \
  -H "Authorization: Bearer $VERIFY_API_KEY" \
  -H "Idempotency-Key: signup-8812" \
  --json '{ "to": "+573001234567", "channels": ["whatsapp", "sms"] }'

const response = await fetch('https://verify-api.inalambria.com/v1/verifications', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VERIFY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'signup-8812',
  },
  body: JSON.stringify({ to: '+573001234567', channels: ['whatsapp', 'sms'] }),
});
const verification = await response.json();

verification = requests.post(
    "https://verify-api.inalambria.com/v1/verifications",
    headers={
        "Authorization": f"Bearer {os.environ['VERIFY_API_KEY']}",
        "Idempotency-Key": "signup-8812",
    },
    json={"to": "+573001234567", "channels": ["whatsapp", "sms"]},
).json()

La respuesta llega en cuanto la verificación existe; no espera a que el mensaje se entregue.

{
  "id": "ver_01J9XQ4M7K2VBN3P",
  "status": "pending",
  "to": "+57******4567",
  "channel": "whatsapp",
  "attempts_remaining": 3,
  "expires_at": "2026-09-29T14:37:05.000Z",
  "resend_available_at": "2026-09-29T14:33:05.000Z",
  "created_at": "2026-09-29T14:32:05.000Z"
}

Los enteros opcionales expires_in (60–1800 s), code_length (4–10) y max_attempts (1–10) sobrescriben la política de tu aplicación solo para esta verificación; brand (hasta 64 caracteres) y client_reference (hasta 128) viajan con ella. El detalle está en la referencia.

2. Comprueba el código

Envía lo que escribió tu usuario, con el id del paso anterior.

curl https://verify-api.inalambria.com/v1/verifications/ver_01J9XQ4M7K2VBN3P/check \
  -H "Authorization: Bearer $VERIFY_API_KEY" \
  --json '{ "code": "418302" }'

const response = await fetch(
  `https://verify-api.inalambria.com/v1/verifications/${verification.id}/check`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.VERIFY_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ code: codeFromUser }),
  },
);
const result = await response.json();

result = requests.post(
    f"https://verify-api.inalambria.com/v1/verifications/{verification['id']}/check",
    headers={"Authorization": f"Bearer {os.environ['VERIFY_API_KEY']}"},
    json={"code": code_from_user},
).json()

{
  "id": "ver_01J9XQ4M7K2VBN3P",
  "status": "approved",
  "attempts_remaining": 3,
  "verified_at": "2026-09-29T14:32:41.000Z",
  "channel_used": "whatsapp"
}

verified_at y channel_used solo aparecen cuando la verificación se aprueba.

3. Actúa según el resultado

Un código incorrecto no es un error HTTP: responde 200 y el resultado viaja en status. Los 4xx quedan para peticiones que no se pudieron atender.

Envía code como cadena. Los espacios alrededor y las mayúsculas no importan; los espacios en medio, sí. Envía también una Idempotency-Key en esta llamada: si se pierde la respuesta de un código correcto, reintentar con la misma clave devuelve el approved original; sin ella, el reintento responde 409.

switch (result.status) {
  case 'approved':
    return markPhoneAsVerified(user);
  case 'pending':
    return askAgain({ attemptsLeft: result.attempts_remaining });
  case 'max_attempts_reached':
    return offerNewCode();
}

Reenviar el código

No hay un endpoint de reenvío: volver a crear la verificación es el reenvío. Si ya hay una activa para ese destinatario, recibes la misma con 200, nunca un 409.

• Antes de resend_available_at, no se envía nada nuevo: te devolvemos la verificación en curso.
• Después, se reenvía el mismo código por el canal en curso y el plazo de reenvío vuelve a empezar. expires_at no se mueve. El reenvío vuelve a pasar por los límites, así que puede responder 429 o 403; la verificación en curso queda intacta.
• Por correo, si el envío anterior fue incierto, no se reenvía nada: te devolvemos la verificación en curso. Detalles en Cascada de canales.
• Mientras hay una verificación activa, las opciones de la nueva llamada (channels, expires_in, code_length, max_attempts, brand, client_reference) se ignoran, aunque se siguen validando. Cuando termina, la siguiente llamada crea una verificación nueva con un código nuevo.
• Usa una Idempotency-Key nueva en cada «Reenviar»: la misma clave repite la primera respuesta y no envía nada. Más en Reintentos seguros.

Así un usuario que pulsa «Reenviar» dos veces no dispara dos mensajes ni recibe dos códigos distintos.

Pruébalo

Esta simulación nunca llama a la API. Para ejecutar las llamadas reales con una clave test_, usa la pantalla Sandbox de la consola (mira Entorno de pruebas).

Siguientes pasos

• Entiende los estados de una verificación y cómo se cierra sola.
• Añade reintentos seguros con Idempotency-Key.
• Recibe el resultado en tu backend con webhooks.