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 8.5.108.02. 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.

Important

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"

Response

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. FROM_NUMBER_WITH_PLUS_SIGN FROM_NUMBER_WITH_IDD FROM_NUMBER_WITHOUT_PLUS_SIGN FROM_DEFAULT_COUNTRY
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: UNKNOWN FIXED_LINE MOBILE FIXED_LINE_OR_MOBILE TOLL_FREE PREMIUM_RATE SHARED_COST VOIP PERSONAL_NUMBER PAGER UAN VOICEMAIL
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"

Examples

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
 
Result
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
 
Result
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

Result

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]"
}

Errors

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

Result 
400 Bad Request
{
	"exception":"com.genesyslab.gsg.GSGException",
	"message":"Invalid Phone Number bad for Country DE (parsing impossible)"
}