Reference Guide

Reference Guide#

Introduction #

Welcome to the Global Phone Cloud API by Melissa. Verify phone numbers from over 230 countries and territories, append useful geographic information, identify various phone types, and flag live numbers.

Base URL #

https://globalphone.melissadata.net

New to Melissa Cloud Services?#

We highly recommend first time users of our web services to review our Using Melissa Cloud APIs section. It will cover critical topics like:

Endpoints #

/V4/WEB/GlobalPhone/doGlobalPhone #

Use this endpoint to validate phone numbers and use all the features of Global Phone.

Try It Now #

GET JSON
POST JSON

curl -X GET "http://globalphone.melissadata.net/V4/WEB/GlobalPhone/doGlobalPhone?\
&t=Test\
&id={{customerId}}\
&opt=\
&phone=1-800-635-4772\
&ctry=US\
&ctryOrg=" \
-H "Content-Type: application/json" \
-H "Accept: application/json"

curl -X POST "http://globalphone.melissadata.net/V4/WEB/GlobalPhone/doGlobalPhone" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
      "TransmissionReference": "Test",
      "CustomerID": "{{customerId}}",
      "Options": "",
      "Records":
      [{
         "RecordID": "1",
         "PhoneNumber": "1-800-635-4772",
         "Country": "US",
         "CountryOfOrigin": ""
      },
      {
         "RecordID": "2",
         "PhoneNumber": "+44 (0)20 7718 0070",
         "Country": "UK",
         "CountryOfOrigin": ""
      }]
    }
   '

Request Parameters #

GET JSON
POST JSON

Code

Description

t

This is a string value that serves as a unique identifier for this set of records. It is returned as sent.

id

The License Key issued by Melissa.

opt

Set Options
CallerID
DefaultCallingCode
EnableBatchSuggestion
TimeToWait
VerifyPhone

phone

The phone number to be verified.

ctry

The suspected country of the input phone number as the official country name or the ISO2 code. Some territories will require a different ISO2 code than the one that is given to them.

ctryOrg

The country from where the verification is being done as the official country name or the ISO2 code. If the Country of Origin differs from the Country, then the outputted phone number will be changed to a callable format from the country of origin. Some territories will require a different ISO2 code than the one that is given to them.

Code

Description

TransmissionReference

This is a string value that serves as a unique identifier for this set of records. It is returned as sent.

CustomerID

The License Key issued by Melissa.

Options

Set Options
CallerID
DefaultCallingCode
EnableBatchSuggestion
TimeToWait
VerifyPhone

RecordID

A unique identifier for the current record.

Phone

The phone number to be verified.

Country

The suspected country of the input phone number as the official country name or the ISO2 code. Some territories will require a different ISO2 code than the one that is given to them.

CountryOfOrigin

The country from where the verification is being done as the official country name or the ISO2 code. If the Country of Origin differs from the Country, then the outputted phone number will be changed to a callable format from the country of origin. Some territories will require a different ISO2 code than the one that is given to them.

Options #

List options in the following format, with multiple options delimited with a ,.

OptionName:Parameter,OptionName:Parameter

CallerID #

US and Canada Only.

Parameter	Description
False	Default. CallerID is turned off.
True	Adds the CallerID to the queried phone, if we found it to be valid.

DefaultCallingCode #

This is used when the country could not be detected from the phone number or country input.

Parameter	Description
[Country Calling Code]	Blank by Default. The sequence of digits found after the leading +.

EnableBatchSuggestion (Batch Mode Only)#

Automatically and aggressively correct invalid phone numbers using the suggestions engine when sending multiple record requests. When there is only one match returned from the suggestions engine in batch mode, Global Phone will automatically resolve the input phone number to that country.

Parameter	Description
False	Default. Suggestions Engine off.
True	Enables records to be corrected using the suggestions engine when there is exactly only 1 suggestion found.

PreferDialingCode #

When there is a mismatch between a phone dialing code (the “+” prefix in a phone number) and country name this controls which is prioritized.

Parameter	Description
False	The service will use the country code provided in the request, even if it does not match the dialing code in the phone number.
True	Default. The service will use the country associated with the dialing code in the phone number, regardless of the country name passed in.

Examples

Input

Output

phone=+4551145623, ctry=BG, preferDialingCode:true

Returned record is for Denmark (DK) phone, because the submitted dialing code (+45) is for Denmark, and we have preferDialingCode set to true.

The ctry input was ignored in favor of using the country specified by the submitted dialing code +45.

phone=+4551145623, ctry=BG, preferDialingCode:false

Returned record is for Bulgaria (BG) phone, because the submitted ctry input is BG, and we have preferDialingCode set to false.

The submitted dialing code was ignored in favor of using the country specified by the ctry input.

phone=+4551145623, ctry=BG

Same results as preferDialingCode:true, since that is the default.

NOTE: The option doesn’t force Global Phone to use the dialing code/country input, it only tells Global Phone which to prefer.

Example showcasing this:

Input

Output

phone=+17143008773, ctry=GB, preferDialingCode:true

Works as expected: returned record is for US because the submitted dialing code (+1) is for the US.

phone=+17143008773, ctry=GB, preferDialingCode:false

Returned record is still for the US. This is because the number 7143008773 doesn’t exist for GB.

Global Phone attempts to find the phone number there, and when it can’t, it uses the dialing code, which allows it to find the US record.

TimeToWait #

TimeToWait allows you to select how long (in seconds) that you would like our web service to wait on a single request before it times out. Select a smaller number if time is of essence, or longer if you would prefer more accurate results.

Parameter	Description
[#{1 - 30}]	Default set to 2. Select how long (in seconds) the service will wait before it times out.

VerifyPhone #

This sets the level of verification to be done on a phone check.

Parameter	Description
Express	Default. Quickly validates against a database of known phone numbers.
Premium	Validates against a database of known phone numbers. If a number was last real-time validated more than 180 days ago, then a real-time check will be performed.

Headers #

GET JSON
POST JSON

Content-Type: application/json
Accept: application/json

Content-Type: application/json
Accept: application/json

Response #

GET JSON
POST JSON

{
  "Version": "7.4.0.1184",
  "TransmissionReference": "Test",
  "TransmissionResults": "",
  "Records": [
    {
      "RecordID": "1",
      "Results": "PS01,PS22",
      "PhoneNumber": "8006354772",
      "AdministrativeArea": "",
      "CountryAbbreviation": "US",
      "CountryName": "United States",
      "Carrier": "(UNKNOWN)",
      "CallerID": "",
      "DST": "",
      "InternationalPhoneNumber": "+18006354772",
      "Language": "",
      "Latitude": "",
      "Locality": "Toll-free",
      "Longitude": "",
      "PhoneInternationalPrefix": "",
      "PhoneCountryDialingCode": "1",
      "PhoneNationPrefix": "1",
      "PhoneNationalDestinationCode": "800",
      "PhoneSubscriberNumber": "6354772",
      "UTC": "",
      "TimeZoneCode": "EST",
      "TimeZoneName": "Eastern Time",
      "PostalCode": "",
      "Suggestions": null
    }
  ]
}

{
  "Version": "7.4.0.1184",
  "TransmissionReference": "Test",
  "TransmissionResults": "",
  "Records": [
    {
      "RecordID": "1",
      "Results": "PS01,PS22",
      "PhoneNumber": "8006354772",
      "AdministrativeArea": "",
      "CountryAbbreviation": "US",
      "CountryName": "United States",
      "Carrier": "(UNKNOWN)",
      "CallerID": "",
      "DST": "",
      "InternationalPhoneNumber": "+18006354772",
      "Language": "",
      "Latitude": "",
      "Locality": "Toll-free",
      "Longitude": "",
      "PhoneInternationalPrefix": "",
      "PhoneCountryDialingCode": "1",
      "PhoneNationPrefix": "1",
      "PhoneNationalDestinationCode": "800",
      "PhoneSubscriberNumber": "6354772",
      "UTC": "",
      "TimeZoneCode": "EST",
      "TimeZoneName": "Eastern Time",
      "PostalCode": "",
      "Suggestions": null
    },
    {
      "RecordID": "2",
      "Results": "PS01,PS20",
      "PhoneNumber": "2077180070",
      "AdministrativeArea": "City of London",
      "CountryAbbreviation": "GB",
      "CountryName": "United Kingdom",
      "Carrier": "BT",
      "CallerID": "",
      "DST": "Y",
      "InternationalPhoneNumber": "+442077180070",
      "Language": "English",
      "Latitude": "51.509918",
      "Locality": "London",
      "Longitude": "-0.127464",
      "PhoneInternationalPrefix": "",
      "PhoneCountryDialingCode": "44",
      "PhoneNationPrefix": "0",
      "PhoneNationalDestinationCode": "20",
      "PhoneSubscriberNumber": "77180070",
      "UTC": "+00:00",
      "TimeZoneCode": "GMT",
      "TimeZoneName": "Greenwich Mean Time",
      "PostalCode": "",
      "Suggestions": null
    }
  ]
}

Service Level Response Fields #

Output Name	Description
Version	The current service version number.
TransmissionReference	Optional. Serves as a unique request identifier.
TransmissionResults	Lists error codes from any errors caused by the most recent request as a whole.
TotalRecords	Total number of records.

Record Level Response Fields #

Output Name	Description
RecordID	The number of the record. Always 1 for a single request, otherwise it serves as an index of the array of records.
Results	Comma delimited status, error codes, and change codes for the record.
PhoneNumber	The standardized phone number. This will return in varying formats depending on the inputs. For more detailed information, see Phone Number Format.
Administrative Area	State. The administrative area (state) associated with the phone number.
Country Abbreviation	The abbreviation of the country.
Country Name	The country name associated with the phone number.
Carrier	The phone number’s carrier name.
Caller ID	The user name associated with the phone number, provided by our Caller ID service.
Daylight Savings Time	Indicates if the phone number region observes daylight savings time. Y for yes or N for no.
International Phone Number	The number you dial to successfully send an international call. This number can change depending on the Country of Origin field.
Language	The predominant language of the phone number’s geographical location.
Latitude	The latitude of the phone number’s service area. Latitude is measured in degrees north or south of the equator.
Locality	The locality (city) associated with the phone number.
Longitude	The latitude of the phone number’s service area. Latitude is measured in degrees east or west of the Greenwich Meridian.
International Prefix	The international exit code needed to call a number outside of the dialing country. This depends on the Country of Origin and Country input fields.
Country Dialing Code	The digit(s) required to reach the target country. These are dialed after the international prefix.
Nation Prefix	The digit(s) dialed before an area (city) code when calling a number within the same country but outside the numbering area.
National Destination Code	The national destination code, the numbering area within a country (or group of countries) and/or network/services.
Subscriber Number	The significant leading digits that further define the local exchange area and/or service.
Universal Time Code	The phone number’s time zone in the format: +/- hh:mm.
Postal Code	US Only. The zip code associated with the phone number.
Suggestions	An array of Response Record Elements. This is for single-record requests only.
Time Zone Code	The 3-letter code for the time zone associated with the phone number.
Time Zone Name	The full name of the 3-letter time zone code returned by the Time Zone Code field.

Phone Number Format #

The phone number will return in varying formats depending on the inputs. If the inputted country and country of origin are the same the returned number will include the National Destination Code + Subscriber Number. For example:

Input Phone	Input Country	Input Country of Origin	Phone Returned
495-728-5802	RU	RU	495-728-5802
+7 495-728-5802	RU	RU	495-728-5802
+1 495-728-5802	RU	RU	495-728-5802

If the inputted country and country of origin differ, the returned number will include a leading + followed by the Country Code + National Destination Code + Subscriber Number. The leading + represents the International Prefix that is required to dial a number outside of the caller’s country. For example:

Input Phone	Input Country	Input Country of Origin	Phone Returned
495-728-5802	RU	US	+7 495-728-5802
+7 495-728-5802	RU	US	+7 495-728-5802
+1 495-728-5802	RU	US	+7 495-728-5802

If a country is entered and a country of origin is left blank or not passed in, the returned number will match the format of the inputted phone number. For example:

Input Phone	Input Country	Input Country of Origin	Phone Returned
495-728-5802	RU	<blank>	495-728-5802
+7 495-728-5802	RU	<blank>	+7 495-728-5802
+1 495-728-5802	RU	<blank>	+7 495-728-5802

Input Best Practices #

This service can deal with multiple languages and scripts. It expects UTF-8 encoding. Be on the lookout for question marks (?), squares (▖) or other unwanted characters like �. They may be an indication of encoding issues and may result in data loss. Bad encoding or character loss is not something our service can correct for you.

Result Codes #

Please visit Result Codes - Global Phone for more information on the result codes returned by Global Phone.

Interpreting Results #

Result codes yield more granular information about a given phone number. They are returned as a comma-delimited string of 4-character alpha-numeric codes, e.g. PS01,PS07,PS18 or PS07,PE04.

SE## and GE## Codes #

The SE## and GE## codes (Transmission Service Error and General Transmission Error) are used to signify more general errors, and are returned under the key TransmissionResults in the outermost level of our responses.

PE## and PS## Codes #

Global Phone web service returns back a string of PSXX result codes in the “Results” field of the response. These result codes provide users with information about the response from the service.

In almost every case, one of the values of the “Results” string will be one of the following:

Code	Description	Recommendation
`PS20`	Number exists within a block of registered phone numbers.	Low Confidence - This number exists within a block of registered phone numbers that the service checks against.
`PS22`	Number was verified against current dialing equipment.	High Confidence - This number was verified against current dialing equipment. This result code will only be returned if the VerifyPhone option in the initial request to the service is set to Premium. (ex: `&opt=VerifyPhone:Premium`).

With these result codes users can easily build logic for what to do with good valid phone numbers and easily distinguish good phone numbers from bad phone numbers.

There are also PEXX codes that can be returned which indicate there was an error with a part of the requested phone number.

Reference Guide

Contents

Reference Guide#