Phone Validation & Intelligence API

Normaliza, valida y enriquece un teléfono en 4 niveles progresivos de capacidad. No son "más validación": son capacidades distintas, con semántica y costo diferentes. El consumidor elige el nivel; se ejecuta el mínimo de operaciones y costo para la capacidad pedida.

• Endpoint: POST /api/v1/utils/phone/validate
• Autenticación: API Key ilk_ — igual que el resto de la API (Autenticación)
• Scopes: utils:phone:validate (LOCAL/VERIFY), utils:phone:mnp (MNP), utils:phone:hlr (HLR)
• Facturación: 1 request del nivel completado (LOCAL/VERIFY no facturan)

POSTProbar la validación de teléfono→

Niveles

Nivel	Capacidad	Externo	Costo
LOCAL	Normalización + validación estructural (E.164, tipo, área)	No	Gratis
CHECKMOBI_VERIFY	Validación externa + metadata de numeración (red de origen)	Sí	Gratis
MNP	Red / carrier actual (portabilidad numérica)	Sí	Pago
HLR	Red actual + original + portabilidad + reachability	Sí	Pago

Un HLR se resuelve en una sola llamada (ya trae carrier actual + original + portabilidad + reachability): nunca se encadenan operaciones pagas redundantes. Si el nivel pedido no puede completarse (número inválido, fijo con fallback, proveedor deshabilitado), completedLevel refleja el nivel real y no se factura por encima de él.

El acceso a los niveles pagos se controla por scope: utils:phone:mnp y utils:phone:hlr son independientes de utils:phone:validate. Ver Autenticación y scopes.

Request

{
  "phone": "011 15-5555-1234",
  "defaultCountry": "AR",
  "validationLevel": "MNP"
}

• phone — teléfono a procesar (puede venir desnormalizado).
• defaultCountry — país ISO alpha-2, usado sólo si el input no trae calling code internacional explícito (+… prevalece).
• validationLevel — LOCAL (default), CHECKMOBI_VERIFY, MNP o HLR.

Response

{
  "requestId": "capi_9f2a7c1e4b0d8a6f",
  "input": { "raw": "011 15-5555-1234", "defaultCountry": "AR" },
  "phone": {
    "e164": "+5491155551234",
    "international": "+54 9 11 5555-1234",
    "national": "011 15-5555-1234",
    "countryCode": "AR",
    "callingCode": "54",
    "nationalNumber": "91155551234",
    "areaCode": "911",
    "type": "MOBILE",
    "flagUrl": "https://<host>/api/v1/utils/phone/flags/AR.svg"
  },
  "validation": {
    "status": "VALID",
    "reason": null,
    "requestedLevel": "MNP",
    "completedLevel": "MNP",
    "possible": true,
    "structurallyValid": true,
    "externallyValidated": true
  },
  "carrier": { "original": null, "current": { "countryIso2": "AR", "mcc": "722", "mnc": "310", "mccmnc": "722310", "networkName": "…" } },
  "portability": { "ported": null },
  "reachability": null,
  "messaging": {
    "whatsapp": { "status": "UNKNOWN" },
    "telegram": { "status": "UNKNOWN" },
    "signal":   { "status": "UNKNOWN" },
    "viber":    { "status": "UNKNOWN" }
  }
}

Presencia en mensajería (messaging)

Para números móviles, la respuesta incluye un bloque messaging con el estado de cuenta por app (WhatsApp, Telegram, Signal, Viber). En números no móviles es null.

Cada app reporta un status:

• UNKNOWN — no se determinó. Es el valor por defecto de hoy: la inteligencia de presencia todavía no está desarrollada, así que todas las apps devuelven UNKNOWN.
• REGISTERED — se detectó una cuenta activa.
• NOT_REGISTERED — se detectó ausencia de cuenta.

messaging no prueba propiedad del teléfono ni identidad del titular. La forma del contrato es estable: cuando se active la detección, sólo cambia el status de cada app.

Semántica (afirmaciones separadas)

Nunca se colapsa todo en un único valid. Cada afirmación es independiente:

• possible — la estructura/longitud podría corresponder a un número válido.
• structurallyValid — cumple las reglas conocidas del plan de numeración.
• externallyValidated — se ejecutó una validación mediante proveedor externo. No implica que el número exista, esté activo, sea de una persona, ni reachability.
• carrier.original — red/origen de numeración cuando puede determinarse.
• carrier.current — red actual determinada por MNP/HLR.
• portability.ported — portabilidad sólo con evidencia (HLR is_ported); si no puede determinarse, es null (nunca se inventa false).
• reachability — resultado específico del lookup HLR; no prueba propiedad del teléfono ni que pueda recibir SMS/llamadas/WhatsApp.
• flagUrl — URL absoluta al SVG de la bandera del país reconocido, servido por la propia API (GET /api/v1/utils/phone/flags/{ISO}.svg), lista para un <img src>. Es null si no se determinó el país.

Estados

status: VALID · INVALID · POSSIBLE · AMBIGUOUS · UNKNOWN · PROVIDER_ERROR. Un error técnico del proveedor es PROVIDER_ERROR (200), nunca INVALID.

Errores

Los mismos de toda la API (ver Errores); acá, qué los dispara:

• 400 — sobre mal formado (falta phone).
• 401 — API Key ausente o inválida.
• 403 — scope insuficiente para el nivel pedido.
• 429 — rate-limit (con retryAfterMs) o cuota diaria.

Un fallo del proveedor externo no es un error de protocolo: devuelve 200 con status: PROVIDER_ERROR y el completedLevel realmente alcanzado (y no factura por encima de él). Ver Límites y facturación.

Playground

Probalo en vivo desde el API Reference + Playground (elegí Phone Validation en el selector de documentos).