Personator Consumer:Request

← Personator Consumer

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 License Key (Customer ID) and the fields listed as Required below.

Personator allows for inputting data using either discrete/individual columns, or with single string input using Free Form. The web service supports JSON, JSONP, REST, SOAP, and XML protocols.

URL

Protocol	URL
SOAP	https://personator.melissadata.net/v3/SOAP/ContactVerify
REST	https://personator.melissadata.net/v3/WEB/ContactVerify/doContactVerify

Field Names

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

Field Name	REST	JSON/XML
Transmission Reference	t	TransmissionReference
License Key	id	CustomerID
Actions	act	Actions
Columns	cols	Columns
Options	opt	Options
Address Line 1	a1	AddressLine1
Address Line 2	a2	AddressLine2
Age Approximate	ageapprox	AgeApproximate
Age Greater Than	agegt	AgeGreaterThan
Age Less Than	agelt	AgeLessThan
Birth Day	bday	BirthDay
Birth Month	bmo	BirthMonth
Birth Year	byr	BirthYear
City	city	City
Company Name	comp	CompanyName
Country	ctry	Country
Email	email	EmailAddress
First Name	first	FirstName
Format	format	Format
Free Form	ff	Freeform
Full Name	full	FullName
IP Address	ip	IPAddress
Last Line	lastline	LastLine
Last Name	last	LastName
Melissa Address Key	mak	MelissaAddresKey
Melissa Identity Key	MIK	MIK
Phone	phone	PhoneNumber
Postal Code	postal	PostalCode
Record ID		RecordID
Social Security Number	ss	SocialSecurity
State	state	State

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
SOAP/XML	<TransmissionReference>string</TransmissionReference>

License Key

Required.

This is a string value containing the License Key issued to the customer by Melissa for the web service.

If this element is absent, the web service will return an error. To receive a License Key, please contact your Melissa sales representative at 1-800-MELISSA.

Protocol	Syntax
JSON	"CustomerID":"string"
REST	&id = string
SOAP/XML	<CustomerID>string</CustomerID>

Actions

Required.

Specifies the actions. See the actions below for more information.

Protocol	Syntax
JSON	"Actions":"string"
REST	&act = string
SOAP/XML	<Actions>string</Actions>

List actions in the following format, with multiple actions delimited with a ",".

Syntax
Action,Action

Check

The Check action will validate the individual input data pieces for validity and correct them if possible. If the data is correctable, additional information will often be appended as well. US and Canada only.

Action Name	Parameter
Check	Check

Check(Address)

US and Canada only. Check (Address) will only be processed if the following is true: AddressLine1 is not empty Both City and State are not empty or PostalCode is not empty.

AddressLine1 and AddressLine2 Request

AddressLine1 and AddressLine2 may each contain a full address. If both addresses are verified as valid, both are returned as inputted. If AddressLine1 has an invalid address and AddressLine2 has a valid address, the return order is switched. This returns the valid address previously in AddressLine2 into AddressLine1. Conversely, the invalid address in AddressLine1 will be returned in AddressLine2. Alternatively, AddressLine2 may contain a suite number for AddressLine1. The suite information will be cleared from AddressLine2 and placed under its own field in the output.

Geocode

If an address is verifiable, you can choose to geocode it. You will have the geocoding information appended (depending on your license). Geocoding is available for US and Canada.

To use Geocode, you must have the geocode columns on: GrpCensus or GrpGeocode.

Geodetic System

The GeoCoder Object uses WGS 84 standard, an Earth-centered, Earth-fixed terrestrial reference system and geodetic datum.

Geocode level

Your license will determine what geocode level you are allowed. If your license only has address checking enabled, you can geocode to 5 digits. If your license only has GeoCode enabled, you can geocode to 9 digits. If your license has GeoPoints enabled, you can geocode to 11 digits.

Geocode requires the results returned from the Web service.

Check (Phone)

US and Canada only. Check (Phone) will only be processed if the PhoneNumber input has a value.

Check (Email)

US and Canada only. Check (Email) will only be processed if the EmailAddress input has a value.

Check (Name)

US and Canada only. Check (FullName) will only be processed if the FullName or FirstName input has a value.

Verify

The Verify action will return to you the relationships between your different input data pieces. It can show you if your name, address, email, and phone number are correlated (belonging to the same person) or not.

Action Name	Parameter
Verify	Verify

Verify (Address, Phone, Email)

The type of search performed is dependent upon your defined centric piece of information.

Append

The Append action will return elements based on the selected point of centricity which can either be the address, email or phone. For example, an address centric Append will return the name, company, phone and email associated with the given address.

This action isn't allowed for a credit license and will return a GE29 error code.

Action Name	Parameter
Append	Append

Append (Address, Phone, Email)

The appended information is dependent upon your defined centric piece of information.

Move

The Move action will return the latest address for an individual or business if a previous address was entered. Move requires either a Name and Address, or a Business/Company Name and Address as inputs.

Move also returns results codes that help identify which addresses were updated with a move.

This action isn't allowed for a credit license and will return a GE29 error code.

Action Name	Parameter
Move	Move

Columns

Optional.

Specifies which column(s) to be output.

Protocol	Syntax
JSON	"Columns":"string"
REST	&cols = string
SOAP/XML	<Columns>string</Columns>

Entering the column name will return the column. Specifying a group name will return all columns in the group.

List multiple columns in the following format, with multiple options delimited with a ",".

Syntax
ColumnName,ColumnName,ColumnName

Field Name	Group
AddressExtras	[DEFAULT] Returned by default.
AddressKey
AddressLine1
AddressLine2
City
CompanyName
EmailAddress
MelissaAddressKey
MelissaAddressKeyBase
NameFull
PhoneNumber
PostalCode
RecordID
Results
State
DateLastConfirmed	N/A
EstimatedHomeValue
MelissaIdentityKey
MoveDate
Occupation
OwnRent
PhoneCountryCode
PhoneCountryName
Plus4
PrivateMailBox
Suite
AddressTypeCode	GrpAddressDetails
CarrierRoute
CityAbbreviation
CountryCode
CountryName
DeliveryIndicator
DeliveryPointCheckDigit
DeliveryPointCode
StateName
UrbanizationName
UTC
CBSACode	GrpCensus
CBSADivisionCode
CBSADivisionLevel
CBSADivisionTitle
CBSALevel
CBSATitle
CensusBlock
CensusTract
CongressionalDistrict
CountyFIPS
CountyName
PlaceCode
PlaceName
CensusKey	GrpCensus2
CountySubdivisionCode
CountySubdivisionName
ElementarySchoolDistrictCode
ElementarySchoolDistrictName
SecondarySchoolDistrictCode
SecondarySchoolDistrictName
UnifiedSchoolDistrictCode
UnifiedSchoolDistrictName
StateDistrictUpper
StateDistrictLower
Latitude	GrpGeocode
Longitude
ChildrenAgeRange	GrpDemographicBasic Personator Demographics is part of a premium package. Requesting for GrpDemographicBasic will result in outputting multiple demographic columns, which may incur unnecessary charges. To avoid this, please request only for specific demographic columns when not using all the demographics included in this group. These Fields Will NOT Return on a Credit License. The GrpDemographicBasic fields will not return while using a credit license. If you try to use these fields with a credit license, you will instead have a GE29 error code returned.
CreditCardUser
DateOfBirth
DateOfDeath
DemographicsGender
DemographicsResults
Education
EthnicCode
EthnicGroup
HouseholdIncome
HouseholdSize
LengthOfResidence
MaritalStatus
PoliticalParty
PresenceOfChildren
PresenceOfSenior
DistanceAddressToIP	GrpIPAddress
IPAddress
IPCity
IPConnectionSpeed
IPConnectionType
IPContinent
IPCountryAbbreviation
IPCountryName
IPDomainName
IPISPName
IPLatitude
IPLongitude
IPPostalCode
IPProxyDescription
IPProxyType
IPRegion
IPUTC
Gender	GrpNameDetails
Gender2
NameFirst
NameFirst2
NameLast
NameLast2
NameMiddle
NameMiddle2
NamePrefix
NamePrefix2
NameSuffix
NameSuffix2
Salutation
AddressDeliveryInstallation	GrpParsedAddress
AddressHouseNumber
AddressLockBox
AddressPostDirection
AddressPreDirection
AddressPrivateMailboxName
AddressPrivateMailboxRange
AddressRouteService
AddressStreetName
AddressStreetSuffix
AddressSuiteName
AddressSuiteNumber
DomainName	GrpParsedEmail
MailboxName
TopLevelDomain
AreaCode	GrpParsedPhone
NewAreaCode
PhoneExtension
PhonePrefix
PhoneSuffix

Options

Optional.

Specifies the options. See the options below for more information.

Protocol	Syntax
REST	&opt = string

List options in the following format, with multiple options delimited with a ";".

Syntax
OptionName:Parameter;OptionName:Parameter

UsePreferredCity

Check(Address)

For every city in the United States, there is an official name that is preferred by the U.S. Postal Service. There may be one or more unofficial or “vanity” names in use. Normally, Personator allows you to verify addresses using known vanity names. If the usePreferredCity is set to on, Personator will substitute the preferred city name for all vanity names when it verifies an address.

Option Name	Parameter	Description
UsePreferredCity	on	Will substitute the preferred city name for all vanity names.
	off	Default. No substitution will occur.

Diacritics

Check(Address)

Determines whether or not French language characters are returned. If set to auto, those characters are only returned if they are in the input.

Option Name	Parameter	Description
Diacritics	on	Will return diacritics.
	off	No diacritics returned.
	auto	Default. Diacritics only returned if in the input.

AdvancedAddressCorrection

Check(Address)

Uses the name input to perform more advanced address corrections. This can correct or append house numbers, street names, cities, states, and ZIP codes.

Option Name	Parameter	Description
AdvancedAddressCorrection	on	Will use name input to perform advanced address corrections.
	off	Default. No advanced address corrections will occur.

AdvancedAddressType

Check(Address)

This option allows you to select whether to return the simplified address type codes or the advanced and more complete address type codes.

See Address Type codes for the full list of possible codes. There are different codes available depending on AdvancedAddressType being set to either on or off.

Option Name	Parameter	Description
AdvancedAddressType	on	All possible address type codes are returned (US Address Type, Canadian Address Type).
	off	Default. Only Default Address Types are returned (S, G, M, P, R, and U).

LongAddressFormat

Check(Address)

This function controls how Personator handles the abbreviations of suffixes and directionals when standardizing a street address. Setting this option to on will spell out any suffix and directional abbreviations (Ave to Avenue). Setting this option to auto will preserve the suffix and directional as they were entered. In auto mode, if a spelled out “avenue” is entered, we will keep the suffix spelled out and vice versa.

Option Name	Parameter	Description
LongAddressFormat	on	Will spell out suffixes and directional abbreviations.
	off	Default. Will abbreviate suffixes and directionals.
	auto	Will preserve suffixes and directionals as entered.

CorrectSyntax

Check(Email)

If set to on, corrects the syntax of the Email field.

Option Name	Parameter	Description
CorrectSyntax	on	Default. Will correct the syntax of the Email field.
	off	No corrections will occur.

UpdateDomain

Check(Email)

If set to on, determines whether the domain name is out of date and updates it.

Option Name	Parameter	Description
UpdateDomain	on	Default. Will update the domain if it is out of date.
	off	No updates will occur.

DatabaseLookup

Check(Email)

If set to on, verification of domain names will be attempted using a database of valid domains.

Option Name	Parameter	Description
DatabaseLookup	on	Default. Will attempt to verify domain names.
	off	No verification will occur.

StandardizeCasing

Check(Email)

If set to on, changes all letters in the Email field to lower case before any checking occurs.

Option Name	Parameter	Description
StandardizeCasing	on	Default. Will standardize all letters to lower case.
	off	No case changes will occur.

CorrectFirstName

Check(Name)

If set to on, allows common spelling corrections for the FirstName field.

Option Name	Parameter	Description
CorrectFirstName	on	Default. Will perform spelling corrections on the FirstName field.
	off	No spelling corrections will occur.

StandardizeCompany

Check(Name)

If set to on, the CompanyName field will be returned with standard abbreviation, capitalization, and punctuation rules applied.

Option Name	Parameter	Description
StandardizeCompany	on	Default. Will perform standard abbreviation, capitalization, and punctuation on the CompanyName field.
	off	No changes will occur.

NameHint

Check(Name)

Sets the name hint for the input name.

Option Name	Parameter	Description
NameHint	varying	Default. If necessary, statistical logic will be employed to determine name order, with no bias toward either name order.
	definitelyfull	Name will always be treated as normal name order, regardless of formatting or punctuation.
	verylikelyfull	Name will be treated as normal name order unless inverse order is clearly indicated by formatting or punctuation.
	probablyfull	If necessary, statistical logic will be employed to determine name order, with a bias toward normal name order.
	probablyinverse	If necessary, statistical logic will be employed to determine name order, with a bias toward inverse name order.
	verylikelyinverse	Name will be treated as inverse name order unless normal order is clearly indicated by formatting or punctuation.
	definitelyinverse	Name will always be treated as inverse name order, regardless of formatting or punctuation.
	mixedfirstname	Name field is expected to only contain prefixes, first, and middle names.
	mixedlastname	Name field is expected to only contain last names and suffixes.

GenderPopulation

Check(Name)

Sets the gender balance of the source data, either predominantly male, female, or mixed (evenly split).

Option Name	Parameter	Description
GenderPopulation	mixed	Default. Sets source data gender balance to mixed.
	male	Sets source data gender balance to predominantly male.
	female	Sets source data gender balance to predominantly female.

GenderAggression

Check(Name)

Sets how aggressive genderization is for neutral first names.

Option Name	Parameter	Description
GenderAggression	neutral	Default. Gender agression is neutral.
	conservative	Gender aggression is conservative.
	aggressive	Gender aggression is aggressive.

MiddleNameLogic

Check(Name)

Determines the handling of middle names.

• ParseLogic: Middle names that are typically last names are considered to be part of a hyphenated last name.
• HypenatedLast: The middle word is assumed to be part of the last name.

For Example: "Matthew Edward Jones" is treated as "Matthew Edward-Jones."

• MiddleName: The middle word is assumed to be a middle name.

For example: "Matthew Svensson Jones." "Svensson" would be considered a middle name instead of part of the last name.

Option Name	Parameter	Description
MiddleNameLogic	parselogic	Default. Middle name typically a last name is assumed to be a hypenated last name.
	hyphenatedlast	Middle word assumed to be part of the last name.
	middlename	Middle word assumed to be a middle name.

SalutationFormat

Check(Name)

Sets the salutation format for the response.

• Formal: Dear Mr. Smith
• Informal: Dear John
• First/Last: Dear John Smith

Option Name	Parameter	Description
SalutationFormat	formal	Default. Sets the salutation format to formal.
	informal	Sets the salutation format to informal.
	firstlast	Sets the salutation format to first/last.

CentricHint

Verify(Address, Phone, Email)

When set to Auto, it first uses Address if available, followed by Phone if no Address is available, and lastly Email if neither Address nor Phone are available. Use this to tell the service which piece of information to use as the primary pivot when verifying information.

Option Name	Parameter	Description
CentricHint	auto	Default. Will use Address, Phone, then Email as a primary pivot.
	address	Will use Address as a primary pivot.
	phone	Will use Phone as a primary pivot.
	email	Will use Email as a primary pivot.
	ssn	Will use Social Security Number as a primary pivot.

Append

Append(Address, Phone, Email)

Setting this option to Blank will cause the service to return information only when the input address, phone, email, name or company is blank.

Setting this option to CheckError will cause the service to return information when there are errors to either the address, phone, email, name or company. What an error entails are defined as follows:

• Address Error: If the input address was not found in the database, was not at the least partially verified, or could not be corrected. (does not contain AS01, AS02, or AS03).

• Phone Error: If the input phone number was not matched to either the 10 digit or 7 digit level at the least. (does not contain PS01 or PS02).

• Email Error: If the input email address was not found in the database, or if the email is unconfirmed. (does not contain ES01 or ES03).

• Name Error: If the input name did not parse successfully (does not contain NS01)

• Company Error: If the input company was blank.

Setting the Append option to Always will cause the service to return information all the time, regardless of whether the input address, phone, email, name or company is blank or incorrect.

Option Name	Parameter	Description
Append	blank	Default. Returns information when the input field is blank.
	checkerror	Returns information when there are errors.
	always	Always returns information.

Demographics

Determines the data masking of demographics columns.

• Yes: No data masking will be performed. All selected output columns will be returned.
• Mask: Demographic columns' data will be 'masked'; it will be replaced with the 'Y' character if the column returns non-blank data. All selected output columns will be returned. This will return fields normally restricted for a credit license.
• MaskOnly: Demographic columns' data will be 'masked'; it will be replaced with the 'Y' character if the column returns non-blank data. All other requested columns will be in the response structure but will be blank. This will return fields normally restricted for a credit license.
• ValueOnly: All data in the demographics columns will be returned. All other requested columns will be in the response structure but will be blank.

Option Name	Parameter	Description
Demographics	yes	Default. Returns the requested demographics with other other check columns.
	mask	Returns the requested masked demographics with other check columns.
	maskonly	Returns only the requested masked demographics.
	valueonly	Returns only the requested demographics.

SSNCascade

Verify(SSN)

If set to on, cascading logic for SSN for SSN Verification and append. The cascading logic is as follows:

1. First try to verify Full Name and Full SSN
2. If there is no match, then verify the Last Name and Full SSN
3. If there is no match, then verify the Full Name and Last 4 SSN

Option Name	Parameter	Description
SSNCascade	on	The cascading verification logic for SSN and Name will be applied.
	off	Default. No cascading will occur.

DecennialCensusKey

Check(Address)

Set the preferred Census information returned, whether the latest one or the decennial version.

Option Name	Parameter	Description
DecennialCensusKey	2020	Return the 2020 static decennial census database released.
	2010	Return the 2010 static decennial census database released.
	off	Default. Return the latest Census information available.

FuzzyLookup

Check(Email)

If set to on, the API will attempt to to apply fuzzy matching algorithms to the input domain for correction.

Option Name	Parameter	Description
FuzzyLookup	on	Default. Will apply fuzzy matching correction to the domain.
	off	No corrections will occur.

AliasMode

Check(Address)

Option to convert an address to the USPS preferred street name or preserve the original address.

Option Name	Parameter	Description
AliasMode	ConvertAlias	Default. The street address alias is converted to the USPS preferred street name. This is the default setting.
	PreserveAlias	The street address alias is preserved and returned as sent.

Address Line 1

Optional.

The input field for the address line 1. This should contain the delivery address information (house number, street, building, suite, etc.) but should not contain locality information (city, state, postal code, etc.) which have their own inputs.

Protocol	Syntax
JSON	"AddressLine1":"string"
REST	&a1 = string
SOAP/XML	<AddressLine1>string</AddressLine1>

Address Line 2

Optional.

The input field for the address line 2. This can be a continuation of AddressLine1 (ex: suite) or another address.

Protocol	Syntax
JSON	"AddressLine2":"string"
REST	&a2 = string
SOAP/XML	<AddressLine2>string</AddressLine2>

Age Approximate

Optional.

Filter results to return individuals who are within a year of the provided age.

Protocol	Syntax
JSON	"AgeApproximate":"string"
REST	&ageapprox = string
SOAP/XML	<AgeApproximate>string</AgeApproximate>

Age Greater Than

Optional.

Filter results to return individuals who’s age is greater than the provided age.

Protocol	Syntax
JSON	"AgeGreaterThan":"string"
REST	&agegt = string
SOAP/XML	<AgeGreaterThan>string</AgeGreaterThan>

Age Less Than

Optional.

Filter results to return individuals who’s age is less than the provided age.

Protocol	Syntax
JSON	"AgeLessThan":"string"
REST	&agelt = string
SOAP/XML	<AgeLessThan>string</AgeLessThan>

Birth Day

Optional.

The birth day of the contact record in DD format.

Protocol	Syntax
JSON	"BirthDay":"string"
REST	&bday = string
SOAP/XML	<BirthDay>string</BirthDay>

Birth Month

Optional.

The birth month of the contact record in MM format.

Protocol	Syntax
JSON	"BirthMonth":"string"
REST	&bmo = string
SOAP/XML	<BirthMonth>string</BirthMonth>

Birth Year

Optional.

The birth year of the contact record in YYYY format.

Protocol	Syntax
JSON	"BirthYear":"string"
REST	&byr = string
SOAP/XML	<BirthYear>string</BirthYear>

City

Optional.

The city.

Protocol	Syntax
JSON	"City":"string"
REST	&city = string
SOAP/XML	<City>string</City>

Company Name

Optional.

The company name.

Protocol	Syntax
JSON	"CompanyName":"string"
REST	&comp = string
SOAP/XML	<CompanyName>string</CompanyName>

Country

Optional.

The country.

• Can only take in variations of US or Canada.
• All other countries will return AS09 (Foreign Address).
• Invalid/Blank inputs will default to US and Canada.

Protocol	Syntax
JSON	"Country":"string"
REST	&ctry = string
SOAP/XML	<Country>string</Country>

Email

Optional.

The email address.

Protocol	Syntax
JSON	"EmailAddress":"string"
REST	&email = string
SOAP/XML	<Email>string</Email>

First Name

Optional.

The given (first) name.

Protocol	Syntax
JSON	"FirstName":"string"
REST	&first = string
SOAP/XML	<FirstName>string</FirstName>

Format

Optional.

Sets the format of the response.

Protocol	Syntax
JSON	"Format":"string"
REST	&format = string
SOAP/XML	<Format>string</Format>

Free Form

Optional.

Accepts delimited or undelimited free form input. This will be parsed by the service.

Protocol	Syntax
JSON	"Freeform":"string"
REST	&ff = string
SOAP/XML	<FreeForm>string</Freeform>

Full Name

Recommended.

This field can contain a full name. We will parse and check Names only if the First Name and Last Name fields are left blank.

Protocol	Syntax
JSON	"FullName":"string"
REST	&full = string
SOAP/XML	<FullName>string</FullName>

IP Address

Optional.

An IP Address for the record.

Protocol	Syntax
JSON	"IPAddress":"string"
REST	&ip = string
SOAP/XML	<IPAddress>string</IPAddress>

Last Line

Optional.

The city, state, and ZIP.

Protocol	Syntax
JSON	"LastLine":"string"
REST	&lastline = string
SOAP/XML	<LastLine>string</LastLine>

Last Name

Optional.

The family (last) name.

Protocol	Syntax
JSON	"LastName":"string"
REST	&last = string
SOAP/XML	<LastName>string</LastName>

Melissa Address Key (MAK)

Optional.

A proprietary unique key identifier for an address.

Protocol	Syntax
JSON	"MelissaAddressKey":"string"
REST	&mak = string
SOAP/XML	<MAK>string</MAK>

Melissa Identity Key

Optional.

The input field for the Melissa Identity Key. Each individual is assigned a unique MIK number in the Melissa Personator Database.

Protocol	Syntax
JSON	"MIK":"string"
REST	&MIK = string
SOAP/XML	<MIK>string</MIK>

Phone

Optional.

The phone number.

Protocol	Syntax
JSON	"PhoneNumber":"string"
REST	&phone = string
SOAP/XML	<Phone>string</Phone>

Postal Code

Optional.

The postal code.

Protocol	Syntax
JSON	"PostalCode":"string"
REST	&postal = string
SOAP/XML	<PostalCode>string</PostalCode>

Record ID

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"
SOAP/XML	<RecordID>string</RecordID>

Social Security Number*

Optional.

Social Security Number for the record. Accepts the full Social Security Number or the Last 4 digits.

Note 1:Will not work with credit licenses and will instead return a GE29 error code.

Note 2: Verification and Reverse Social Security Appends to retrieve contact information/demographics require both the Name and SSN as inputs in order to work.

Protocol	Syntax
JSON	"SocialSecurtiy":"string"
REST	&ss = string
SOAP/XML	<SocialSecurity>string</SocialSecurity>

State

Optional.

The US state.

Protocol	Syntax
JSON	"State":"string"
REST	&state = string
SOAP/XML	<State>string</State>