API para Validar y Formatear Números de Teléfono

Información telefónica global

Un número, una salida coherente

Acepta entradas nacionales, internacionales o con formato irregular y recibe formatos normalizados y datos de validación para 242 países y territorios.

Entrada original+1 212 867 5309

Salida E.164+12128675309

ValidaciónisValid e isPossible

FormatoNacional, internacional y E.164

ClasificaciónMóvil, fijo, VoIP y más

UbicaciónRegión, código de área y lugar

Parámetros de entrada

Número y contexto regional

Parámetro	Requisito	Descripción
`number`	Obligatorio	Número en formato nacional, internacional o E.164.
`address`	Condicional	Código ISO, país, ciudad o región para interpretar un número nacional.

Cuándo es obligatorio address

Si number no comienza con + y un prefijo internacional, añade contexto como ES, España o Madrid.

ESEspañaMadridMéxicoBuenos Aires

GET

Autenticación mediante query string

Solicitud GET básica

cURL

curl "https://api.genderapi.io/api/phone?key=YOUR_API_KEY&number=%2B12128675309&address=US"

Codificación URL: Codifica + como %2B y los espacios como %20. Utiliza URL/URLSearchParams en lugar de construir la cadena manualmente.

POST

Autenticación Bearer

Solicitud POST desde el servidor

Envía el número y el address opcional como JSON, con la clave API en el header Authorization.

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"}'

JavaScript

const response = await 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" })
});

Respuesta de la API

Validación, formato y metadatos

JSON

{
 "status": true, "remaining_credits": 15709, "expires": 0, "duration": "18ms",
 "regionCode": "US", "countryCode": 1, "country": "United 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)"
}

Campos de respuesta

Campo	Tipo	Descripción
`status`	boolean	Indica si la solicitud se ha completado correctamente.
`remaining_credits`	integer	Créditos disponibles después de la solicitud.
`expires`	integer	Vencimiento de los créditos como marca de tiempo UNIX.
`duration`	string	Tiempo de procesamiento en el servidor.
`regionCode`	string	Código de región ISO 3166-1 alfa-2 detectado.
`countryCode`	integer	Prefijo telefónico internacional.
`country`	string	Nombre del país.
`national`	string	Número formateado para uso nacional.
`international`	string	Número formateado para visualización internacional.
`e164`	string	Representación canónica E.164.
`isValid`	boolean	Indica si el número cumple las reglas regionales.
`isPossible`	boolean	Indica si el número podría existir según su estructura.
`numberType`	string	Categoría detectada del número.
`nationalSignificantNumber`	string	Número nacional sin prefijo telefónico del país.
`rawInput`	string	Número original enviado en la solicitud.
`isGeographical`	boolean	Indica si puede asociarse con un área geográfica.
`areaCode`	string	Segmento de código de área detectado.
`location`	string	Ubicación asociada con el código de área.

Referencia de clasificación

Tipos de números de teléfono

FIXED_LINE

Línea fija asociada con una ubicación geográfica.

MOBILE

Número de teléfono móvil.

FIXED_LINE_OR_MOBILE

El plan de numeración no distingue entre línea fija y móvil.

TOLL_FREE

Número gratuito cuyo coste asume el receptor.

PREMIUM_RATE

Número de servicio con tarifa especial.

SHARED_COST

El coste se comparte entre quien llama y quien recibe.

VOIP

Número de telefonía por internet.

PERSONAL_NUMBER

Número personal que puede redirigir a otra línea.

PAGER

Número de buscapersonas.

UAN

Número de acceso universal utilizado como contacto empresarial compartido.

VOICEMAIL

Número dedicado de acceso al buzón de voz.

UNKNOWN

No se ha podido determinar la categoría del número.

Preguntas frecuentes

Preguntas sobre la API de teléfonos

¿Qué hace la API de validación de teléfonos?

Valida y normaliza números, devuelve los formatos nacional, internacional y E.164 e identifica región, tipo y datos geográficos cuando están disponibles.

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

isValid comprueba el número con las reglas regionales; isPossible indica que su estructura podría representar un número aunque no se pueda confirmar su validez.

¿Cuándo es obligatorio address?

Incluye address cuando el número no empieza con el signo más y el prefijo internacional. Puede ser un código ISO, país, ciudad o región.

¿Cómo se envían los caracteres especiales?

Codifica para URL los espacios, signos más y otros caracteres especiales en parámetros GET. Tu cliente HTTP codifica los cuerpos JSON POST.

Siguiente referencia

Controla el uso y la cuota

Uso y cuotaComprende los créditos y límites →Bibliotecas clienteInstala un paquete de validación telefónica →