Quickstart Guide

Personator Consumer

Introduction

Personator Consumer can be used to:

  • Verify, Correct, & Standardize names, addresses, phones and emails
  • Retrieve move information
  • Append demographics
  • Append Geographic and Census data

Basic Order of Operations

Real Time

  • Put the input data into JSON, XML, or REST format.
  • Make sure to include your license key.
  • Specify any options you would like to modify from their default.
  • Send the request to the service URL: https://personator.melissadata.net/v3/WEB/ContactVerify/doContactVerify using HTTP GET.
  • Receive the result back from the service.

Batch

  • Put the input request together using JSON or XML. Put up to 100 records into the request array.
  • Make sure to include your license key.
  • Specify any options you would like to modify from their default. They will apply to all records in the request.
  • Make sure to specify the same options for all records in the batch to maintain consistency.
  • Send the full request to the service URL: https://personator.melissadata.net/v3/WEB/ContactVerify/doContactVerify using HTTP POST
  • Receive the result back for all records from the input.

Input Request

Real Time

With a REST request, you can include all the input along with the URL for an easy and quick way of sending a single record.

curl -X GET 
“https://personator.melissadata.net/v3/WEB/ContactVerify/doContactVerify?t=&id=LICENSE_KEY&act=Check,Verify,Append,Move&cols=GrpDemographicBasic&opt=&full=Ray%20Melissa&comp=&a1=22382%20Avenida%20Empresa&a2=&city=Rancho%20Santa%20Margarita&state=CA&postal=92688&email=&phone=&phone=&ctry=&ss=&mak=&ip=&bday=&bmo=&byr=&format=json”

You can also put the URL without the “curl -X GET” command directly into your browser. This service will only return a JSON result. You can also use JSON POST to send requests.

JSON POST

Header

Make sure the header includes this line.

Accept: application/json

Body

{
  "TransmissionReference":"Test",
  "Actions":"Check,Verify,Append,Move",
  "Columns":"GrpDemographicBasic",
  "CustomerID":"LICENSE_STRING",
  "Options":"",
  "Records":[
    {
      "AddressLine1":"22382 Avenida Empresa",
      "AddressLine2":"",
      "BirthDay":"",
      "BirthMonth":"",
      "BirthYear":"",
      "City":"Rancho Santa Margarita",
      "CompanyName":"",
      "Country":"",
      "EmailAddress":"",
      "FirstName":"",
      "FreeForm":"",
      "FullName":"Ray Melissa",
      "IPAddress":"",
      "LastLine":"",
      "LastName":"",
      "MelissaAddressKey":"",
      "PhoneNumber":"",
      "PostalCode":"92688",
      "RecordID":"",
      "SocialSecurity":"",
      "State":"CA"
    }
  ]
}

Input Fields

JSON Input REST Input Description REQUIRED
TransmissionReference t Value passed through unchanged to the response for identification or any other purpose No
CustomerID id The License Key issued by Melissa Yes
Actions act
Action Description
Check The Check action will validate the individual input data pieces for validity (address, name, phone and email) and correct them if possible. If the data is correctable, additional information will often be appended as well. US and Canada only.
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.
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.
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.
No
Columns cols Specifies which column(s) to be output. You may specify individual column names to be outputted, or column groups which are columns that have been grouped together in the same category No
Options opt UsePreferredCity
Code Description
on Will substitute the preferred city name for all vanity names.
off Default. No substitution will occur.
Diacritics
Code Description
on Will return diacritics.
off No diacritics returned.
auto Default. Diacritics only returned if in the input.
AdvancedAddressCorrection
Code Description
on Will use name input to perform advanced address corrections.
off Default. No advanced address corrections will occur.
AdvancedAddressType
Code Description
on All possible address type codes are returned.
off Default. Only simplified address types are returned (S, G, M, P, R, and U).
LongAddressFormat
Code Description
on Will spell out suffixes and directional abbreviations.
off Default. Will abbreviate suffixes and directionals.
auto Will preserve suffixes and directionals as entered
CorrectSyntax
Code Description
on Default. Will correct the syntax of the Email field.
off No corrections will occur.
UpdateDomain
Code Description
on Default. Will update the domain if it is out of date.
off No updates will occur.
DatabaseLookup
Code Description
on Default. Will attempt to verify domain names.
off No verification will occur.
StandardizeCasing
Code Description
on Default. Will standardize all letters to lower case.
off No case changes will occur.
CorrectFirstName
Code Description
on Default. Will perform spelling corrections on the FirstName field.
off No spelling corrections will occur.
StandardizeCompany
Code Description
on Default. Will perform standard abbreviation, capitalization, and punctuation on the CompanyName field.
off No changes will occur.
NameHint
Code Description
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
Code Description
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
Code Description
neutral Default. Gender agression is neutral.
conservative Gender aggression is conservative.
aggressive Gender aggression is aggressive.
MiddleNameLogic
Code Description
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
Code Description
formal Default. Sets the salutation format to formal.
informal Sets the salutation format to informal.
firstlast Sets the salutation format to first/last.
CentricHint
Code Description
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
Code Description
blank Default. Returns information when the input field is blank.
checkerror Returns information when there are errors.
always Always returns information.
Demographics
Code Description
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
Code Description
on The cascading verification logic for SSN and Name will be applied.
off Default. No cascading will occur.
DecennialCensusKey
Code Description
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.
No
AddressLine1 a1 The Input Address Line 1 Yes
AddressLine2 a2 The Input Address Line 2 No
BirthDay bday The Input Day of Birth No
BirthMonth bmo The Input Month of Birth No
BirthYear byr The Input Year of Birth No
City city The Input City No
CompanyName comp The Input Company Name No
Country ctry 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.
 No
Email email The Input Email No
FirstName first The Input First Name No
Format format The Input format set to either JSON or XML No
Freeform ff The Input as a single string which can contain the address, name, phone, email or SSN in a delimited or undelimited format. No
FullName full The Input Full Name No
IPAddress ip The Input IP Address No
LastLine lastline The Input city, state, zip as a single string No
LastName last The Input Last Name No
MelissaAddressKey mak The Input Melissa Address Key No
MIK MIK The input field for the Melissa Identity Key. Each individual is assigned a unique MIK number in the Melissa Personator Database. No
Phone phone The Input Phone No
PostalCode postal The Input Zip/Postal Code No
RecordID A unique identifier for the current record. Use this to match the record submitted with the record returned. No
SocialSecurityNumber ss The Input Social Security Number No
State state The Input State No

Input Best Practices

Personator Consumer does not return all data points by default. In order to return other data points, you must request them using them from the Columns input. This is how it is configured in the request:

  • REST: cols=GrpDemographicBasic
  • JSON: "Columns":"GrpDemographicBasic",

Specifying individual column names or column groups in the input will result in that column or column group to be returned in the response.

The complete list of columns and column groups can be found here: http://wiki.melissadata.com/index.php?title=Personator_Consumer%3ARequest#Columns

Actions

Personator Consumer allows you to choose specifically which actions to perform. You can customize this using the Actions input.

This is how it is configured in the request:

  • REST: act=Check,Verify,Append
  • JSON: "Actions":"Check,Verify,Append",

The actions and their purpose are as follows:

Action Description
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.
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.
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.
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.

Output Response

Real Time

Here is a sample response of the real-time request and JSON POST from above.

{
  "Records":[{
    "AddressDeliveryInstallation":"string",
    "AddressExtras":"string ",
    "AddressHouseNumber":"string",
    "AddressKey":"string",
    "AddressLine1":"string",
    "AddressLine2":"string",
    "AddressLockBox":"string",
    "AddressPostDirection":"string",
    "AddressPreDirection":"string",
    "AddressPrivateMailboxName":"string",
    "AddressPrivateMailboxRange":"string",
    "AddressRouteService":"string",
    "AddressStreetName":"string",
    "AddressStreetSuffix":"string",
    "AddressSuiteName":"string",
    "AddressSuiteNumber":"string",
    "AddressTypeCode":"string",
    "AreaCode":"string",
    "CBSACode":"string",
    "CBSADivisionCode":"string",
    "CBSADivisionLevel":"string",
    "CBSADivisionTitle":"string",
    "CBSALevel":"string",
    "CBSATitle":"string",
    "CarrierRoute":"string",
    "CensusBlock":"string",
    "CensusKey":"string",
    "CensusTract":"string",
    "ChildrenAgeRange":"string",
    "City":"string",
    "CityAbbreviation":"string",
    "CompanyName":"string",
    "CongressionalDistrict":"string",
    "CountryCode":"string",
    "CountryName":"string",
    "CountyFIPS":"string",
    "CountyName":"string",
    "CountySubdivisionCode":"string",
    "CountySubdivisionName":"string",
    "CreditCardUser":"string",
    "DateOfBirth":"string",
    "DateOfDeath":"string",
    "DeliveryIndicator":"string",
    "DeliveryPointCheckDigit":"string",
    "DeliveryPointCode":"string",
    "DemographicsGender":"string",
    "DemographicsResults":"string",
    "DistanceAddressToIP":"string",
    "DomainName":"string",
    "Education":"string",
    "ElementarySchoolDistrictCode":"string",
    "ElementarySchoolDistrictName":"string",
    "EmailAddress":"string",
    "EstimatedHomeValue":"string",
    "EthnicCode":"string",
    "EthnicGroup":"string",
    "Gender":"string",
    "Gender2":"string",
    "HouseholdIncome":"string",
    "HouseholdSize":"string",
    "IPAddress":"string",
    "IPCity":"string",
    "IPConnectionSpeed":"string",
    "IPConnectionType":"string",
    "IPContinent":"string",
    "IPCountryAbbreviation":"string",
    "IPCountryName":"string",
    "IPDomainName":"string",
    "IPISPName":"string",
    "IPLatitude":"string",
    "IPLongitude":"string",
    "IPPostalCode":"string",
    "IPProxyDescription":"string",
    "IPProxyType":"string",
    "IPRegion":"string",
    "IPUTC":"string",
    "Latitude":"string",
    "LengthOfResidence":"string",
    "Longitude":"string",
    "MailboxName":"string",
    "MaritalStatus":"string",
    "MelissaAddressKey":"string",
    "MelissaAddressKeyBase":"string",
    "MoveDate":"string",
    "NameFirst":"string",
    "NameFirst2":"string",
    "NameFull":"string",
    "NameLast":"string",
    "NameLast2":"string",
    "NameMiddle":"string",
    "NameMiddle2":"string",
    "NamePrefix":"string",
    "NamePrefix2":"string",
    "NameSuffix":"string",
    "NameSuffix2":"string",
    "NewAreaCode":"string",
    "Occupation":"string",
    "OwnRent":"string",
    "PhoneCountryCode":"string",
    "PhoneCountryName":"string",
    "PhoneExtension":"string",
    "PhoneNumber":"string",
    "PhonePrefix":"string",
    "PhoneSuffix":"string",
    "PlaceCode":"string",
    "PlaceName":"string",
    "Plus4":"string",
    "PoliticalParty":"string",
    "PostalCode":"string",
    "PresenceOfChildren":"string",
    "PresenceOfSenior":"string",
    "PrivateMailBox":"string",
    "RecordExtras":"string",
    "RecordID":"string",
    "Reserved":"string",
    "Results":"string",
    "Salutation":"string",
    "SecondarySchoolDistrictCode":"string",
    "SecondarySchoolDistrictName":"string",
    "State":"string",
    "StateDistrictLower":"string",
    "StateDistrictUpper":"string",
    "StateName":"string",
    "Suite":"string",
    "TopLevelDomain":"string",
    "TypesOfVehicles":"string",
    "UTC":"string",
    "UnifiedSchoolDistrictCode":"string",
    "UnifiedSchoolDistrictName":"string",
    "UrbanizationName":"string"
  }],
  "TotalRecords":"string",
  "TransmissionReference":"string",
  "TransmissionResults":"string",
  "Version":"string"
}

Output Fields

Response (Base Level)

Output Name Description
Version The current revision number of Global Address Verification.
TransmissionReference Returned value will be the same as the input TransmissionReference to be used as a unique identifier.
Total Records The total number of records returned.
TransmissionResults Service Errors (SE Codes) and General Transmission Errors (GE Codes)
Results Shows you the result of the address verification with codes for status, error, and changes. See the Results section below for more details.

Record Level

Output Name Description
AddressLine1 Returns the first address line
AddressLine2 Returns the second address line
City Returns the city for the address
State Returns the state for the address
PostalCode Returns the Zip+4 for the address
NameFull Returns the individual's full name
PhoneNumber Returns the individual's phone number
EmailAddress Returns the individual's email address
MelissaAddressKey A unique key identifier associated with the address
MelissaAddressKeyBase A unique key identifier associated with a building containing multiple suites/apartments

A complete list of all Personator Output fields can be retrieved here: http://wiki.melissadata.com/index.php?title=Personator_Consumer%3AResponse

Interpreting Results

The Personator API and other Melissa APIs will have a Results Output. Several different Result Codes may be returned by the service in order to give you detailed information about the status of the record submitted.

It is important to understand these result codes in order for you to make a determination of good vs bad data and how you would want to use it.

The following shows you the indicators for the different results:

Code Description Quality Indicator
AS01 Address verified at the unit level Good Data
AS02 Address verified at the building level Good Data
AS03 Valid non-USPS address Good Data
PS01 Valid phone number Good Data
ES01 Valid email address Good Data
NS01 Name successfully parsed Good Data
AE** Results that begin with AE are an indication of address errors Bad Data
PE** Results that begin with PE are an indication of phone errors Bad Data
EE** Results that begin with EE are an indication of email errors Bad Data
NE** Results that begin with NE are an indication of name errors Bad Data
GS05 Rooftop level accuracy for Lat/Long High Accuracy GeoCoding
GS06 Interpolated rooftop level accuracy for Lat/Long High Accuracy GeoCoding
GS01 Street level accuracy for Lat/Long Medium Accuracy GeoCoding

For a list of the common transmission errors, see the General Info - Response Level Errors page.

For the full list of all possible result codes, please visit our Result Wiki page at Personator Consumer Result Code Details.