Personator Consumer:Request

From Melissa Data Wiki
Jump to navigation Jump to search

← Personator Consumer

Personator Consumer Navigation
Introduction
Basics
Licensing
Input/Output
Request Fields
Response Fields
Examples
REST JSON
REST JSONP
REST XML
JSON
Batch JSON
XML
Batch XML
Result Codes
Result Code Use
Personator Consumer 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 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
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.


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>


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>