Global Phone:Request: Difference between revisions

From Melissa Data Wiki
Jump to navigation Jump to search
← Older edit
No edit summary
No edit summary
 
(20 intermediate revisions by the same user not shown)
Line 6: Line 6:
{{CustomTOC}}
{{CustomTOC}}


A request consists of a protocol to make a call to the service, detailing desired elements. The minimum required elements in a request are your Customer ID and at least one input phone number. Though not required, an input country name will greatly increase the chances of recognizing and verifying the phone number in question.
A request consists of a protocol to make a call to the service, detailing desired elements. The minimum required elements in a request are your Customer ID (License Key) and at least one input phone number. Though not required, an input country name will greatly increase the chances of recognizing and verifying the phone number in question.


Global Phone supports REST and JSON protocols.
Global Phone supports REST and JSON protocols.
==URL==
{{URL-GlobalPhone}}




Line 15: Line 19:


{| class="alternate01 sortable"
{| class="alternate01 sortable"
!Field Name !! Level !! REST Abbreviation !! JSON
!Field Name !! Level !! REST !! JSON
|- style="vertical-align:top;"
|Transmission Reference||Request||t||TransmissionReference
|-
|-
|Customer ID||Request||id||CustomerID
|Transmission Reference||rowspan="3" valign="center"|Request||t||TransmissionReference
|-
|-
|Options||Request||opt||Options
|License Key||id||CustomerID
|-
|-
|Record ID||Record|| ||RecordID
|Options||opt||Options
|-
|-
|Phone Number||Record||phone||PhoneNumber
|Record ID||rowspan="4" valign="center"|Record|| ||RecordID
|-
|-
|Country||Record||ctry||Country
|Phone Number||phone||PhoneNumber
|-
|-
|Country Of Origin||Record||ctryOrg||CountryOfOrigin
|Country||ctry||Country
|-
|Country Of Origin||ctryOrg||CountryOfOrigin
|}
|}


Line 44: Line 48:
!Protocol !! Syntax
!Protocol !! Syntax
|-
|-
|JSON||“TransmissionReference”:”string"
|JSON||<code>"TransmissionReference":"'''''string'''''"</code>
|-
|-
|REST||?t = {string}
|REST||<code>?t = '''''string'''''</code>
|}
|}




<h3 style="background-color:rgb(240,240,240);">Customer ID</h3>
<h3 style="background-color:rgb(240,240,240);">License Key</h3>
:''Required.''
:''Required.''


:This is a string value containing the identification number issued to the customer by Melissa Data for Global Phone.
:This is a string value containing the License Key issued to the customer by Melissa Data for Global Phone.


:If this element is absent, the Web Service will return an error. To receive a customer ID, please contact your Melissa Data sales representative at 1-800-MELISSA.
:If this element is absent, the Web Service will return an error. To receive a License Key, please contact your Melissa Data sales representative at 1-800-MELISSA.


:{| class="alternate01"
:{| class="alternate01"
!Protocol !! Syntax
!Protocol !! Syntax
|-
|-
|JSON||"CustomerID”:”string”
|JSON||<code>"CustomerID":"'''''string'''''"</code>
|-
|-
|REST||&id = {string}
|REST||<code>&id = '''''string'''''</code>
|}
|}


Line 69: Line 73:
:''Optional.''
:''Optional.''


:This is a string value containing the options set by the user. For more information on options available for this service, see [[Global Phone:Options|Options]].
:This is a string value containing the options set by the user.


:{| class="alternate01"
:{| class="alternate01"
!Protocol !! Syntax
!Protocol !! Syntax
|-
|-
|JSON||"Options”:”string”
|JSON||<code>"Options":"'''''string'''''"</code>
|-
|REST||<code>?opt = '''''string'''''</code>
|}
 
:List options in the following format, with multiple options delimited with a ",".
 
:{| class="alternate01"
!Syntax
|-
|<code>''OptionName'':''Parameter'',''OptionName'':''Parameter''</code>
|}
 
 
:<h4 style="border-bottom:1px solid black;">CallerID</h4>
::''US and Canada Only.''
 
::Returns the name or association linked to the phone number at the time of registration, if available.
 
::{| class="alternate01 sortable"
!Option Name !! Parameter !! Description
|-
|rowspan="2"|'''CallerID'''||<code>False</code>||'''''Default.''''' CallerID is turned off.
|-
|<code>True</code>||Adds the CallerID to the queried phone, if we found it to be valid.
|}
 
 
:<h4 style="border-bottom:1px solid black;">DefaultCallingCode</h4>
::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. For more information on country calling codes, please see: https://en.wikipedia.org/wiki/List_of_country_calling_codes.
 
::{| class="alternate01 sortable"
!Option Name !! Parameter
|-
|'''DefaultCallingCode'''||<code>Country Calling Code</code>
|}
 
 
:<h4 style="border-bottom:1px solid black;">ENABLEBATCHSUGGESTION (Batch Mode Only)</h4>
::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.
 
::{| class="alternate01 sortable"
!Option Name !! Parameter !! Description
|-
|rowspan="2"|'''ENABLEBATCHSUGGESTION'''||False||'''''Default.''''' Suggestions Engine off.
|-
|True||Enables records to be corrected using the suggestions engine when there is exactly only 1 suggestion found.
|}
 
 
:<h4 style="border-bottom:1px solid black;">TimeToWait</h4>
::Determines how long the service takes to query a phone number for Premium or CallerID, before it decides to time out.
 
::Time to wait in seconds. Minimum value is 1, maximum value is 30.
 
::{| class="alternate01 sortable"
!Option Name !! Parameter !! Description
|-
|'''TimeToWait'''||(Time in seconds)||'''''Default is 2.''''' Time to wait in seconds.
|}
 
 
:<h4 style="border-bottom:1px solid black;">VerifyPhone</h4>
::VerifyPhone sets the level of verification to be done on a phone check.
 
::{| class="alternate01 sortable"
!Option Name !! Parameter !! Description
|-
|rowspan="2"|'''VerifyPhone'''||<code>Express</code>||'''''Default.''''' Quickly validates against a database of known phone numbers.
|-
|-
|REST||?opt = {string}
|<code>Premium</code>||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.
|}
|}


Line 100: Line 176:
!Protocol !! Syntax
!Protocol !! Syntax
|-
|-
|JSON||“RecordID”:”string”
|JSON||<code>"RecordID":"'''''string'''''"</code>
|}
|}


Line 107: Line 183:
:''Required.''
:''Required.''


:The phone number to be verified
:The phone number to be verified.


:{| class="alternate01"
:{| class="alternate01"
!Protocol !! Syntax
!Protocol !! Syntax
|-
|-
|JSON||“PhoneNumber”:”string”
|JSON||<code>"PhoneNumber":"'''''string'''''"</code>
|-
|-
|REST||&phone = {string}
|REST||<code>&phone = '''''string'''''</code>
|}
|}


Line 129: Line 205:
!Protocol !! Syntax
!Protocol !! Syntax
|-
|-
|JSON||“Country”:”string”
|JSON||<code>"Country":"'''''string'''''"</code>
|-
|-
|REST||&ctry = {string}
|REST||<code>&ctry = '''''string'''''</code>
|}
|}


Line 145: Line 221:
!Protocol !! Syntax
!Protocol !! Syntax
|-
|-
|JSON||“CountryOfOrigin”:”string”
|JSON||<code>"CountryOfOrigin":"'''''string'''''"</code>
|-
|-
|REST||&ctryOrg = {string}
|REST||<code>&ctryOrg = '''''string'''''</code>
|}
|}


Latest revision as of 23:37, 26 February 2024

← Global Phone

Global Phone Navigation
Introduction
Licensing
Input/Output
Request Fields
Response Fields
Examples
REST JSON
Batch JSON
Result Codes
Result Code Use
Global Phone Result Codes
Sample Code



A request consists of a protocol to make a call to the service, detailing desired elements. The minimum required elements in a request are your Customer ID (License Key) and at least one input phone number. Though not required, an input country name will greatly increase the chances of recognizing and verifying the phone number in question.

Global Phone supports REST and JSON protocols.


URL

REST and JSON

Use URL
Standard http://globalphone.melissadata.net/v4/WEB/GlobalPhone/doGlobalPhone
Secure https://globalphone.melissadata.net/v4/WEB/GlobalPhone/doGlobalPhone


Field Names

This is a list of the request field names and their protocol naming conventions.

Field Name Level REST JSON
Transmission Reference Request t TransmissionReference
License Key id CustomerID
Options opt Options
Record ID Record RecordID
Phone Number phone PhoneNumber
Country ctry Country
Country Of Origin ctryOrg CountryOfOrigin


Request Elements

The following elements set the basic options for each request. These apply to the entire request, not the individual records.

Transmission Reference

Optional.
This is a string value that serves as a unique identifier for this set of records. It is returned as sent.
Protocol Syntax
JSON "TransmissionReference":"string"
REST ?t = string


License Key

Required.
This is a string value containing the License Key issued to the customer by Melissa Data for Global Phone.
If this element is absent, the Web Service will return an error. To receive a License Key, please contact your Melissa Data sales representative at 1-800-MELISSA.
Protocol Syntax
JSON "CustomerID":"string"
REST &id = string


Options

Optional.
This is a string value containing the options set by the user.
Protocol Syntax
JSON "Options":"string"
REST ?opt = string
List options in the following format, with multiple options delimited with a ",".
Syntax
OptionName:Parameter,OptionName:Parameter


CallerID

US and Canada Only.
Returns the name or association linked to the phone number at the time of registration, if available.
Option Name Parameter Description
CallerID False Default. CallerID is turned off.
True Adds the CallerID to the queried phone, if we found it to be valid.


DefaultCallingCode

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. For more information on country calling codes, please see: https://en.wikipedia.org/wiki/List_of_country_calling_codes.
Option Name Parameter
DefaultCallingCode Country Calling Code


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.
Option Name Parameter Description
ENABLEBATCHSUGGESTION False Default. Suggestions Engine off.
True Enables records to be corrected using the suggestions engine when there is exactly only 1 suggestion found.


TimeToWait

Determines how long the service takes to query a phone number for Premium or CallerID, before it decides to time out.
Time to wait in seconds. Minimum value is 1, maximum value is 30.
Option Name Parameter Description
TimeToWait (Time in seconds) Default is 2. Time to wait in seconds.


VerifyPhone

VerifyPhone sets the level of verification to be done on a phone check.
Option Name Parameter Description
VerifyPhone 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.


Request Record Elements

JSON will only contain the Records element.

Protocol Definition
JSON Each phone number will be contained within [{}] under the Records element.
REST The REST interface only allows a single record per request.


RecordID

Optional.
This is a string value containing a unique identifier for the current record. Use this to match the record submitted with the record returned. It will return what is inputted.
Protocol Syntax
JSON "RecordID":"string"


PhoneNumber

Required.
The phone number to be verified.
Protocol Syntax
JSON "PhoneNumber":"string"
REST &phone = string


Country

Optional.
The suspected country of the input phone number.
The service accepts the official country name or the ISO2 code.
Some territories will require a different ISO2 code than the one that is given to them. For more information, please see the FAQ.
Protocol Syntax
JSON "Country":"string"
REST &ctry = string


CountryOfOrigin

Optional.
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 origin.
The service accepts the official country name or the ISO2 code. Some territories will require a different ISO2 code than the one that is given to them. For more information, please see the FAQ.
Protocol Syntax
JSON "CountryOfOrigin":"string"
REST &ctryOrg = string
Retrieved from "http://wiki.melissadata.com/index.php?title=Global_Phone:Request&oldid=20005"