Skip to main content
POST

​
Good to know

  • Send country for local numbers. A number without a + prefix, such as (415) 555-2671, needs a country to be read. Use the country of your form, the user’s billing address or their IP. Without it the result is reason: missing_country.
  • Store e164. It is the one format every SMS and voice provider accepts, and it makes duplicates easy to spot.
  • valid is not “in service”. The number is in an assigned range, but Finowl doesn’t call or text it. Send a one-time code when you need to know the user owns it.
  • carrier is the original carrier. It is the network the number range was first allocated to. Numbers that were ported keep their old carrier here. It is usually null for US and Canadian numbers.
  • fixed_line_or_mobile is common. In the US, Canada and some other countries, landlines and mobiles share ranges, so the type can’t be told apart. Don’t reject these as “not mobile”.
  • location can be just the country. When the number has no finer area, which is common for mobile numbers, location is the country name, for example India.
  • Time zones use the library’s IANA names. Some are older aliases, such as Asia/Calcutta rather than Asia/Kolkata. Toll-free and other national numbers can list every time zone in the country.
  • Bad input is a 200, not an error. Unparseable numbers return valid: false with a reason.
  • Nothing leaves Finowl. Validation runs offline against Google’s open-source libphonenumber data.
Phone metadata from Google libphonenumber (Apache 2.0), via the nyaruka/phonenumbers Go port (MIT).

Guide: sign-up fraud checks

Validate the email, phone and IP address together when someone registers.

Authorizations

​
Authorization
string
header
required

Your Finowl API key, for example finowl_3f9a.... Create keys in the dashboard under API Keys.

Body

application/json
​
phone
string
required

The number as the user typed it. Spaces, dashes, dots and brackets are fine. Start with + and the country calling code, or send country.

Required string length: 1 - 64
Example:

"(415) 555-2671"

​
country
string

ISO 3166-1 alpha-2 code, in any case, used to read numbers written without a + prefix, such as US or GB. Ignored when the number starts with +. Unassigned codes such as ZZ return invalid_input.

Pattern: ^[A-Za-z]{2}$
Example:

"US"

Response

The check completed. Invalid numbers are still successful responses.

​
phone
string
required

The number you sent.

​
valid
boolean
required

true when the number matches an assigned range in its country's numbering plan. It does not prove the number is in service.

​
possible
boolean
required

true when the number has a plausible length for its country. A possible number can still be invalid.

​
reason
enum<string> | null
required

Why the number is not valid. null when valid is true.

  • unparseable: the input does not look like a phone number.
  • missing_country: the number has no + prefix and no country was sent.
  • too_short or too_long: the number has the wrong length for its country.
  • invalid_number: the length is plausible, but the number is not in an assigned range.
Available options:
unparseable,
missing_country,
too_short,
too_long,
invalid_number,
null
​
country_code
string
required

ISO 3166-1 alpha-2 code of the number's country. Empty when unknown.

​
country
string
required

The country name for country_code. Empty when unknown.

​
calling_code
integer | null
required

The country calling code, such as 1 or 44. null when unknown.

​
type
enum<string>
required

The kind of line, from the numbering plan. fixed_line_or_mobile is common in countries such as the US and Canada, where landline and mobile numbers share ranges. uan is a universal access number, a single number that routes to several lines. unknown for invalid numbers.

Available options:
mobile,
fixed_line,
fixed_line_or_mobile,
toll_free,
premium_rate,
shared_cost,
voip,
personal_number,
pager,
uan,
voicemail,
unknown
​
e164
string | null
required

The number in E.164 format, such as +14155552671. Store numbers in this format. null when the number could not be parsed.

​
international
string | null
required

The number formatted for international display. null when it could not be parsed.

​
national
string | null
required

The number formatted for display within its own country. null when it could not be parsed.

​
carrier
string | null
required

The carrier the number range was originally allocated to. Numbers can be ported, so the current carrier may differ. null when unknown, which is usual for landlines and for US and Canadian numbers.

​
location
string | null
required

A geographic description in English, such as San Francisco, CA, from the number's area code. Falls back to the country name, such as India, when there is no finer area. null when unknown.

​
timezones
string[]
required

IANA time zones the number may be in, such as America/Los_Angeles, using libphonenumber's names (for example Asia/Calcutta). National numbers such as toll-free can list every zone in the country. Empty when unknown.