Reference Guide

Introduction

Welcome to the Global Phone service 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:

• Licensing

• Rate Limiting

• IP Addresses

• Protocols and Usage

Endpoints

/V4/WEB/GlobalPhone/doGlobalPhone

Introduction

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

Try It Now

Note

Make sure to replace {{customerId}} with your license key.

Get it here!

• 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

Note

For details on territories using different ISO2 codes, see the FAQs.

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

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

Important

Because of phone number portability, geographical information may not reflect the true location of the owner of the phone number for wireless and VOIP numbers.

Note

The Phone Number output field has multiple possible formats, all depending on what was input. For more information, see Phone Number Format.

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.

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

Tip

For more information on country calling codes, see Wikipedia - Country Calling Codes.

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.

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 30 days ago, then a real-time check will be performed.

Phone Number Format

Note

The phone number field, located under the Record Level Response Fields section, returns phone numbers using these formats.

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.

Important

There were significant changes to Global Phone result code handling, for more information see Melissa Blog - Global Phone Result Code Changes.

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.