Analyse Request

We would like to point out explicitly that the PhoneNumberAnalysis service is not able to determine whether a phone number has actually been assigned by a telephone company. The validation can only determine whether a given phone number is valid (syntactically correct) or not. An invalid phone number cannot be assigned by the respective telephone company; a valid phone number, however, may have been assigned, but this is not necessarily the case

URL of the service:

The PhoneNumberAnalysis service includes the following request:


The analyse_phone request returns all available data on the input phone number or list of phone numbers. The analysis comprises multiple steps:

  • Syntax validation of the phone number. The result will be returned in the out_syntax output argument. The syntax check is the first step in the processing of phone number data The service does not output any other informa- tion for phone numbers with an incorrect syntax

  • Normalized Formatting As a result, the phone number using a normalized format is returned in the out_format output argument. The normalization standard used for this purpose is the internationally valid E.123 format. However, a parameter is provided that allows you to select a different format.

  • Classification. As a result, the service returns the type of subscriber connection in the out_type output argument.

  • Additional geographic information. For fixed line subscriber connections, the approximate location of the phone is returned in the out_city output argument. This result is based on the local area code of the validated phone number. The service returns the largest town found in the region of the local area code.

Request parameters

The configuration parameters control the processing of the request. The input arguments describe the individual fields of a data record that is to run through the request. Output arguments contain the individual fields of the processed record and do not have to be specified when calling the request.

  • This is an input field

  • This is an output argument

  • This is a configuration parameter

Name Description


Language in which warnings and messages will be displayed.
de = German
en = English (default)
fr = French


Optional: Country code in ISO 3166-1 alpha-2, ISO 3166-1 alpha-3, or ISO 3166-1 numeric format. Example for Germany: de, DE, DEU, 276. if country is empty, enter the country calling code in the in_phone input argument using E.123 format.


Format to be used for outputting the result of normalized formatting
INTERNATIONAL Output in E.123 format. Example: +49 7231 9361000
NATIONAL Output in the format that is used in the identified country. Example: 07231 9361000
E164 Output in E.164 format. Example: +4972319361000
RFC3966 Output in RFC 3966 format. Example: tel:+49-7231-9361000


Phone number (and additionally the local area code for fixed line subscriber connections). If the country parameter is empty, enter the number including the country calling code in E.123 format. In E.123 format, the international country calling code is preceded by a + sign, serving as an international prefix symbol. Example for Germany: +49.


Additional geographic information based on the local area code. For fixed line phone numbers, the service re- turns the largest town found in the region of the local area code. For mobile phone numbers, the country will be returned.


Country calling code


Output of the phone number in the format specified in the par_format parameter. If the phone number is errorneous, this argument remains blank as the number conversion will not work.


Country code that was entered


Phone number that was entered


Normalized country code in ISO-3166 alpha-2 format


For numbers associated with mobile phones, this is the mobile carrier. If the number is not a mobile phone number, the field remains blank. Note: The mobile carrier returned by the service is only correct if the mobile phone user did not keep his / her mobile phone number (i.e. did not opt for mobile number porting) when changing from one carrier to another. In case the number was ported, the previous or first mobile carrier will be returned


Result of the syntax check
0 = Phone number is syntactically correct.
1 = Phone number is syntactically correct but inconsistent.
2 = Phone number is syntactically incorrect.


Result of the syntax check as plain text


0 = Fixed Line
1 = Mobile
2 = Fixed line or mobile
3 = Toll free
4 = Premium rate, chargeable
5 = Shared cost. In the UK, Australia, Germany, France, Portugal, Switzerland, and the Netherlands, shared-cost numbers are numbers where the call costs are shared between the caller and the number owner. This type of number is often used by companies and other organizations. For calls to these numbers, the caller is charged a higher fee than for calls to normal numbers.
6 = VoIP
7 = Personal number
8 = Pager
9 = UAN
10 = Emergency number
11 = Voicemail
12 = Unknown


Type of subscriber connection as plain text.

Executing Request

Most parameters are optional. If you omit them, they either use their default value or are ignored. The request will return the following two objects:

  • info The info object may contain warnings, e.g. if an invalid parameter was passed.

  • content The content object contains the output arguments.

Sample Request

GET /rest/phone_number_analysis/analyse_phone?language=en&country=DE&in_phone=072319360

Sample Response

   "info": [
         "level": "OK",
         "code": 0,
         "description": "",
         "count": 1,
         "durationInMs": 13
   "content": [
         "out_input_phone": "072319360",
         "out_type": "FIXED_LINE",
         "out_syntax": "0",
         "out_input_country": "DE",
         "out_mobile_carrier": "",
         "out_syntax_text": "Valid Number",
         "out_city": "Pforzheim",
         "out_country_calling_code": "49",
         "out_normalized_country": "DE"