API reference v1 · REST · JSON

One request. Every number.

Validate a number, reveal its carrier and line type, and return clean formats — all from one lightweight endpoint.

Endpoint: One
Setup: Instant
Misses: Free

GET /v1/lookup

200 OK

Quick start

curl --request GET \
  --url "https://numberverifyapi.com/v1/lookup?number=+12012046698&key=api_key"

Copy, paste and run. No SDK required.

Base URL

All endpoints live under one versioned base path.

https://numberverifyapi.com/v1

Authentication

Every request needs your API key. Choose whichever method fits your client.

Query string

?key=YOUR_API_KEY

Quick for tests and simple scripts.

API key header

X-API-Key: YOUR_API_KEY

Clean and explicit for most apps.

Bearer token

Authorization: Bearer KEY

Works well with existing HTTP clients.

Lookup endpoint

GET POST /v1/lookup

Returns the carrier, line type, validity and standard formats for a single phone number. US & Canada (+1) numbers are answered from the local NPA-NXX dataset, with US toll-free prefixes classified from the standard active and reserved NPA lists and the 811 prefix returned as governmental; all other countries are resolved with libphonenumber.

Example request

https://numberverifyapi.com/v1/lookup?number=+12012046698&key=api_key

Parameters

The number and your key are required. A country hint is optional for national numbers.

Parameter	Required	Description
number	Yes	The phone number to look up, in any format. Use an international `+` prefix or a national number; the country is detected automatically.
key	Yes	Your API key. May also be sent as an `X-API-Key` or `Authorization: Bearer` header.
country_code	No	Optional ISO-2 hint, or a comma-separated list such as `US,GB,CH`, for ambiguous national numbers.

In a query string, + means a space. Encode a literal E.164 plus as %2B.

Sample response

A successful lookup returns 200 OK with a JSON body.

JSON response 200 OK

{
   "number": "2012046698",
   "formatted": "(201) 204-6698",
   "carrier": "OMNIPOINT COMMUNICATIONS, INC. (T-Mobile US, Inc)",
   "line_type": "MOBILE",
   "valid": true,
   "country": "US",
   "e164": "+12012046698"
}

Field	Type	Description
number	string	The lookup key that was resolved.
formatted	string	Human-readable national format.
carrier	string	Carrier that owns the number, or `null` when unknown.
line_type	string	One of `MOBILE`, `FIXED_LINE`, `VOIP`, `TOLL_FREE`, `TOLL_FREE_RESERVED`, `GOVERNMENTAL`, etc. Reserved US toll-free prefixes are billed as successful checks.
valid	boolean	`true` for a recognised number, `false` for an unknown US/Canada number.
country	string	ISO-2 country code.
e164	string	The number in E.164 format.

Account endpoint

Check the balance and usage counters for the account that owns your API key.

GET https://numberverifyapi.com/v1/account?key=api_key

JSON response 200 OK

{
   "success": true,
   "credits": 5000,
   "status": "active",
   "total_lookups": 1240,
   "total_hits": 1180,
   "cost_per_lookup": 1
}

Errors

Errors use { "error": { "code": "...", "message": "..." } } with the following status codes.

Status	Meaning
400	Bad input, invalid number or bad country.
401	Missing or invalid API key.
402	Insufficient credits.
403	Account suspended.
429	Rate limit exceeded.
503	API disabled.

Ready when you are

Make your first lookup in minutes

Create a free account, copy your key and send a request. No sales call or SDK required.

Get your free API key View pricing