Reference Guide

Introduction

WebSmart Phone Verifier allows Web sites and custom applications to verify phone numbers down to 7 and 10 digits, update area codes, and append data about the phone number.

Use Phone Verifier to:

• Verify U.S. or Canadian phone numbers down to 7 or 10 digits.

• Update the area code if it changed in the last year.

• Append data on the telephone line, distinguishing between landline, wireless numbers, or Voice Over IP (VOIP).

• Append data on the telephone owner, distinguishing between residential, business, or home office numbers.

• Parse the phone number into its components.

Service URLs

Protocol	URL
SOAP	https://phonecheck.melissadata.net/v2/soap/service.svc
SOAP:WSDL	https://phonecheck.melissadata.net/v2/soap/service.svc?wsdl
SOAP:Flat WSDL	https://phonecheck.melissadata.net/v2/soap/service.wsdl
XML	https://phonecheck.melissadata.net/v2/xml/service.svc
REST	https://phonecheck.melissadata.net/v2/rest/service.svc

Sample Code

• REST VBScript

• SOAP CSharp8

• SOAP PHP

• XML ASP

• XML VBScript

Adding Phone Verifier to a Project

If you are using the SOAP service with Visual Studio.NET, you need to add a web reference to the service to your project. Click on the Project menu and select Add Web Reference.... Enter the following URL on the Add Web Reference dialog box:

https://phonecheck.melissadata.net/v2/SOAP/Service.svc

If you are not using Visual Studio.NET, see the documentation for your SOAP interface for the procedure for adding the service to your project. Submitting an XML Request After building your XML string from your data, an XML request to the web service is submitted using an HTTP POST operation to the following URL:

https://phonecheck.melissadata.net/v2/XML/Service.svc/DoPhoneCheck

Building a REST Request

Query strings are sent to the web service as part of the URL using an HTTP Get operation appended to following URL:

https://phonecheck.melissadata.net/v2/REST/Service.svc/doPhoneCheck

Phone Verifier Request

At the very minimum, a request to the WebSmart Phone Verifier consists of the user’s Customer ID and a phone number.

SOAP Request

The following Visual Basic Code shows a simple order of operations for building and submitting a RequestArray object, submitting it to the Web Service and retrieving a response object.

Step 1 – Create the Request and Response Objects

Dim ReqPhoneCheck As New dqwsPhoneCheck.RequestArray
Dim ResPhoneCheck As New dqwsPhoneCheck.ResponseArray

Step 2 – Assign the General Field Values

There are two properties of the Request Array object that apply to the request as a whole. CustomerID is required.

ReqPhoneCheck.CustomerID = strCustID
ReqPhoneCheck.TransmissionReference = strTranRef

The Transmission Reference is a unique string value that identifies this request array.

Step 3 – Dimension the Record Array

The maximum number of records per request is 100, therefore the largest dimension will be 99.

ReDim ReqPhoneCheck.Record(99)

For maximum efficiency, you should dimension the array using the exact number of records being submitted minus one.

Step 4 – Build the Record Array

The exact method for building the array will depend on the exact database software in use, but you will need to loop through every record to be submitted and assign the required values to the corresponding fields for each record in the RequestArray.

ReqPhoneCheck.Record(intRecord) = New dqwsPhoneCheck.RequestArrayRecord
ReqPhoneCheck.Record(intRecord).Phone = "9495895200"

The lines above show only the fields that are absolutely required to submit a record to the web service.

Repeat for each record being submitted with the current RequestArray.

Step 5 – Submit the Request Array

The final step is to create the Service Client Object and then submit the RequestArray object doPhoneCheck method. This sends the data to the web service and retrieves the ResponseArray object.

PhoneCheckClient = New dqwsPhoneCheck.Service
ResPhoneCheck = PhoneCheckClient.doPhoneCheck(ReqPhoneCheck)

XML Request

The raw XML request is built using whatever XML tools are available via your development tools and submitted to the following URL using an HTTP POST request.

https://phonecheck.melissadata.net/v2/XML/Service.svc/doPhoneCheck

Rather than an array of Record objects, an XML request contains a <Record> element for each address record, up to 100.

The following XML Code contains the same request as the SOAP example above.

<?xml version="1.0" ?>
<RequestArray xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <TransmissionReference xmlns="urn:mdWebServicePhoneCheck">Test</TransmissionReference>
  <CustomerID xmlns="urn:mdWebServicePhoneCheck">XXXXXXXX</CustomerID>
  <Record xmlns="urn:mdWebServicePhoneCheck">
    <Phone>9495895200</Phone>
  </Record>
</RequestArray>

REST Request

A REST request can submit a single address record via an HTTP GET. The following example uses the same address as the SOAP and XML samples.

https://phonecheck.melissadata.net/v2/REST/Service.svc/doPhoneCheck?id=12345678&t=RestTest&phone=9495895200

The record ID field does not exist for the REST interface, since you can only submit a single record per request.

Request Fields

The following section lists the fields that set the basic options for each and identify the user to the Web Service.

Customer ID

This is a required string value containing the identifier number issued to the customer when signing up for Melissa Data WebSmart Services.

You need a customer ID to access any Melissa Data Web Service. If this field is not populated, the web service will return an error. To receive a customer ID, call your Melissa Data sale representative.

SOAP

Request.CustomerID = string

XML

<RequestArray>
  <CustomerID>String</CustomerID>
</RequestArray>

REST

id={CustomerID}

Transmission Reference

This is an optional string value that may be passed with each Request Array to serve as a unique identifier for this set of records.

This value is returned as sent by the Response Array, allowing you to match the Response to the Request.

SOAP

Request.TransmissionReference = string

XML

<RequestArray>
  <TransmissionReference>String</TransmissionReference>
</RequestArray>

REST

t={transMissionReference}

Record Fields

For the SOAP and XML web services, the Request Array will contain an element or property called Record. In SOAP this property is an array of object variables of the type Record. XML will have as many Record elements as there are phone numbers being submitted to the web service.

The REST interface only allows a single record per request.

Record ID

This field is a string value containing a unique identifier for the current record.

Use this field to match the record with the record returned with the Response Array.

When using the SOAP interface, if this field is not populated, the web service will automatically insert a sequential number for each record.

There is no equivalent for Record ID for the REST interface.

SOAP

Request.Record().RecordID = string

XML

<RequestArray>
  <Record>
    <RecordID>String</RecordID>
  </Record>
</RequestArray>

Phone

This field is a required ten-character string value containing the phone number to be verified.

The phone number should be ten characters long and include only the digits of the phone number; no parentheses, dashes or spaces.

SOAP

Request.Record().Phone = string

XML

<RequestArray>
  <Record>
    <Phone>String</Phone>
  </Record>
</RequestArray>

REST

phone={PhoneNumber}

Phone Verifer Response

The SOAP interface for the Phone Verifer service returns a ResponseArray Object. The primary component of this object is an array of Record objects, one for each record submitted with the RequestArray, containing the parsed and verified phone data.

The XML interface returns an XML document containing a number of <Record> elements, one for each record submitted with the Request, containing the parsed and verified phone data.

The REST interface returns an XML document with a single <Record> element.

TransmissionReference

Returns a string value containing the contents of the TransmissionReference field from the original Request.

If you passed any value to the TransmissionReference field when building your request, it is returned here. You can use this property to match the response to the request.

SOAP

string = Response.TransmissionReference

XML

<ResponseArray>
  <TransmissionReference>String</TransmissionReference>
</ResponseArray>

Total Records

Returns a string value containing the number records returned with the current response.

This property returns the number of records processed and returned by the response as a string value.

SOAP

string = Response.TotalRecords

XML

<ResponseArray>
  <TotalRecords>String</TotalRecords>
</ResponseArray>

Results

Returns a string value containing the general and system error messages from the most recent request sent to the service.

This field returns error messages caused by the most recent request as a whole.

For a list of these codes, see Phone Verifier - Service Level Result Codes.

SOAP

string = Response.Results

XML

<ResponseArray>
  <Results>String</Results>
</ResponseArray>

Version

Returns a string value containing the current version number of the Phone Verifer web service.

SOAP

string = Response.Version

XML

<ResponseArray>
  <Version>String</Version>
</ResponseArray>

Record Fields

The SOAP version of the Response Array returns a property called Record which is an array of Record objects, one for each record submitted with the original Request Array.

The XML service returns one <Record> element for every record submitted with the original request.

The REST response is identical to the XML response, but will only contain a single <Record> element since it only allows single requests.

The following section describes the fields returned by each record in the Response Array.

Record ID

For each record in the Response Array, this field returns a string value containing the unique identifier for the current record if one was passed to the Request Array.

Use this field to match the record in the Response Array with the record originally passed with the request.

SOAP

string = Response.Record().RecordID

XML

<ResponseArray>
  <Record>
    <RecordID>String</RecordID>
  </Record>
</ResponseArray>

Results

For each record in the Response Array, this field returns a string value containing status and error codes for the current record. Multiple codes are separated by commas.

This field returns the status and error messages for each record in the Response Array.

The Result field may return one or more four-character strings, separated by commas, depending on the result generated by the current record.

If the address in the current record was verified, this field will contain the value PS01 or PS02 at the very minimum and may include more of the PS codes. If the address could not be verified, the codes beginning with P will indicate the reason or reasons why verification failed.

For a list of these codes, see Phone Verifier - Record Level Result Codes.

SOAP

string = Response.Record().Results

XML

<ResponseArray>
  <Record>
    <Results>String</Results>
  </Record>
</ResponseArray>

Area Code

For each record in the Response Array, this field returns a string value containing the original area code from the submitted phone number.

If there are not enough digits for the area code, this field will be empty. If the area code/prefix combination has been split, the new area code will be returned by the NewAreaCode field.

SOAP

string = Response.Record().Phone.AreaCode

XML

<ResponseArray>
  <Record>
    <Phone>
      <AreaCode>String</AreaCode>
    </Phone>
  </Record>
</ResponseArray>

New Area Code

For each record in the Response Array, this field returns a string value containing the new area code for the submitted phone number, if the submitted area code has recently undergone a split.

The New Area Code field will return an updated area code based on the submitted phone number.

An updated area code is a new area code that is based on the input of an area code/prefix combination that has been split. If no new area code was found, then this field will be empty.

SOAP

string = Response.Record().Phone.NewAreaCode

XML

<ResponseArray>
  <Record>
    <Phone>
      <NewAreaCode>String</NewAreaCode>
    </Phone>
  </Record>
</ResponseArray>

Prefix

For each record in the Response Array, this field returns a string value containing the prefix (first three digits after the area code) of the submitted phone number.

The prefix or exchange is the three-digit portion of the phone number that immediately follows the area code.

SOAP

string = Response.Record().Phone.Prefix

XML

<ResponseArray>
  <Record>
    <Phone>
      <Prefix>String</Prefix>
    </Phone>
  </Record>
</ResponseArray>

Suffix

For each record in the Response Array, this field returns a string value containing the suffix (last four digits) of a submitted phone number.

The suffix is the last four digits of the phone number.

SOAP

string = Response.Record().Phone.Suffix

XML

<ResponseArray>
  <Record>
    <Phone>
      <Suffix>String</Suffix>
    </Phone>
  </Record>
</ResponseArray>

Extension

For each record in the Response Array, this field returns a string value containing the extension information, if any, of a submitted phone number.

If the submitted phone number did not contain an extension, this field will be blank.

SOAP

string = Response.Record().Phone.Extension

XML

<ResponseArray>
  <Record>
    <Phone>
      <Extension>String</Extension>
    </Phone>
  </Record>
</ResponseArray>

City

Note

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.

For each record in the Response Array, this field returns a string value containing the name of the city associated with the submitted phone number.

SOAP

string = Response.Record().Phone.City

XML

<ResponseArray>
  <Record>
    <Phone>
      <City>String</City>
    </Phone>
  </Record>
</ResponseArray>

State

Note

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.

For each record in the Response Array, this field returns a string value containing the name of the state associated with the submitted phone number.

SOAP

string = Response.Record().Phone.State

XML

<ResponseArray>
  <Record>
    <Phone>
      <State>String</State>
    </Phone>
  </Record>
</ResponseArray>

Country

Note

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.

For each record in the Response Array, these two fields return string values containing the full name and abbreviation for the country, either the United States or Canada, associated with the submitted phone number.

The possible values for Country Code are US or CA. The possible values for Country Name are United States of America or Canada.

SOAP

string = Response.Record().Phone.Country.Abbreviation
string = Response.Record().Phone.Country.Name

XML

<ResponseArray>
  <Record>
    <Phone>
      <Country>
        <Abbreviation>String</Abbreviation>
        <Name>String</Name>
      </Country>
    </Phone>
  </Record>
</ResponseArray>

Latitude

Note

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.

For each record in the Response Array, this field returns a string value containing the latitude of the NPA/NXX wire center for the submitted phone number.

SOAP

string = Response.Record().Phone.Latitude

XML

<ResponseArray>
  <Record>
    <Phone>
      <Latitude>String</Latitude>
    </Phone>
  </Record>
</ResponseArray>

Longitude

Note

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.

For each record in the Response Array, this field returns a string value containing the longitude of the NPA/NXX wire center for the submitted phone number.

SOAP

string = Response.Record().Phone.Longitude

XML

<ResponseArray>
  <Record>
    <Phone>
      <Longitude>String</Longitude>
    </Phone>
  </Record>
</ResponseArray>

TimeZone

Note

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.

For each record in the Response Array, these fields return string values containing the name and numeric code for the time zone associated with the submitted phone number.

For a list of these codes, see Phone Verifier - Service Level Result Codes.

SOAP

string = Response.Record().Phone.TimeZone.Code
string = Response.Record().Phone.TimeZone.Name

XML

<ResponseArray>
  <Record>
    <Phone>
      <TimeZone>
        <Code>String</Code>
        <Name>String</Name>
      </TimeZone>
    </Phone>
  </Record>
</ResponseArray>

Response Object XML Format

The following shows the structure of the XML document returned by the Phone Verifer Service.

<?xml version="1.0" ?>
<ResponseArray xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Version xmlns="urn:mdWebServicePhoneCheck">2.0.18</Version>
  <TransmissionReference xmlns="urn:mdWebServicePhoneCheck">Test</TransmissionReference>
  <Results xmlns="urn:mdWebServicePhoneCheck" />
  <TotalRecords xmlns="urn:mdWebServicePhoneCheck">1</TotalRecords>
  <Record xmlns="urn:mdWebServicePhoneCheck">
    <RecordID>1</RecordID>
    <Results>PS01,PS08,PS11</Results>
    <Phone>
      <AreaCode>949</AreaCode>
      <Prefix>589</Prefix>
      <Suffix>5200</Suffix>
      <Extension />
      <NewAreaCode />
      <Latitude>33.635101</Latitude>
      <Longitude>-117.599602</Longitude>
      <City>Trabuco Canyon</City>
      <State>CA</State>
      <Country>
        <Abbreviation>US</Abbreviation>
        <Name>United States of America</Name>
      </Country>
      <TimeZone>
        <Name>Pacific Time</Name>
        <Code>08</Code>
      </TimeZone>
    </Phone>
  </Record>
</ResponseArray>