Quickstart Guide

Global Phone

Introduction

The Global Phone Web Service can:

  • Verify and append country dialing codes, international exit codes, national prefixes, and more.
  • Append geographic information on the telephone line such as latitude, longitude, administrative area, and language.
  • Parse the phone number into its various components.
  • Return Caller ID Information for 200 countries.
  • Identify the numbers phone type including mobile, landline, VoIP, and more. (North America Only)
  • Perform a real-time check on a number to know whether it is live or not. (North America Only)

Basic Order of Operations

Real Time

  • Put the contact data into JSON, XML, or REST format.
  • Make sure to include your license key.
  • Specify any options you would like modify from their default values.
  • Specify the level of verification:
    • Express
    • Premium
  • Send the request to the service URL:
  • Receive the result back from the service.

Input Request

Real Time

With a REST request, you can include all the input along with the URL for an easy and quick way of sending a single record.

C:\>curl -X GET “https://globalphone.melissadata.net/v4/WEB/GlobalPhone/doGlobalPhone?id=LICENSEKEY&opt=CallerID:True&phone=1234567890&ctry=USA&ctryorg=&format=json”

Batch

You can send batch requests of up to 100 records per batch that are sent using HTTP POST. You cannot send the request like you would with the previous Real Time example.

Header

Make sure the header includes this line.

Accept: application/json

Body

{
  "TransmissionReference":"string",
  "CustomerID":"string",
  "Options":"string",
  "Records":[
    {
      "RecordID":"string",
      "PhoneNumber":"string",
      "Country":"string",
      "CountryOfOrigin":"string"
    },
    {
      "RecordID":"string",
      "PhoneNumber":"string",
      "Country":"string",
      "CountryOfOrigin":"string"
    },
    {
      ...
    }
  ]
}

Input Fields

Batch Input REST Input Description REQUIRED
TransmissionReference t This is a string value that serves as a unique identifier for this set of records. It is returned as sent. NO
CustomerID id This is a string value containing the License Key issued to the customer by Melissa Data for Global Phone. YES
Options opt CallerID
Code Description
FALSE Default. CallerID is turned off.
TRUE Adds the Caller ID to the queried phone, if we found it to be valid.
DefaultCallingCode
Code Description
(Country Calling Code) DefaultCallingCode is used when the country could not be detected from the phone number or country input. A calling code is a sequence of digits often found after the leading ‘+’ and is unique to a country/region. By default, this value is blank.
TimeToWait
Code Description
(Time in seconds) Default is 2. Time to wait in seconds.
VerifyPhone
Code 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.
RecordID This is a string value containing a unique identifier for the current record. Use this to match the record submitted with the record returned. NO
PhoneNumber phone The phone number to be verified. YES
Country ctry The suspected country of the input phone number. The service accepts the official country name or the ISO2 Code. NO
CountryOfOrigin ctryOrg The country from where the verification is being done. 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 orogin. NO

Output Response

Here is a sample response from the previous request.

{
  "Version":"string",
  "TransmissionReference":"string",
  "TransmissionResults":"string",
  "TotalRecords":"string",
  "Records":[{
    "RecordID":"string",
    "Results":"string",
    "PhoneNumber":"string",
    "AdministrativeArea":"string",
    "CountryAbbreviation":"string",
    "CountryName ":"string",
    "Carrier":"string",
    "CallerID":"string",
    "DST":"string",
    "InternationalPhoneNumber":"string",
    "Language":"string",
    "Latitude":"string",
    "Locality":"string",
    "Longitude":"string",
    "PhoneInternationalPrefix":"string",
    "PhoneCountryDialingCode":"string",
    "PhoneNationPrefix":"string",
    "PhoneNationalDestinationCode":"string",
    "PhoneSubscriberNumber":"string",
    "UTC":"string",
    "PostalCode":"string",
    "TimeZoneCode":"string",
    "TimeZoneName":"string",
    "Suggestions":[{}]
  }]
}

Output Fields

Response (Base Level)

Output Name Description
Version The current service version
TransmissionReference Optional request identifier
TransmissionResults Service and General Transmission Errors
TotalRecords The total number of records returned

Record Level

Output Name Description
RecordID A unique identifier for the current record if one was sent in the request. Use this element to match a request record and the corresponding response record.
Results Comma delimited status, error codes, and change codes for the record.
PhoneNUmber The standardized phone number after a successful call to the service.
AdministrativeArea The administrative area associated with the inputted phone number. 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.
CountryAbbreviation The abbreviation of the country for the inputted phone number.
CountryName The name of the country for the inputted phone number.
Carrier The name of the phone’s carrier.
CallerID You must set CallerID Option to enable (opt=CallerID:true). The result from our CallerID service, which it appends the name to the targeted phone number.
DST Returns a Y (for yes) or N (for no) to distinguish whether the region of the inputted phone number observes daylight savings time.
InternationalPhoneNumber The number you would dial, given your output fields, in order to successfully send a call.
Language The predominant language of the phone’s detected geographical location.
Latitude The latitude of the geographically identifiable service area of the exchange.
Locality The locality (city) associated with the phone number passed to the Lookup function.
Longitude The longitude of the geographically identifiable service area of the exchange.
PhoneInternationalPrefix The international exit code needed to call a number outside of the dialing country.
PhoneCountryDialingCode A digit, or combination of digits, known as the country dialing code.
PhoneNationPrefix A digit, or combination of digits, known as the national prefix.
PhoneNationalDestinationCode A digit, or combination of digits, known as the national destination code.
PhoneSubscriberNumber The subscriber number associated with the phone number passed in. The subscriber number contains significant leading digits that further define the local exchange area and/or service.
UTC The universal time code for the time zone associated with the inputted phone number.
PostalCode The zip code that corresponds to a locality inside the United States.
Suggestions This is an array of Response Record Elements. This can only be returned for single-record requests.
TimeZoneCode The time zone code for the time zone associated with the inputted phone number. Time zone codes are a 3 letter codes for the locality of the region.
TimeZoneName The time zone name associated with the inputted phone number. The name is the full name of the 3 letter time zone code.

Interpreting Results

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 Low Confidence - This number exists within a block of registered phone numbers that the service checks against. Medium
PS22 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). Good

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.

PE Codes

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

For a list of the common transmission errors, see the General Info - Response Level Errors page.

For the full list of all possible result codes, please visit our Result Wiki page at Global Phone Result Code Details.