Look up a Mexican phone number's carrier and location by API

You have a 10-digit Mexican number and you want to know three things: which carrier it's assigned to, whether it's mobile or landline, and where in the country it belongs. In Mexico that information is public: it's maintained by the Federal Telecommunications Institute (IFT) in the National Numbering Plan (Plan Nacional de Numeración, PNN), the catalog that hands number blocks out to the carriers. This post shows how to query it in a single HTTP call — and what it can't tell you, so you don't misuse it.

What the National Numbering Plan is (and why it matters)

Mexican phone numbers aren't handed out at random. The IFT assigns series of numbers to each carrier: a contiguous block (say, 8112345000 through 8112345999) is assigned to one company, for a specific town and network type. Every 10-digit number breaks down into three parts — NIR (the regional prefix), series and subscriber part — and those parts locate the block it belongs to.

Querying the PNN is exactly that: take the number, find the block that contains it, and return the data the IFT recorded for that series. It isn't an estimate or a client-side check digit — it's the official catalog record.

The call

A single GET request, with your Bearer API key (prefix tlmx_) generated in the console. The number goes in as 10 digits, no spaces or dashes:

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

The response is an array of PNN records (there can be more than one match depending on how the series resolves):

[
  {
    "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
  }
]

What each field tells you

• razon_social — the carrier the IFT assigned the series to. In the example, RADIOMOVIL DIPSA (Telcel's legal name). This is your carrier field, and it's the assigned carrier, not necessarily the current one (more on this below).
• tipo_red — MOVIL or FIJO (mobile or landline). This is what you use to choose between SMS and a call, or to drop landlines from a messaging campaign.
• poblacion, municipio, estado — where the series is registered. Useful for segmenting by region or a geographic sanity check.
• nir, serie, numeracion_inicial/numeracion_final — the number's breakdown and the exact range of the assigned block.
• modalidad — the series' commercial scheme (e.g. MPP).
• fecha_asignacion, fecha_consolidacion, fecha_migracion, nir_anterior — series-administration dates and fields: when the block was assigned and, if applicable, when the numbering was consolidated or migrated to a different NIR. These are not subscriber portability data; they describe the block's lifecycle, not an individual line.

The key point: this is not a portability lookup

Here's the caveat that keeps you from using the API for something it can't do. The PNN gives you the carrier the series was originally assigned to. When a user ports their number to another company, that portability is not reflected in the PNN: in the catalog, the number still belongs to its original carrier's series.

In practice: if you ask about a number that was born on Telcel and its owner ported it to AT&T, the API will still answer RADIOMOVIL DIPSA. There is no subscriber-portability source behind this endpoint, and we don't fabricate one. If what you need is “which company holds this number today?”, this API is not the answer — it gives you the assigned carrier, which is a different (and often perfectly useful) question, but not the same one.

When the number isn't in the registry

If the series doesn't exist in the PNN, the API returns 404. That's information too: a well-formed number (10 digits) with no assigned series is usually nonexistent or not routable. In a database cleanup, a 404 is a signal to flag the record, not an error to swallow.

What it's typically used for

• Decide SMS vs. call. The tipo_red field tells you whether the number can receive messages, before you spend on an SMS campaign aimed at landlines.
• Route traffic by carrier. Call centers use the assigned razon_social to optimize interconnection costs.
• Segment by region. estado and municipio let you slice a contact base by geography.
• Detect invalid numbers. The 404 flags nonexistent series in a lead cleanup (see the post on validating numbers for leads and anti-fraud).

Price and notes

Each lookup costs 0.01 u ($0.01 MXN, VAT included) — prepaid, pay per call, no monthly plan. It's one of the cheapest services on the platform precisely so you can sweep entire databases. The data comes from the official IFT catalog.

Get started

1. Create your account and generate your tlmx_ key.
2. One call: GET /v1/phone?number=8112345678 with Authorization: Bearer tlmx_....
3. Read razon_social and tipo_red — and remember the carrier is the assigned one, not the ported one.

• Learn about the phone number lookup service
• Validate Mexican phone numbers: leads and anti-fraud
• Look up numbers from ChatGPT or Claude with the MCP server

Official source: Federal Telecommunications Institute (IFT) — administrator of the National Numbering Plan. This article is informational; the reported carrier is the one assigned to the series in the PNN and does not reflect subscriber portability.