API de Validación y Formateo de Números Telefónicos

La API de Validación de Teléfonos es compatible con 242 países.

La API de Validación y Formateo de Números Telefónicos te permite procesar fácilmente números ingresados por los usuarios en una gran variedad de formatos. Ya sea que el número se ingrese como 1(212)-867-53-09, +1 212 8675309, 001-212.867.5309 o simplemente 2128675309, nuestra API detectará inteligentemente su estructura y devolverá una versión estandarizada.

Esta herramienta convierte automáticamente la entrada proporcionada al formato E.164, que es el formato reconocido globalmente para números telefónicos internacionales. Por ejemplo, +1 212 867 5309 se devuelve como +12128675309, haciéndolo adecuado para sistemas de llamadas internacionales e integraciones.

Más allá del formateo, la API ofrece funciones detalladas de validación de números telefónicos. Verifica si el número es isValid: true, lo que significa que es un número válido según los planes nacionales de numeración. También ofrece una verificación isPossible: true, que indica si un número podría existir potencialmente, incluso si actualmente no está asignado. Esto es útil para validar antes de guardar o procesar datos.

El parámetro numberType ayuda a identificar si el número es móvil, fijo o VoIP. Esto es especialmente útil en casos donde solo se permiten números móviles para verificación por SMS o líneas fijas para contactos de oficina.

Con compatibilidad para el reconocimiento de códigos de área, la API también puede detectar el origen geográfico del número. Por ejemplo, un número que comienza con el código de área 212 se asigna automáticamente a la ciudad de Nueva York (Manhattan). Esta función es perfecta para aplicaciones que requieren segmentación o análisis basado en ubicación.

Cada número también está asociado con metadatos a nivel de país, como el código de región ISO (por ejemplo, US) y el código numérico del país (por ejemplo, 1), lo que permite implementar lógica y formatos regionales en tus aplicaciones.

✅ Respuesta de la API

Ejemplo de respuesta en formato JSON:

{
  "status": true,
  "remaining_credits": 15709,
  "expires": 0,
  "duration": "18ms",
  "regionCode": "US",
  "countryCode": 1,
  "country":"Unites States",
  "national": "(212) 867-5309",
  "international": "+1 212-867-5309",
  "e164": "+12128675309",
  "isValid": true,
  "isPossible": true,
  "numberType": "FIXED_LINE_OR_MOBILE",
  "nationalSignificantNumber": "2128675309",
  "rawInput": "+1 212 867 5309",
  "isGeographical": true,
  "areaCode": "212",
  "location": "New York City (Manhattan)"
}

Prueba la API de Validación de Números

Uso Básico

Envía un número telefónico al siguiente endpoint:

https://api.genderapi.io/api/phone?key=YOUR_API_KEY&number=12128675309

Puedes obtener tu clave API gratuita diaria con 200 créditos desde este enlace.

Parámetro address

La API también admite un parámetro opcional address, que es muy útil en casos donde el número telefónico se proporciona sin el código de país internacional. Este campo ayuda al sistema a detectar la región deseada y analizar correctamente el número. Por ejemplo, si el número ingresado es 2128675309 y no se especifica el código de país, establecer address=US, address=United States o incluso address=New York puede ayudar a la API a determinar que el número pertenece a Estados Unidos.

El parámetro address acepta entrada en varios formatos, incluyendo:

• Códigos ISO 3166-1 alpha-2 como US, DE o TR
• Nombres de países como Alemania, Turquía o América
• Nombres de ciudades o regiones como Berlín, Estambul o Nueva York

Aunque es opcional, el campo address se vuelve obligatorio si el número no comienza con un signo más y un código de marcación internacional (por ejemplo, +1, +44, +90). Sin esta información contextual, la API puede no interpretar correctamente el formato del número nacional.

Ejemplo con el parámetro address:

https://api.genderapi.io/api/phone?key=YOUR_API_KEY&number=12128675309&address=US

Campos de Respuesta

Valores posibles para numberType

curl "https://api.genderapi.io/api/phone?number=+49 151 12345678&address=United States&key=YOUR_API_KEY"

curl "https://api.genderapi.io/api/phone?number=%2B49%20151%2012345678&address=United%20States&key=YOUR_API_KEY"

API de Validación de Números Telefónicos vía Solicitud POST

Puedes usar el método POST para validar un número telefónico en Estados Unidos. Solo proporciona el número en formato E.164, nacional o internacional junto con el país o dirección. Tu clave API debe enviarse como un token Bearer.

Ejemplo con cURL

curl -X POST "https://api.genderapi.io/api/phone" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"number": "+12128675309", "address": "US"}'

Ejemplo con PHP cURL

<?php
$url = "https://api.genderapi.io/api/phone";

$data = array(
    "number" => "+12128675309",
    "address" => "US"
);

$payload = json_encode($data);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    "Content-Type: application/json",
    "Authorization: Bearer YOUR_API_KEY"
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

Ejemplo con fetch en JavaScript

fetch("https://api.genderapi.io/api/phone", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
  },
  body: JSON.stringify({
    number: "+12128675309",
    address: "United States"
  })
})
.then(response => response.json())
.then(data => console.log(data));

Ejemplo con requests en Python

import requests

url = "https://api.genderapi.io/api/phone"

payload = {
    "number": "+12128675309",
    "address": "United States"
}

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
}

response = requests.post(url, headers=headers, json=payload)

print(response.json())

Bibliotecas Cliente

Para facilitar aún más la integración, ofrecemos una variedad de bibliotecas cliente oficiales y soportadas por la comunidad para diferentes lenguajes de programación. Estas bibliotecas te permiten interactuar con los endpoints de GenderAPI — como la API de Validación de Números Telefónicos — sin tener que manejar manualmente las solicitudes HTTP o el análisis de JSON. Simplemente elige la biblioteca adecuada para tu entorno, instálala y comienza a hacer solicitudes con una configuración mínima.

Puedes encontrar las bibliotecas cliente disponibles e instrucciones de instalación en la siguiente página:
https://www.genderapi.io/es/docs-client-libraries

Preguntas Frecuentes (FAQ)

1. ¿Qué es la API de Validación y Formateo de Números Telefónicos?

La API de Validación y Formateo de Números Telefónicos es una herramienta que te permite validar, formatear y analizar números telefónicos de todo el mundo. Puede convertir los números al formato E.164 estandarizado y determinar metadatos como la región, tipo (móvil/fijo), validez y más.

2. ¿Para qué se utiliza la validación de números telefónicos?

Se utiliza para verificar si un número telefónico es válido, formatearlo para uso internacional, identificar su tipo (por ejemplo, móvil, VoIP), detectar metadatos regionales y asegurar una entrada estandarizada en sistemas de CRM, herramientas de marketing o formularios de registro.

3. ¿Cuántos países son compatibles?

La API admite números telefónicos de 242 países y territorios en todo el mundo. Esto garantiza cobertura global para cualquier aplicación internacional o regional.

4. ¿Qué formatos son compatibles?

La API acepta números en formatos nacionales, internacionales o E.164. Detecta y normaliza automáticamente estos formatos al correcto.

5. ¿Qué ocurre si omito el parámetro de país o dirección?

Si el número telefónico no comienza con un '+' y no se proporciona ningún país/dirección, la API podría no interpretar correctamente el número. Se recomienda incluir el parámetro address (como US, United States o New York).

6. ¿La API puede detectar el tipo de número?

Sí. La API devuelve el campo numberType que indica si el número es MOBILE, FIXED_LINE, VOIP, etc.

7. ¿Cuál es la diferencia entre isValid e isPossible?

isValid significa que el número está oficialmente asignado y cumple con todas las reglas regionales. isPossible verifica si el número podría existir teóricamente según su estructura, aunque aún no esté asignado.

8. ¿Qué tipo de respuesta devuelve la API?

Una respuesta exitosa incluye el estado, variantes del número formateado (nacional, internacional, E.164), datos de región, tipo de número, uso de créditos y más. Consulta la sección de ejemplo de respuesta para ver una salida completa.

9. ¿Cómo debo enviar mi clave API?

Para solicitudes GET, añade la clave como ?key=YOUR_API_KEY. Para solicitudes POST, usa el token Bearer en el encabezado así:
"Authorization: Bearer YOUR_API_KEY".

10. ¿Qué pasa si veo una respuesta con status: false?

Esto significa que la solicitud falló. El campo message incluirá una descripción detallada del error, como parámetros faltantes, número inválido o créditos insuficientes.

11. ¿Se permiten caracteres especiales o espacios en la entrada?

Sí, pero deben estar codificados en URL para solicitudes GET. Por ejemplo, usa %20 en lugar de un espacio. Consulta la sección de advertencia más arriba para el uso correcto.

12. ¿Puedo usar direcciones en diferentes formatos o idiomas?

Sí. Además de los códigos ISO 3166-1 alfa-2 (como US, DE, TR), el parámetro address también acepta nombres completos de países o ciudades — incluso en distintos idiomas. La API utiliza inteligencia artificial para detectar e interpretar inteligentemente el país o región correcto. Por ejemplo:

address=Deutschland
address=États-Unis
address=İstanbul
address=New York
address=Estados Unidos

Todas estas entradas serán correctamente asociadas a sus respectivos países o regiones por la API sin ningún problema.