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

Licensing

The License Key is a software key required to use the web service. You will receive your license key from your Melissa representative. If you don’t have a license key, contact the Melissa sales team at sales@melissa.com or 800-MELISSA ext. 3 (800-635-4772 ext. 3). Without a license key, Global Phone will not function.

To set the license key, use the id/CustomerID property in your requests.

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

Important

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

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.

PS## and PE## Codes

The PS## and PE## codes (Phone Status and Phone Error) are returned alongside each phone number record in a request.

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.

Service Level Result Codes

Note

The Service Level result codes apply to the service as a whole.

Code	Short Description	Long Description
Transmission Service Error
SE01	Cloud Service Internal Error	The cloud service experienced an internal error.
General Transmission Error
GE01	Empty Request Structure	The SOAP, JSON, or XML request structure is empty. Not to be confused with the GE01 GeoCode result code.
GE02	Empty Request Record Structure	The SOAP, JSON, or XML request record structure is empty. Not to be confused with the GE02 GeoCode result code.
GE03	Records Per Request Exceeded	The counted records sent more than the number of records allowed per request.
GE04	Empty License Key	The License Key is empty.
GE05	Invalid License Key	The License Key is invalid.
GE06	Disabled License Key	The License Key is disabled.
GE07	Invalid Request	The SOAP, JSON, or XML request is invalid.
GE08	Product/Level Not Enabled	The License Key is invalid for this product or level.
GE09	Customer Does Not Exist	The Customer ID is not in our system.
GE10	Customer License Disabled	The encrypted license is on the ban list.
GE11	Customer Disabled	The Customer ID is disabled.
GE12	IP Blacklisted	The IP Address is on the global ban list.
GE13	IP Not Whitelisted	The IP Address is not on the customer’s whitelist.
GE14	Out of Credits	The account has ran out of credits. Add more credits to continue using the service.
GE26	CallerID Not Enabled	The license key or ID does not have CallerID enabled.

Record Level Result Codes

Note

The Record Level result codes apply to the individual request records.

Tip

For example input that returns specific codes, see the FAQ: Result Code Examples

Code	Short Description	Long Description
PS - Phone Status
PS01	Valid Phone	The phone number has been verified as valid.
PS07	Cellular Line	On activation, the exchange type of the phone number was designated as a cellular number, but current status cannot be confirmed.
PS08	Land Line	On activation, the exchange type of the phone number was designated as a land line, but current status cannot be confirmed.
PS18	Do Not Call	The phone number was found in Melissa’s proprietary Do Not Call list.
PS19	Disposable Phone Number	The phone number submitted was identified as a temporary number generally used to circumvent two factor authentication (2FA).
PS20	Low Confidence	Number exists within a block of registered phone numbers.
PS22	High Confidence	Number was verified against current dialing equipment.
PS30	Premium Timeout	Querying Premium has timed out, but has continued to run in the background. Query later to obtain the cached results.
PS31	CallerID Timeout	Querying CallerID has timed out, but has continued to run in the background. Query later to obtain the cached results.
PE - Phone Error
PE01	Invalid Phone	The area code/phone number does not exist in our database or contains non-numbers.
PE02	Blank Phone	The phone number is blank.
PE03	Bad Phone	The phone number has too many or too few digits.
PE04	Multiple Match	Two or more possible area codes are available as a fix and their distance is too close to choose one over the other.
PE05	Bad Prefix/Prefix +1	The phone prefix or first 7-digits do not exist in our database.
PE11	Disconnected Phone	Phone number has been disconnected.