Saltar al contenido principal
GET
/
v1
API de validación de teléfono
curl --request GET \
  --url https://phonevalidation.cleariflow.com/v1
{
  "phone": "14155552671",
  "valid": true,
  "format": {
    "international": "+14155552671",
    "local": "(415) 555-2671"
  },
  "country": {
    "code": "US",
    "name": "United States",
    "prefix": "+1"
  },
  "location": "San Francisco, CA",
  "type": "Landline_or_Mobile",
  "carrier": ""
}
Es muy sencillo de usar: envíe su clave API y un número de teléfono. La API devuelve si el número es estructuralmente válido (según Google libphonenumber) y, cuando es válido, formatos E.164 normalizados más metadatos opcionales como tipo de línea, indicaciones de geocodificación y datos del operador 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 HLR/SMS 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

https://phonevalidation.cleariflow.com/v1/

​
Qué significa valid

validSignificado
trueEl número es estructuralmente válido para su región detectada (libphonenumber IsValidNumber).
falseEl número no pudo analizarse o no cumple las reglas de formato regional. format, country, location, type y carrier siempre están vacíos; phone contiene solo los dígitos de su entrada.
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: 
https://phonevalidation.cleariflow.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& phone = 14155552671
& country = US
Respuesta válida (phone=14155552671, country=US): 
{
  "phone": "14155552671",
  "valid": true,
  "format": {
    "international": "+14155552671",
    "local": "(415) 555-2671"
  },
  "country": {
    "code": "US",
    "name": "United States",
    "prefix": "+1"
  },
  "location": "San Francisco, CA",
  "type": "Landline_or_Mobile",
  "carrier": ""
}
Respuesta no válida (phone=123, country=US): 
{
  "phone": "123",
  "valid": false,
  "format": {
    "international": "",
    "local": ""
  },
  "country": {
    "code": "",
    "name": "",
    "prefix": ""
  },
  "location": "",
  "type": "Unknown",
  "carrier": ""
}

​
Parámetros de solicitud

​
api_key
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.
​
phone
String
requerido
El número de teléfono a validar (comprobación estructural según libphonenumber).
​
country
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.
​
phone
String
Dígitos E.164 normalizados (sin +) cuando valid es true. Cuando valid es false, solo los dígitos de su entrada.
​
valid
Boolean
true cuando el número es estructuralmente válido según libphonenumber. Esto no es verificación de estado de línea ni de abonado.
​
format
Object
Formatos international y local. Cadenas vacías cuando valid es false.
​
format.international
String
Formato E.164 con + inicial. Vacío cuando valid es false.
​
format.local
String
Formato nacional para la región detectada. Vacío cuando valid es false.
​
country
Object
País/territorio detectado. Campos vacíos cuando valid es false.
​
country.code
String
Código de dos letras ISO 3166-1 alpha-2 para la región detectada.
​
country.name
String
Nombre para mostrar en inglés de country.code.
​
country.prefix
String
Prefijo de llamada internacional (p. ej. +1).
​
location
String
Indicación de geocodificación de los metadatos de libphonenumber (región, estado/provincia o ciudad). A menudo vacío fuera de US/CA. Vacío cuando valid es false.
​
type
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.
​
carrier
String
Nombre del operador de los metadatos de libphonenumber cuando esté disponible (más a menudo US/CA). Cadena vacía en caso contrario, incluido 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.
CodeTypeDetails
200OKTodo funcionó como se esperaba.
400Bad requestSolicitud incorrecta.
401UnauthorizedLa solicitud no fue aceptable. Normalmente por clave API ausente o incorrecta.
422Quota reachedLa solicitud se interrumpió por créditos API insuficientes. (Planes gratuitos)
429Too many requestsLa solicitud se interrumpió por alcanzar el límite de solicitudes por segundo. En planes gratuitos las solicitudes están limitadas a 1 por segundo.
500Internal server errorLa solicitud no pudo completarse por un error en el servidor.
503Service unavailableEl servidor no estaba disponible.

​
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.