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:

https://real-time.data-quality-service.com/rest/phone_number_analysis/analyse_phone

The PhoneNumberAnalysis service includes the following request:

/rest/phone_number_analysis/analyse_phone?language=language&country=country&par_*&in_*

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

Name	Description
language	Language in which warnings and messages will be displayed. `de` = German `en` = English (default) `fr` = French
country	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.
par_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
in_phone	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`.
out_city	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.
out_country_calling_code	Country calling code
out_format	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.
out_input_country	Country code that was entered
out_input_phone	Phone number that was entered
out_normalized_country	Normalized country code in ISO-3166 alpha-2 format
out_mobile_carrier	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
out_syntax	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.
out_syntax_text	Result of the syntax check as plain text
out_type	`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
out_type_text	Type of subscriber connection as plain text.

language

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

country

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.

par_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

in_phone

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.

out_city

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.

out_country_calling_code

Country calling code

out_format

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.

out_input_country

Country code that was entered

out_input_phone

Phone number that was entered

out_normalized_country

Normalized country code in ISO-3166 alpha-2 format

out_mobile_carrier

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

out_syntax

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.

out_syntax_text

Result of the syntax check as plain text

out_type

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

out_type_text

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