Skip to content

Phone Validator API

Validate every phone number the moment it arrives

One request tells you whether a number is valid, its line type, carrier, location and port status. Add it to signup forms, lead intake and CRMs in minutes.

POST https://api.phonevalidator.com/v5/lookups

curl https://api.phonevalidator.com/v5/lookups \
  -H "Authorization: Bearer $PHONEVALIDATOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone_number":"(702) 927-0000"}'
import os
import requests

response = requests.post(
    "https://api.phonevalidator.com/v5/lookups",
    headers={"Authorization": f"Bearer {os.environ['PHONEVALIDATOR_API_KEY']}"},
    json={"phone_number": "(702) 927-0000"},
    timeout=30,
)
print(response.status_code, response.json())
const response = await fetch("https://api.phonevalidator.com/v5/lookups", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PHONEVALIDATOR_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"phone_number":"(702) 927-0000"}),
});
console.log(response.status, await response.json());
<?php
$curl = curl_init("https://api.phonevalidator.com/v5/lookups");
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("PHONEVALIDATOR_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode(['phone_number' => '(702) 927-0000']),
]);
$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
curl_close($curl);
echo $status, " ", $response, "\n";
require "json"
require "net/http"

uri = URI("https://api.phonevalidator.com/v5/lookups")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("PHONEVALIDATOR_API_KEY")}"
request["Content-Type"] = "application/json"
request.body = JSON.generate({ "phone_number" => "(702) 927-0000" })

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

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

func main() {
	req, err := http.NewRequest("POST", "https://api.phonevalidator.com/v5/lookups", strings.NewReader(`{"phone_number":"(702) 927-0000"}`))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("PHONEVALIDATOR_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	data, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode, string(data))
}
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("PHONEVALIDATOR_API_KEY"));

var content = new StringContent("""{"phone_number":"(702) 927-0000"}""", Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.phonevalidator.com/v5/lookups", content);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");

Measured at our servers in US East (Ohio); 95% of lookups finish in under 100 ms. One price for every lookup, with no plans, minimums or contracts.

The response

One answer, ready to act on

Response 200 OK

{
  "phone_number": "+17029270000",
  "valid": true,
  "invalid_reason": null,
  "format_national": "(702) 927-0000",
  "format_international": "+1 702-927-0000",
  "country": "US",
  "region": "NV",
  "city": "LAS VEGAS",
  "time_zone": "America/Los_Angeles",
  "line_type": "mobile",
  "carrier": "T-MOBILE",
  "ported": true,
  "cost": "0.0040",
  "balance": "41.2760",
  "test_mode": false
}
valid invalid_reason
Reject mistyped and made-up numbers at the form, with a reason to show the person entering them.
line_type
Tell mobile, landline, VoIP and toll-free numbers apart, and handle each the way your workflow needs.
carrier ported
See who serves the number, including the company behind a VoIP number, such as Google Voice, and whether it has moved between carriers. Try a free carrier lookup.
country region city
Route leads by territory and catch numbers from outside your market.
time_zone
Know the local time where the number was issued.
cost balance
Track spend per request and top up before you run low.

Every field in the API reference

Security and privacy

Built to pass your security review

Phone numbers are personal data, and we treat them that way. Every claim below is documented in our security overview.

  • API numbers are never stored

    Phone numbers you look up through the API are not written to our database or our logs. Each request leaves a billing record of the lookup, never the number itself.

  • Your data stays yours

    We process lookups as your service provider under our Data Processing Addendum, and never sell, share or compile them.

  • Encrypted everywhere

    TLS 1.2 or newer on every connection, AWS KMS encryption at rest, and account details encrypted again inside the application.

  • Hosted in the United States

    AWS in US East (Ohio), in private subnets across two availability zones, behind CloudFront and AWS WAF. Data and backups stay in the United States.

  • Locked-down access

    There is no API phone data to reach, because none is stored. Everything else is open only to named staff with hardware security keys, and audit logs sit in a separate account where they can't be changed or deleted.

  • Ready for vendor review

    We answer security questionnaires, countersign our DPA and notify you of an incident affecting your data within 72 hours. Our security overview details every control.

Built for production

Everything an integration needs

Test keys

Test keys return fixed answers for documented test numbers and are never billed. Build and run your test suite without spending.

Safe retries

Send an Idempotency-Key and retry freely. A retried lookup returns the original response and is billed once.

Clear limits

25 requests per second per account, with higher limits on request. Every response carries rate-limit headers.

Stable contract

The API changes only by addition. Fields keep their name, type and meaning, so integrations keep working.

Proven at scale

Validating numbers since 2005, and now more than 8 million lookups a month across the API, batch uploads and web lookups.

Current data

Every lookup is checked in real time against current carrier and numbering data, for numbers in more than 250 countries and territories.

Compared

How it compares with Twilio Lookup and Numverify

Twilio Lookup charges $0.008 per Line Type Intelligence request, twice our $0.004, and prices caller name and other checks separately. Numverify sells monthly plans from $14.99, with overage fees past the plan. Every Phone Validator lookup includes line type, carrier and, for US numbers, ported status, with no plan to pick.

AI-ready

Set it up with your AI agent

Our docs are published for coding agents at llms.txt, with the full reference in Markdown and an OpenAPI specification. Give your agent this prompt:

Prompt

Read https://www.phonevalidator.com/llms.txt and add Phone Validator phone validation to our signup form. Call the API from our server, never from browser or app code, using the API key in the PHONEVALIDATOR_API_KEY environment variable.

FAQ

Questions

How much does a lookup cost?

$0.004 per lookup, the same for every number. New accounts start with 100 free trial lookups, and no card is required.

How does it compare with Twilio Lookup or Numverify?

See prices, free tiers and what each lookup returns side by side in our phone validation API comparison, with Twilio Lookup, Numverify, IPQualityScore and others.

How does billing work?

You prepay a balance by card, starting at $10, and can turn on auto-refill. Invoicing and custom terms are available on request for larger orders: contact us.

Which requests are billed?

Every completed lookup, valid number or not. Errors, rate-limited requests and requests made with a test key are free.

What does valid mean?

That the number is in a range that is assigned and in service in its numbering plan. It does not confirm that a particular phone is switched on or that a call or text will connect.

How fast is it?

A lookup takes about 40 ms of server time (median) in US East (Ohio), and 95% finish in under 100 ms. Measured end to end from Virginia and Ohio, the median is about 85 ms; see it live on our status page.

Which countries are covered?

Numbers from more than 250 countries and territories, each checked in real time. Every lookup returns the same fields: validity, line type, carrier and location.

Does a lookup tell me who holds a number?

No. A lookup describes the number: whether it is valid, its line type, carrier and location. It does not identify the person holding it.

Is there an uptime commitment?

Yes. We commit to 99.95% monthly uptime for each API version, with service credit of 10% to 50% of that month's API lookup charges if we miss it, and outages at our data providers count. Section 2.8 of our Terms has the details. Live uptime and incident history are public at status.phonevalidator.com.

How do I start?

Create an account, copy your API key from the API keys page and send your first request. Test keys are on the same page.

Start validating numbers today

$0.004 per lookup. Start with 100 free trial lookups, no card required.

Looking for older API docs?

Accessibility