Carrier and line type lookup

The carrier lookup tells you what kind of line a phone number is (mobile, fixed line, VoIP, toll-free and others) and which network serves it. When the number has moved away from the network its range was allocated to, it also returns that original carrier. It covers numbers worldwide, in real time or in bulk jobs, and is currently in beta.

#What does the carrier lookup tell you?

It answers two practical questions about a number: can it receive SMS at all, and which network is it on. The first comes from line_type, the second from carrier.

A line_type of mobile means the number belongs to a mobile range. fixed_line, toll_free, premium_rate, shared_cost or uan usually mean SMS will fail or cost money for nothing. voip means the number is served by an internet-telephony provider. In some countries mobile and fixed ranges cannot be told apart, and the answer is then fixed_line_or_mobile. The line type glossary entry explains each value.

carrier is the current network name. original_carrier appears only when it differs from carrier, and a difference is a strong hint that the number was ported. country is the ISO country of the number.

This is data about the number, not about a person or a handset. It does not tell you whether the phone is switched on. That needs a live query to the home network, which the HLR lookup will provide when it launches.

#Who uses it, and why?

Teams that send SMS, place calls or accept phone numbers on forms use the carrier lookup as the first filter.

• SMS cost control. Sending a text to a landline or a toll-free number wastes the message fee and skews delivery reports. Filter by line_type before you send. See SMS cost reduction.
• Routing. Some messaging providers price or route by destination network. The current carrier, not the one the number prefix suggests, is what counts once a number has been ported.
• Sign-up and OTP fraud. A burst of sign-ups from voip numbers or a single small carrier is a common pattern in fake account creation and SMS pumping. The line type is a signal for an extra verification step.
• Lead verification. A form entry with a fixed_line number in a "mobile" field, or a number whose country doesn't match the address, is worth a second look.

Unlike the platform checks, this service returns data rather than a yes/no answer. A conclusive answer has registered: true, which means "data found".

#What do you get back?

An answer is conclusive only when carrier is present. Attributes we don't have are left out rather than guessed.

#How is it billed?

You pay per number, and only when we return carrier data. You're not charged for inconclusive results (unknown, unsupported country, timeout, invalid, duplicate). A number we hold no data for comes back as unknown with reason NO_DATA and is free. Real-time and bulk checks have separate prices. See pricing.

Repeat checks of the same number inside the freshness window can come from your account's cache. Cache hits are free (cached: true, billed: false). Send max_age: 0 to force a fresh, billed check. Use max_cost to cap what a single request can cost.

#What are the limits?

The carrier lookup runs in real time (POST /v1/lookup, up to 100 numbers) and in bulk jobs (POST /v1/jobs, up to 50,000 numbers and e-mails). It accepts numbers from every country, but coverage varies by country. That is why the service is labelled beta, and why NO_DATA answers are free.

• Up to 20 checks per request. Numbers × checks is capped at 2,000 per lookup and 100,000 per job.
• Requests that look like sequential number ranges or generated e-mail lists are rejected (20 or more consecutive numbers → suspected_enumeration).
• A daily numbers cap applies per account (GET /v1/limits).
• Carrier names are returned as we hold them. Brand names, mergers and MVNOs (virtual operators that use another network) can make the name differ from what a subscriber sees on their bill.

#How do I use it responsibly?

Line type and carrier are facts about a number, but the number usually belongs to a person. Check only numbers you have a lawful reason to process, such as customers, sign-ups and leads who gave you their number. Don't use the lookup to screen or profile people for eligibility decisions like credit, housing or employment. The acceptable use policy forbids that. A voip answer is not evidence of fraud on its own. Many legitimate users have VoIP numbers.

People can object to their number being checked through the opt-out form. Suppressed numbers are skipped and never charged.

#Example request

With a test key, +447700900001 returns fixed test data, …002 returns unknown (NO_DATA) and …003 returns unknown (UPSTREAM_TIMEOUT). See test mode.

curl https://api.mobilevalidate.com/v1/lookup \
  -H "Authorization: Bearer mv_test_publicSandboxn9ZgneuhR1B9CRfKG3fulym" \
  -H "Content-Type: application/json" \
  -d '{"numbers":["+447700900001"],"checks":["carrier"]}'

// npm install mobilevalidate · Node.js 20+ · save as check.mjs and run: node check.mjs
import { MobileValidate } from "mobilevalidate";

// Omit apiKey to read MOBILEVALIDATE_API_KEY from the environment.
const mv = new MobileValidate({ apiKey: "mv_test_publicSandboxn9ZgneuhR1B9CRfKG3fulym" });
const { data, error } = await mv.lookup({
  numbers: ["+447700900001"],
  checks: ["carrier"],
});
if (error) console.error(error.code, error.message);
else console.dir(data.results, { depth: null });

// Node.js 18+, Deno, Bun or the browser console (ES module: save as .mjs or use "type": "module").
const res = await fetch("https://api.mobilevalidate.com/v1/lookup", {
  method: "POST",
  headers: {
    Authorization: "Bearer mv_test_publicSandboxn9ZgneuhR1B9CRfKG3fulym",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    numbers: ["+447700900001"],
    checks: ["carrier"],
  }),
});
console.log(res.status, res.headers.get("x-request-id"));
console.dir(await res.json(), { depth: null });

# pip install mobilevalidate-sdk
from mobilevalidate import MobileValidate

# Omit api_key to read MOBILEVALIDATE_API_KEY from the environment.
mv = MobileValidate(api_key="mv_test_publicSandboxn9ZgneuhR1B9CRfKG3fulym")
result = mv.lookup(numbers=["+447700900001"], checks=["carrier"])
print(result)

<?php
$ch = curl_init('https://api.mobilevalidate.com/v1/lookup');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer mv_test_publicSandboxn9ZgneuhR1B9CRfKG3fulym',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'numbers' => ['+447700900001'],
        'checks' => ['carrier'],
    ]),
]);
$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_RESPONSE_CODE), PHP_EOL, $response, PHP_EOL;

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"numbers":["+447700900001"],"checks":["carrier"]}`)
	req, err := http.NewRequest("POST", "https://api.mobilevalidate.com/v1/lookup", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer mv_test_publicSandboxn9ZgneuhR1B9CRfKG3fulym")
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(out))
}

require "net/http"
require "json"

uri = URI("https://api.mobilevalidate.com/v1/lookup")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer mv_test_publicSandboxn9ZgneuhR1B9CRfKG3fulym"
req["Content-Type"] = "application/json"
req.body = JSON.generate({
  "numbers" => ["+447700900001"],
  "checks" => ["carrier"]
})

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.code, res.body

Response (excerpt, test mode: the first item of results):

{
  "kind": "phone",
  "input": "+447700900001",
  "e164": "+447700900001",
  "country": "GB",
  "number_status": "valid",
  "checks": {
    "network.carrier": {
      "service": "network.carrier",
      "status": "completed",
      "registered": true,
      "attributes": {
        "line_type": "mobile",
        "carrier": "Test Carrier",
        "country": "GB"
      },
      "confidence": "high",
      "confidence_score": 0.99,
      "checked_at": "2026-09-25T14:25:31.270Z",
      "cached": false,
      "age_seconds": 0,
      "billed": false,
      "reason": null,
      "poll_after_ms": null
    }
  },
  "test": true
}