Jump to: navigation, search

Phone Number Validation API

This Phone Number Validation API wraps the Google's common Java, C++ and JavaScript library for the purposes of parsing, formatting, and validating international phone numbers. GMS integrates Version 7.2.8 and uses the Apache License Version 2.0.

The API supports the following features:

  • Parsing the phone number for a syntactic check (number, plus signs, extensions, and so on);
  • Splitting the phone number into parts (country code, extensions, and so on);
  • Verifying local patterns such as: US=(650) 466-1100, FR=06 04 12 04 05, DE=089 125016040;
  • Translating numbers to enable automated systems to use either localized or E164 or international form (useful to identify unique patterns);
  • Providing some hints on advanced information such as timezone, city, carrier;
  • Providing information in the case of premium numbers.

You can pass a country code in the parameters of your queries. See below for further details.

Note that if the validation parsing fails, the response will be an Error 400.

API Query

GET /genesys/1/phonenumber?number={number}
Name Type Mandatory Description
URI Parameters
number string yes Phone number to validate. For example, 0604120405.
country string no Two-letter country code as defined in ISO 3166. If you do not specify country in your query, US will be used by default to parse the phone number. For example, in the default configuration, the phone number 06 04 12 04 05 is invalid unless you set country=FR in your query.
geocodingLocale string no Language used for displaying the area descriptions. For example, if you validate the phone number "06 04 12 04 05":
  • geocodingLocale=FR would return "location": "France"
  • geocodingLocale=DE would return "location": "Frankreich"


HTTP code 200
HTTP message OK
Response Body (JSON content)
Name Type Mandatory Description
language-specified string yes Specified language set in the geocodingLocale request parameter.
number-specified string yes Validated number.
country-default string yes Specified or default country used for the response.
country-code string yes Country code part; for example, 33 for France.
region-code string yes The region where the phone number is originating from. For example, "IT" for Italy.
country-code-source string yes Information used to detect country code.
extension string yes Extension part. For example, "32" if the number is "0604120405#32". Note that # should be url-encoded as %23 in the request.
number-national-short string yes Short number for country. For example, 604120405 for a French mobile number.
number-national string yes Number formatted using the national format
number-E164 string yes Number formatted using the E.164 format.
number-original string yes Number formatted using the original phone number format that was parsed.
number-international string yes Number formatted using the international format
is-possible-number string yes true if the number looks valid from considering the length information.
is-valid-number string yes true if the number looks valid from considering the length and prefix information.
is-premium string no In case of a valid number, true if the number is a premium rate number.
italian-leading-zero string yes In case of an Italian number, true if the number has leading zero.
number-type string no Type of the number based on the number parsing to determine if the number matches Fixed-line, Mobile, Toll-free, Premium Rate, Shared Cost, VoIP, and Personal Numbers (whenever feasible). The possible types are:
  • VOIP
  • UAN

location string no Geographical information related to a phone number.
time-zone string no Geographical time information related to a phone number.
carrier string no Carrier information related to a phone number.
is-possible-short-number string no If the number is impossible or invalid, might return information on a possible usage as a short number.
is-valid-short-number string no When number is not possible short number, might return info on valid usage as short number.
is-possible-number-with-reason string no When the number is impossible, gives the reason why. For example: "TOO_SHORT"


The following example returns a successful validation result for a French mobile number.

GET http://localhost:8010/genesys/1/phonenumber?number=0604120405&country=FR&geocodingLocale=DE
200 OK
    "language-specified": "de",
    "country-code": "33",
    "extension": "",
    "number-type": "MOBILE",
    "number-national-short": "604120405",
    "number-national": "06 04 12 04 05",
    "number-E164": "+33604120405",
    "number-specified": "0604120405",
    "number-original": "06 04 12 04 05",
    "is-possible-number": "true",
    "italian-leading-zero": "false",
    "carrier": "SFR",
    "country-code-source": "FROM_DEFAULT_COUNTRY",
    "number-international": "+33 6 04 12 04 05",
    "country-default": "FR",
    "is-valid-number-for-region": "true",
    "number-region": "FR",
    "location": "Frankreich",
    "is-valid-number": "true",
    "time-zone": "[Europe/Paris]"

The following example returns a successful validation result for a German fixed line number.

GET http://localhost:8010/genesys/1/phonenumber?number=%2B4989125016040&country=DE&geocodingLocale=FR
200 OK
    "language-specified": "fr",
    "country-code": "49",
    "extension": "",
    "number-type": "FIXED_LINE",
    "number-national-short": "89125016040",
    "number-national": "089 125016040",
    "number-E164": "+4989125016040",
    "number-specified": "+4989125016040",
    "number-original": "+49 89 125016040",
    "is-possible-number": "true",
    "italian-leading-zero": "false",
    "country-code-source": "FROM_NUMBER_WITH_PLUS_SIGN",
    "number-international": "+49 89 125016040",
    "country-default": "DE",
    "is-valid-number-for-region": "true",
    "number-region": "DE",
    "location": "Munich",
    "is-valid-number": "true",
    "time-zone": "[Europe/Berlin]"

The following example returns a successful validation result for a US fixed line number.

GET http://localhost:8010/genesys/1/phonenumber?number=%2B16504661100&country=US&geocodingLocale=FR


200 OK
    "language-specified": "fr",
    "country-code": "1",
    "extension": "",
    "number-type": "FIXED_LINE_OR_MOBILE",
    "number-national-short": "6504661100",
    "number-national": "(650) 466-1100",
    "number-E164": "+16504661100",
    "number-specified": "+16504661100",
    "number-original": "+1 650-466-1100",
    "is-possible-number": "true",
    "italian-leading-zero": "false",
    "carrier": "",
    "country-code-source": "FROM_NUMBER_WITH_PLUS_SIGN",
    "number-international": "+1 650-466-1100",
    "country-default": "US",
    "is-valid-number-for-region": "true",
    "number-region": "US",
    "location": "California",
    "is-valid-number": "true",
    "time-zone": "[America/Los_Angeles]"


A 400 Bad request error is generated if the phone number is invalid. For example:

GET http://localhost:8010/genesys/1/phonenumber?number=bad&country=DE&geocodingLocale=de
400 Bad Request
	"message":"Invalid Phone Number bad for Country DE (parsing impossible)"

Comment on this article:

blog comments powered by Disqus
This page was last modified on 13 April 2017, at 06:04.