Reference Guide

Introduction

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

Data Path

This is set during the containerization service setup. It is whatever data path you set.

See {{data_path}} in the Example Docker Setup.

Service Port Number

This is set during the containerization service setup. It defaults to 6245, but can be any port you set.

See {{port_number}} in the Example Docker Setup.

Machine Name

This is your local machine name. You’ll use this in every request you send to your local containerization service. You can view your machine name by using the hostname command in the command prompt.

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 the service will not function.

Endpoints

/V3/WEB/ContactVerify/GetVersion

Introduction

Use this endpoint to check the version of the PhoneLib Service.

Try It Now

• GET JSON

curl -X GET \
"http://{{machine_name}}:{{port_number}}/V3/WEB/ContactVerify/GetVersion" \
-H "accept: application/json"

Headers

• GET JSON

cache-control: no-cache,no-store,must-revalidate,private
content-type: application/json; charset=utf-8
pragma: no-cache

Response

• GET JSON

{
  "Version_0": "7.4.1.17768",
  "ServiceName_0": "phoneLibService",
  "InitializationErrorCode_0": "0",
  "InitializationErrorMessage_0": "No error.",
  "BuildNumber_0": "17768",
  "DatabaseDate_0": "2023-07-01",
  "ExpirationDate_0": "2024-07-02",
  "LicenseExpirationDate_0": "2024-07-02",
  "CanadaDatabaseDate_0": "2023-07-15",
  "CanadaExpirationDate_0": "2024-07-02",
  "Version_1": "7.4.1.17768",
  "ServiceName_1": "phoneLibService",
  "InitializationErrorCode_1": "0",
  "InitializationErrorMessage_1": "No error.",
  "BuildNumber_1": "17768",
  "DatabaseDate_1": "2023-07-01",
  "ExpirationDate_1": "2024-07-02",
  "LicenseExpirationDate_1": "2024-07-02",
  "CanadaDatabaseDate_1": "2023-07-15",
  "CanadaExpirationDate_1": "2024-07-02",
  "Version_2": "7.4.1.17768",
  "ServiceName_2": "phoneLibService",
  "InitializationErrorCode_2": "0",
  "InitializationErrorMessage_2": "No error.",
  "BuildNumber_2": "17768",
  "DatabaseDate_2": "2023-07-01",
  "ExpirationDate_2": "2024-07-02",
  "LicenseExpirationDate_2": "2024-07-02",
  "CanadaDatabaseDate_2": "2023-07-15",
  "CanadaExpirationDate_2": "2024-07-02"
}

/V3/WEB/ContactVerify/doContactVerify

Introduction

Use this endpoint to use all the phone number verification capabilities of Phone Object.

Try It Now

Note

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

Get it here!

• GET JSON
• POST JSON

curl -X GET \
"http://{{machine_name}}:{{port_number}}/V3/WEB/ContactVerify/doContactVerify?\
t=test\
&id={{license_key}}\
&ctry=US\
&a1=22382%20Avenida%20Empresa\
&city=Rancho%20Santa%20Margarita\
&state=CA\
&postal=92688\
&comp=Melissa\
&format=json"\
-H "accept:application/json"

curl -X 'POST' \
  'http://{{machine_name}}:{{port_number}}/V3/WEB/ContactVerify/doContactVerify' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "customerId": "{{license_key}}",
  "options": "",
  "transmissionReference": "test",
  "records": [
    {
      "recordID": "1",
      "addressLine1": "22382 Avenida Empresa",
      "addressLine2": "",
      "suite": "",
      "city": "Rancho Santa Margarita",
      "state": "CA",
      "postalCode": "92688",
      "lastLine": "",
      "plus4": "",
      "deliverypointcode": "",
      "company": "Melissa",
      "urbanization": "",
      "lastName": "",
      "country": "US"
    }
  ]
}'

Request Parameters

Note

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

• 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

cache-control: no-cache,no-store,must-revalidate,private
content-type: application/json; charset=utf-8
pragma: no-cache

cache-control: no-cache,no-store,must-revalidate,private
content-type: application/json; charset=utf-8
pragma: no-cache

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