Reference Guide

Reference Guide#

Introduction #

The WebSmart Name Parser automates the handling of name data, making it simple to send personalized business mail, tailored specifically to the gender of the people in your mailing list, while screening out vulgar or obviously false names.

Parse full names into first, middle and last names, as well as prefixes like Dr. and suffixes like Jr..
Handle name strings that include two names, such as John and Mary Jones.
Correct misspelled first names.
Flag vulgar names and names that are obviously false, such as Bugs Bunny.
Assign gender based on the first name.
Select how aggressively Name Parser determines the gender of names, based on the known gender bias of the mailing list, if any.
Create personalized salutations for business mail.

Service URLs #

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

Sample Code #

Adding WebSmart Name Parser 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://name.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://name.melissadata.net/v2/XML/Service.svc/doNameCheck

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://name.melissadata.net/v2/REST/Service.svc/doNameCheck

Many modern programming language have a URL encode and URL decoding function that automates these character replacements.

Name Parser Request #

At the very minimum, a request to the WebSmart Name Parser consists of the user’s Customer ID and at least one full name.

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 ReqName Parser As New dqwsName Parser.RequestArray
Dim ResName Parser As New dqwsName Parser.ResponseArray

Step 2 – Assign the General Request Values

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

ReqName Parser.CustomerID = strCustID
ReqName Parser.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 ReqName Parser.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 elements for each record in the RequestArray.

ReqName Parser.Record(intRecord) = New dqwsName Parser.RequestArrayRecord
ReqName Parser.Record(intRecord).FullName = "John Q. Smith"

The lines above show only the elements 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 doNameCheck method. This sends the data to the web service and retrieves the ResponseArray object.

Name ParserClient = New dqwsName Parser.Service
ResName Parser = Name ParserClient.doNameCheck(ReqNameParser)
Name ParserClient.Dispose()

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://name.melissadata.net/v2/XML/Service.svc/doNameCheck

Rather than an array of Record object, 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:mdWebServiceName">Test</TransmissionReference>
  <CustomerID xmlns="urn:mdWebServiceName">XXXXXXXX</CustomerID>
  <OptCorrectSpelling xmlns="urn:mdWebServiceName" />
  <OptNameHint xmlns="urn:mdWebServiceName" />
  <OptGenderAggression xmlns="urn:mdWebServiceName" />
  <OptGenderPopulation xmlns="urn:mdWebServiceName" />
  <OptSalutationPrefix xmlns="urn:mdWebServiceName">Dear</OptSalutationPrefix>
  <OptSalutationSuffix xmlns="urn:mdWebServiceName">,</OptSalutationSuffix>
  <OptSalutationSlug xmlns="urn:mdWebServiceName">Valued Customer</OptSalutationSlug>
  <Record xmlns="urn:mdWebServiceName">
    <FullName>Ray Melissa</FullName>
  </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://name.melissadata.net/v2/REST/Service.svc/doNameCheck?id=12345678&t=RestTest&Name=Raymond%20F.%20Melissa

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

Request Elements #

The following section lists the elements that set the basic options for each and identify the user to the web service.

CustomerID #

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

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

SOAP#

Request.CustomerID = string

XML#

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

REST#

id={CustomerID}

TransmissionReference #

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}

OptCorrectSpelling #

Enables or disables spelling correction of first names during parsing.

The Name Parser uses a database of common misspelled first name names to correct the values of the First Name properties.

Set this property to true to enable this feature. Set it to false to disable.

SOAP#

Request.OptCorrectSpelling = string

XML#

<RequestArray>
  <OptCorrectSpelling>True or False</OptCorrectSpelling>
</RequestArray>

REST#

OptSpelling={OptCorrectSpelling}

OptGenderAggression #

Sets how aggressively Name Parser will attempt to genderize neutral first names.

Normally, Name Parser will assign a value of “N” when attempting to genderize a first name that can easily be male or female, such as Pat, Chris, or Tracy. Every name is assigned a score from 7 to 1, with 7 being always male, 4 being completely neutral and 1 being always female.

Using this property in conjunction with the optGenderPopulation element, you can instruct Name Parser how much preference it gives to one gender or the other when assigning a gender to a normally neutral name. This property can accept the following values.

Parameter Code	Parameter Name	Description
`1`	Aggressive	Aggressive name genderizing.
`2`	Neutral	Default. Neutral name genderizing.
`3`	Conservative	Conservative name genderizing.

The default value is 2.

This table shows how the settings for Gender Aggression and Gender Population affect genderizing:

Male					Female
Aggression	Always (7)	Often (6)	Normally (5)	Neutral (4)	Normally (3)	Often (2)	Always (1)
Conservative Bias
Neutral	M	N	N	N	N	N	F
Male	M	M	N	N	N	N	F
Female	M	N	N	N	N	F	F
Neutral Bias
Neutral	M	M	N	N	N	F	F
Male	M	M	M	N	N	F	F
Female	M	M	N	N	F	F	F
Aggressive Bias
Neutral	M	M	M	N	F	F	F
Male	M	M	M	M	N	F	F
Female	M	M	N	F	F	F	F

SOAP#

Request.OptGenderAggression = string

XML#

<RequestArray>
  <OptGenderAggression>integer</OptGenderAggression>
</RequestArray>

REST#

OptGndAggr={OptGenderAggression}

OptGenderPopulation #

Sets the gender balance of the source data, either predominantly male, predominant female or neutral.

If you know that a mailing will be comprised of predominantly one gender or the other, meaning that gender-neutral will likely be of that gender, use this property to set the gender bias to use when genderizing names, either via the Parse or Genderize methods.

Gender Population contains an enumerated value. The possible values for this property are:

The default value is 2.

Parameter Code	Description
`1`	Bias towards Male.
`2`	Default. Evenly slit.
`3`	Bias towards Female.

SOAP#

Request.OptGenderPopulation = string

XML#

<RequestArray>
  <OptGenderPopulation>Integer</OptGenderPopulation>
</RequestArray>

REST#

OptGndPop={OptGenderAggression}

OptNameHint #

Sets an integer value indicating the most likely format of the FullName string.

This setting helps the Name Parser in cases when the order and formatting of the FullName string are unclear.

Full or normal name order is <Prefix> <First> <Middle> <Last> <Suffix>.

Inverse name order is <Last> <Suffix>, <Prefix> <First> <Middle>.

The default is 4 (Varying).

The possible values are:

Parameter Code	Parameter Name	Description
`1`	DefinitelyFull	Name will always be treated as normal name order, regardless of formatting or punctuation.
`2`	VeryLikelyFull	Name will be treated as normal name order unless inverse order is clearly indicated by formatting or punctuation.
`3`	ProbablyFull	If necessary, statistical logic will be employed to determine name order, with a bias toward normal name order.
`4`	Varying	If necessary, statistical logic will be employed to determine name order, with not bias toward either name order.
`5`	ProbablyInverse	If necessary, statistical logic will be employed to determine name order, with a bias toward inverse name order.
`6`	VeryLikelyInverse	Name will be treated as inverse name order unless normal order is clearly indicated by formatting or punctuation.
`7`	DefinitelyInverse	Name will always be treated as inverse name order, regardless of formatting or punctuation.
`8`	MixedFirstName	Name element is expected to only contain first names.
`9`	MixedLastName	Name element is expected to only contain last names.

SOAP#

Request.OptNameHint = string

XML#

<RequestArray>
  <OptNameHint>inte</OptNameHint>
</RequestArray>

REST#

OptHint={OptNameHint}

OptSalutationPrefix #

Accepts a string value and sets the text preceding the name for salutations generated by the web service.

This property lets you set the preferred text that you want before the proper name in salutations generated by the web service. The default = ``Dear ``

SOAP#

Request.OptSalutationPrefix = string

XML#

<RequestArray>
  <OptSalutationPrefix>String</OptSalutationPrefix>
</RequestArray>

REST#

OptSalPrfx={OptSalutationPrefix}

OptSalutationSlug #

Accepts a string value and sets the text that will be substituted for a name into salutations generated by the web service, when no parsed or parseable name are present in the required properties.

If the value of the FullName property cannot be parsed by the DoParse action, this string will be substituted for the name.

The default value is Valued Customer.

SOAP#

Request.OptSalutationSlug = string

XML#

<RequestArray>
  <OptSalutationSlug>String</OptSalutationSlug>
</RequestArray>

REST#

OptSalSlug={OptSalutationSlug}

OptSalutationSuffix #

Accepts a string value and sets the text that follows the name for salutations generated by the web service.

This property lets you set the preferred text that you want after the proper name in salutations generated by the web service. The default = ;

Record Elements #

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 addresses being submitted to the web service.

The REST interface only allows a single record per request.

Request.OptSalutationSuffix = string

<RequestArray>
  <OptSalutationSuffix>String</OptSalutationSuffix>
</RequestArray>

OptSalSffx={OptSalutationSuffix}

RecordID #

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

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

When using the SOAP interface, if this element 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>

FullName #

This element must contain at least one full personal name.

This element can contain one or two full names.

SOAP#

Request.Record().FullName = string

XML#

<RequestArray>
  <Record>
    <FullName>String</FullName>
  </Record>
</RequestArray>

REST#

name={FullName}

Name Parser Response #

The SOAP interface for the Name Parser 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 verified and standardized address data.

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

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

TransmissionReference #

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

If you passed any value to the TransmissionReference element 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 of 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 element returns error messages caused by the most recent request as a whole.

For a list of these codes, see Name Parser - 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 Name Parser web service.

SOAP#

string = Response.Version

XML#

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

Record Elements #

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.

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

Record ID #

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

Use this element 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 element returns a string value containing status and error codes for the current record. Multiple codes are separated by commas.

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

The Result element 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 element will contain the value NS01 at the very minimum and may include more of the NS codes. If the address could not be verified, the codes beginning with NE will indicate the reason or reasons why verification failed.

For a list of these codes, see Name Parser - Record Level Result Codes.

SOAP#

string = Response.Record().Results

XML#

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

First Property #

Returns the first name from a full name passed to the Request Array.

This property will return the first name of any name passed to the Request Array. If the named only contained a single name, a single first name will be returned here. If two names were parsed, the first of the two first names will be returned by this property.

SOAP#

string = Response.Record().Name.First

XML#

<ResponseArray>
  <Record>
    <Name>
      <First>String</First>
    </Name>
  </Record>
</ResponseArray>

First2 #

Returns the second first name from a full name passed to the Request Array.

This property will return the second first name, if two names were passed to the Request Array.

SOAP#

string = Response.Record().Name.First2

XML#

<ResponseArray>
  <Record>
    <Name>
      <First2>String</First2>
    </Name>
  </Record>
</ResponseArray>

Gender #

Returns the gender of the name passed to the Request Array.

This property returns a one-character string indicating the gender of the first name found in the FullName element passed to the Request Array.

The possible values returned by this property are:

Code	Description
`F`	Female
`M`	Male
`N`	A neutral first name
`U`	Unknown first name or no first name present

SOAP#

string = Response.Record().Name.Gender

XML#

<ResponseArray>
  <Record>
    <Name>
      <Gender>String</Gender>
    </Name>
  </Record>
</ResponseArray>

Gender2 #

Returns the gender of any second first name if a dual name was passed to the Request Array.

This property returns a one-character string indicating the gender of any second first name found in the full name property passed to the Request Array.

The possible values returned by this property are the same as for the Gender property.

SOAP#

string = Response.Record().Name.Gender2

XML#

<ResponseArray>
  <Record>
    <Name>
      <Gender2>String</Gender2>
    </Name>
  </Record>
</ResponseArray>

Last #

Returns the last name from a full name passed to the Request Array.

This property will return the last name from a name passed to the Request Array. If the FullName property only contained a single name, the last name will be returned here. If two names were parsed, the first of the two last names will be returned by this property.

SOAP#

string = Response.Record().Name.Last

XML#

<ResponseArray>
  <Record>
    <Name>
      <Last>String</Last>
    </Name>
  </Record>
</ResponseArray>

Last2 #

Returns the second last name from a dual name passed to the Request Array.

This property will return the second last name, if the Full Name passed to the Request Array contained two names.

SOAP#

string = Response.Record().Name.Last2

XML#

<ResponseArray>
  <Record>
    <Name>
      <Last2>String</Last2>
    </Name>
  </Record>
</ResponseArray>

Middle #

Returns the first middle name from a full name passed to the Request Array.

This property will return the middle name from the name passed to the Request Array. If the full fame only contained a single name, the middle name, if any, will be returned here. If two names were parsed, the first of the two middle names will be returned by this property.

SOAP#

string = Response.Record().Name.Middle

XML#

<ResponseArray>
  <Record>
    <Name>
      <Middle>String</Middle>
    </Name>
  </Record>
</ResponseArray>

Middle2 #

Returns the second middle name from a dual name passed to the Request Array.

This property will return the second middle name, if the Full Name passed to the Request Array contained two names.

SOAP#

string = Response.Record().Name.Middle2

XML#

<ResponseArray>
  <Record>
    <Name>
      <Middle2>String</Middle2>
    </Name>
  </Record>
</ResponseArray>

Prefix #

Returns the first prefix (such as “Mr.” or “Dr.”) from a full name passed to the Request Array.

This property will return the prefix from a name passed to the Request. If the Full Name property only contained a single name, the prefix, if any, will be returned here. If two names were parsed, the first of the two prefixes will be returned by this property.

SOAP#

string = Response.Record().Name.Prefix

XML#

<ResponseArray>
  <Record>
    <Name>
      <Prefix>String</Prefix>
    </Name>
  </Record>
</ResponseArray>

Prefix2 #

Returns the second prefix (such as “Mr.” or “Dr.”) from a full name passed to the Request Array.

This property will return the second prefix from a full name passed to the Request Array, if the name contained two names.

SOAP#

string = Response.Record().Name.Prefix2

XML#

<ResponseArray>
  <Record>
    <Name>
      <Prefix2>String</Prefix2>
    </Name>
  </Record>
</ResponseArray>

Salutation #

Returns a generated salutation string for the name passed to the Request Array.

Returns the contents of the salutation string generated according to the preferences set by OptSalutationPrefix, OptSalutationSlug and OptSalutationSuffix properties of the Request Array.

SOAP#

string = Response.Record().Name.Salutation

XML#

<ResponseArray>
  <Record>
    <Name>
      <Salutation>String</Salutation>
    </Name>
  </Record>
</ResponseArray>

Suffix #

Returns the first suffix (such as “Jr.” or “III.”) from a full name passed to the Request Array.

This property will return the suffix from a full name passed to the Request Array. If the full name only contained a single name, the suffix of the first name, if any, will be returned here. If two names were parsed, the first of the two suffixes will be returned by this property.

SOAP#

string = Response.Record().Name.Suffix

XML#

<ResponseArray>
  <Record>
    <Name>
      <Suffix>String</Suffix>
    </Name>
  </Record>
</ResponseArray>

Suffix2 #

Returns the second suffix (such as “Sr.” or “IV.”) from a full name passed to the Request Array.

This property will return the second suffix from a dual name passed to the Request Array, if the full name property contained two names.

SOAP#

string = Response.Record().Name.Suffix2

XML#

<ResponseArray>
  <Record>
    <Name>
      <Suffix2>String</Suffix2>
    </Name>
  </Record>
</ResponseArray>

Response Object XML Format #

The following shows the structure of the XML document returned by the Name Parser.

<?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:mdWebServiceName">2.0.19</Version>
  <TransmissionReference xmlns="urn:mdWebServiceName">Test</TransmissionReference>
  <Results xmlns="urn:mdWebServiceName" />
  <TotalRecords xmlns="urn:mdWebServiceName">1</TotalRecords>
  <Record xmlns="urn:mdWebServiceName">
    <RecordID>1</RecordID>
    <Results>NS01,NS05</Results>
    <Name>
      <Prefix />
      <Prefix2 />
      <First>Ray</First>
      <First2 />
      <Middle />
      <Middle2 />
      <Last>Melissa</Last>
      <Last2 />
      <Suffix />
      <Suffix2 />
      <Gender>M</Gender>
      <Gender2 />
      <Salutation>Dear Mr. Melissa,</Salutation>
    </Name>
  </Record>
</ResponseArray>

Reference Guide

Contents

Reference Guide#

SOAP#

XML#

REST#

SOAP#

XML#

REST#

SOAP#

XML#

REST#

SOAP#

XML#

REST#

SOAP#

XML#

REST#

SOAP#

XML#

REST#

SOAP#

XML#

REST#

SOAP#

XML#

REST#

SOAP#

XML#

SOAP#

XML#

REST#

SOAP#

XML#

SOAP#

XML#

SOAP#

XML#

SOAP#

XML#

SOAP#

XML#

SOAP#

XML#

SOAP#

XML#

SOAP#

XML#

SOAP#

XML#

SOAP#

XML#

SOAP#

XML#

SOAP#

XML#

SOAP#

XML#

SOAP#

XML#

SOAP#

XML#

SOAP#

XML#

SOAP#

XML#

SOAP#

XML#

SOAP#

XML#