Geo API

Phone number validation API

Send a phone number, and Geo API tells you whether it is valid, its country and its type (mobile, fixed line), and returns it formatted as E.164, national and international. To catch wrong numbers in sign-up forms before they are saved, and to bring the numbers in a database to one format.

How it works

/v1/phone?number= checks the number against each country's numbering plan. A number starting with + is matched to its country by the calling code; for a number written locally, such as 0532…, pass the default country with country=TR.

valid says the number is in a range the country's plan uses, possible that its length fits. Store the e164 field and show national or international; type gives a kind such as mobile, fixed_line or toll_free.

What it does not check

Validation looks at the number's format and numbering plan; it does not tell you whether the line is active, who owns it or whether it can receive SMS. For that, send the number a verification code by SMS.

The source is the numbering plan data of Google's libphonenumber library, which covers the numbering plans of the world's countries.

Example request and response

A Turkish mobile number written in local form; country=TR sets the default country. No key needed.

Request

curl "https://api.forlab.io/geo/v1/phone?number=05321234567&country=TR"

Response excerpt

{
  "data": {
    "valid": true,
    "possible": true,
    "e164": "+905321234567",
    "national": "0532 123 45 67",
    "international": "+90 532 123 45 67",
    "country": "TR",
    "type": "mobile"
  },
  "meta": { … }
}

The same job with the Apify Actor

Without a key, or for a batch, give the Geo Reference Actor a list: each item becomes one result row that keeps the value you sent. Example input:

{"operation": "phone", "items": [{"number": "+4915112345678"}, {"number": "05321234567", "country": "TR"}]}

What it costs

  • Without a key: 1,000 requests per IPv4 address or IPv6 /64 per UTC day free, shared across all keyless routes (meta, countries, countries/{cc}, places, places/{id}, phone).
  • Apify Actor (phone operation): $0.10 per 1,000 numbers.

On Apify you pay as you go: only answered lookups are charged, items that cannot become a request are free, and each run adds a $0.001 start fee. The Apify free plan's $5 monthly credit covers about 16,000 coordinate lookups. For a direct API key, email api@forlab.io.

Frequently asked questions

Does it check that the number is in use?

No. It checks the format and the numbering plan; it does not tell you whether the line is active or who owns it. For that, send the number a code by SMS.

What does the reply look like for an invalid number?

valid: false, without the formatted fields; possible still says whether the length fits. If the number cannot be parsed at all, a reason field says why (such as too_short or too_long). The HTTP status is still 200: an invalid number is not a request error.

Which format should I store?

Store e164 (+905321234567): it includes the country code, has no spaces or brackets and looks the same for every country. Show national or international on screen.

Can I clean a list of numbers in bulk?

Yes. Give the Geo Reference Actor on Apify the list: each number becomes one result row, and the value you sent stays in its input field.

More you can do with Geo API