Consultar el operador y la ubicación de un número de México por API

Tienes un número mexicano de 10 dígitos y quieres saber tres cosas: qué operador lo tiene asignado, si es móvil o fijo, y de qué parte del país es. En México esa información es pública: la administra el Instituto Federal de Telecomunicaciones (IFT) en el Plan Nacional de Numeración (PNN), el catálogo que reparte los bloques de numeración entre las compañías. Este post te muestra cómo consultarla en una sola llamada HTTP — y qué no puede decirte, para que no la uses mal.

Qué es el Plan Nacional de Numeración (y por qué importa)

Los números telefónicos mexicanos no se reparten al azar. El IFT asigna series de numeración a cada operador: un bloque contiguo de números (por ejemplo, del 8112345000 al 8112345999) queda asignado a una compañía, para una población y un tipo de red concretos. Cada número de 10 dígitos se descompone en tres partes — NIR (el prefijo regional), serie y numeración — y con esas partes se localiza el bloque al que pertenece.

Consultar el PNN es justo eso: tomar el número, encontrar el bloque que lo contiene y devolverte los datos que el IFT registró para esa serie. No es una estimación ni un dígito verificador calculado del lado del cliente: es el dato oficial del catálogo.

La llamada

Una sola petición GET, con tu API key tipo Bearer (prefijo tlmx_) que generas en la consola. El número va como 10 dígitos, sin espacios ni guiones:

curl -X GET "https://api.tlaloc.sh/mx/v1/phone?number=8112345678" \
  -H "Authorization: Bearer tlmx_TU_API_KEY"

La respuesta es un arreglo de registros del PNN (puede haber más de una coincidencia según cómo se resuelva la serie):

[
  {
    "clave_censal": "190390001",
    "poblacion": "MONTERREY",
    "municipio": "MONTERREY",
    "estado": "NUEVO LEÓN",
    "region": 2,
    "nir": 81,
    "serie": 1234,
    "asl": 4,
    "tipo_red": "MOVIL",
    "modalidad": "MPP",
    "razon_social": "RADIOMOVIL DIPSA SA DE CV",
    "numeracion_inicial": "8112345000",
    "numeracion_final": "8112345999",
    "ocupacion": 1000,
    "fecha_asignacion": "2021-03-10",
    "fecha_consolidacion": null,
    "fecha_migracion": null,
    "presuscripcion": null,
    "nir_anterior": null
  }
]

Qué te dice cada campo

• razon_social — el operador al que el IFT asignó la serie. En el ejemplo, RADIOMOVIL DIPSA (la razón social de Telcel). Este es el dato de operador, y es el operador asignado, no necesariamente el actual (más sobre esto abajo).
• tipo_red — MOVIL o FIJO. Es lo que usas para decidir entre SMS y llamada, o para descartar fijos de una campaña de mensajes.
• poblacion, municipio, estado — dónde está registrada la serie. Útil para segmentar por región o para una verificación de coherencia geográfica.
• nir, serie, numeracion_inicial/numeracion_final — la descomposición del número y el rango exacto del bloque asignado.
• modalidad — el esquema comercial de la serie (por ejemplo, MPP).
• fecha_asignacion, fecha_consolidacion, fecha_migracion, nir_anterior — fechas y datos de administración de la serie: cuándo se asignó el bloque y, si aplica, cuándo se consolidó o migró la numeración a otro NIR. No son datos de portabilidad de un suscriptor; describen el ciclo de vida del bloque, no de una línea individual.

Lo importante: esto no es una consulta de portabilidad

Aquí está la advertencia que evita que uses la API para algo que no puede hacer. El PNN te da el operador al que se asignó originalmente la serie. Cuando un usuario porta su número a otra compañía, esa portabilidad no se refleja en el PNN: el número sigue perteneciendo, en el catálogo, a la serie de su operador original.

En la práctica: si preguntas por un número que nació en Telcel y su dueño lo portó a AT&T, la API te seguirá respondiendo RADIOMOVIL DIPSA. No hay una fuente de portabilidad del suscriptor detrás de este endpoint, y no la inventamos. Si lo que necesitas es “¿a qué compañía está hoy este número?”, esta API no es la respuesta — te da el operador asignado, que es una pregunta distinta y perfectamente útil para muchos casos, pero no la misma.

Cuando el número no está en el registro

Si la serie no existe en el PNN, la API responde 404. Eso también es información: un número con formato válido (10 dígitos) pero sin serie asignada suele ser inexistente o no enrutable. En una limpieza de base de datos, un 404 es una señal para marcar el registro, no un error que debas ignorar.

Para qué se usa normalmente

• Decidir SMS vs. llamada. El campo tipo_red te dice si el número puede recibir mensajes, antes de gastar en una campaña de SMS sobre fijos.
• Enrutar tráfico por operador. Los call centers usan la razon_social asignada para optimizar costos de interconexión.
• Segmentar por región. estado y municipio permiten cortar una base de contactos por geografía.
• Detectar números inválidos. El 404 marca series inexistentes en una limpieza de leads (ver el post sobre validación de números para leads y antifraude).

Precio y notas

Cada consulta cuesta 0.01 u ($0.01 MXN, IVA incluido) — prepago por consulta, sin plan mensual. Es de los servicios más baratos de la plataforma justamente para que puedas recorrer bases enteras. Los datos provienen del catálogo oficial del IFT.

Empieza

1. Crea tu cuenta y genera tu key tlmx_.
2. Una llamada: GET /v1/phone?number=8112345678 con Authorization: Bearer tlmx_....
3. Lee razon_social y tipo_red — y recuerda que el operador es el asignado, no el portado.

• Conoce el servicio de consulta de números telefónicos
• Validar números telefónicos de México: leads y antifraude
• Consulta números desde ChatGPT o Claude con el servidor MCP

Fuente oficial: Instituto Federal de Telecomunicaciones (IFT) — administrador del Plan Nacional de Numeración. Este artículo es informativo; el operador reportado es el asignado a la serie en el PNN y no refleja la portabilidad del suscriptor.