Skip to main content
GET
API de validación de teléfono
Es muy sencillo: envíe su clave API y un número de teléfono. La API indica si el número es estructuralmente válido y, si es válido, devuelve formatos E.164 normalizados y metadatos opcionales como tipo de línea, geocodificación, operador, zonas horarias y datos de marcación cuando estén disponibles.
valid: true significa que el número cumple las reglas de formato regional (longitud, prefijo, sintaxis). No confirma que la línea esté activa, asignada a un abonado o sea alcanzable. Para el estado de línea en tiempo real necesita carrier lookup, que queda fuera del alcance de esta API.

Primeros pasos

REST

La API de validación de números de teléfono, como todas las API de Cleariflow, está organizada en torno a REST. Está diseñada para usar URL predecibles orientadas a recursos y códigos de estado HTTP para indicar errores.

HTTPS

La API de validación de números de teléfono requiere que todas las comunicaciones estén protegidas con TLS 1.2 o superior.

Versiones de la API

Todas las API de Cleariflow están versionadas. La API de validación de números de teléfono está actualmente en la versión 1.

Su clave API

Su clave API es su clave de autenticación única para la API de validación de números de teléfono de Cleariflow. Tenga en cuenta que cada API de Cleariflow tiene una clave API única, por lo que necesitará claves diferentes para acceder a la validación de teléfono y la validación de correo electrónico, por ejemplo. Para autenticar sus solicitudes, añada su clave API a la URL base.

URL base

Qué significa valid

Los números ficticios 555 de EE. UU. y otros rangos estructuralmente válidos pero no asignados pueden seguir devolviendo valid: true. carrier y location se rellenan principalmente con metadatos de US/CA y a menudo están vacíos en otras regiones.

Endpoint de validación

La API requiere su clave API única y el número de teléfono a comprobar:
Respuesta válida (phone=14155552671, country=US):
Respuesta no válida (phone=123, country=US):

Parámetros de solicitud

String
requerido
Su clave API única. Tenga en cuenta que cada usuario tiene claves API únicas para cada una de las API de Cleariflow, por lo que su clave de Phone Validation no funcionará para su API de geolocalización IP, por ejemplo.
String
requerido
El número de teléfono a validar.
String
Indicación opcional ISO 3166-1 alpha-2 para números en formato nacional sin + inicial. Por ejemplo, country=US ayuda a analizar 4155552671. Los números con prefijo internacional se analizan según su código de país; el country.code detectado en la respuesta puede diferir de esta indicación (p. ej. GG para algunos rangos móviles +44).

Parámetros de respuesta

La respuesta de la API se devuelve en un formato JSON universal y ligero.
String
Dígitos E.164 normalizados (sin +) cuando valid es true. Cuando valid es false, solo los dígitos de su entrada.
Boolean
true cuando el número es estructuralmente válido. Esto no es verificación de estado de línea ni de abonado.
Boolean
Comprobación de longitud permisiva (). true cuando los dígitos y la longitud podrían corresponder a un número real, incluso si valid es false.
String
Presente cuando valid es false. Uno de: not_a_number, possible, possible_local_only, invalid_country_code, too_short, invalid_length, too_long, unknown. Omitido cuando valid es true.
Object
Formatos international y local. Cadenas vacías cuando valid es false.
String
Formato E.164 con + inicial. Vacío cuando valid es false.
String
Formato nacional para la región detectada. Vacío cuando valid es false.
Object
País/territorio detectado. Campos vacíos cuando valid es false.
String
Código de dos letras ISO 3166-1 alpha-2 para la región detectada.
String
Nombre para mostrar en inglés de country.code.
String
String
Indicación de geocodificación (región, estado/provincia o ciudad). A menudo vacío fuera de US/CA. Vacío cuando valid es false.
String
Tipo de línea cuando valid es true: Landline, Mobile, Landline_or_Mobile, Toll_Free, Premium, Paging, Special o Unknown. Siempre Unknown cuando valid es false.
String
Nombre del operador cuando esté disponible (más a menudo US/CA). Cadena vacía en caso contrario, incluido cuando valid es false.
String
Nombre seguro del operador para mostrar al usuario (cuando es válido y la región no usa portabilidad móvil). Vacío si valid es false o el operador no puede mostrarse de forma segura.
Array
Identificadores de zona horaria IANA (p. ej. America/New_York). Array vacío si valid es true sin mapeo; null si valid es false.
Boolean
Si el número está asociado a una región geográfica. Siempre false cuando valid es false.
Boolean
Si el número puede marcarse desde fuera de su región de origen. Siempre false cuando valid es false.

Carga masiva (CSV)

Buenas prácticas al cargar masivamente un archivo CSV:
  • Asegúrese de que la primera columna contenga los números de teléfono a analizar.
  • Elimine las filas vacías del archivo.
  • Incluya solo un número de teléfono por fila.
  • El tamaño máximo permitido del archivo es de 50.000 filas.

Códigos de respuesta y error

Siempre que realice una solicitud que falle por algún motivo, también se devuelve un error en formato JSON. Los errores incluyen un código y una descripción, que puede consultar en detalle a continuación.

Otras notas

Nota sobre facturación por uso: cada número de teléfono individual que envíe cuenta como un crédito utilizado. Los créditos también se cuentan por solicitud, no por respuesta exitosa. Por lo tanto, si envía una solicitud con el número (no válido) «kasj8929hs», eso sigue contando como 1 crédito.