Skip to content
/Consumer Verification

Personator Consumer

Overview

The Personator Consumer Cloud API provides CASS/DPV certified Address Verification and optionally leverages comprehensive Consumer data for all-in-one email, phone, name checking, name to address verification, move update, and appending missing information, demographics, enrichments.

Personator Consumer can be used to:

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

Documentation

Useful Resources

Product Page

https://www.melissa.com/personator-consumer

Support Center

https://www.melissa.com/company/product-support

Download OpenAPI description
personator-consumer.json
personator-consumer.yaml
Languages
Servers
Personator Consumer Server
https://personator.melissadata.net/v3/WEB/ContactVerify/

Consumer Verification

Use this endpoint to do contact verification.

Operations

Verify a consumer

Request

Uses HTTP GET to accept one input record and returns the response in XML or JSON format.

Note: The minimum input requirements differ depending on the Action(s) selected. Please check the documentation for more details.

Query
actArray of stringsrequired

Actions - The action(s) to take. Delimit multiple actions with a ,.

Items Enum"Check""Verify""Move""Append"
Example: act=Append
colsstring

Columns - The column names or groups to be output.

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

Delimit multiple columns with a ,.

For example: ColumnName,ColumnName.

Columns:

[No Group] - These fields have no group and have to be requested by the field name.
  • DateLastConfirmed
  • EstimatedHomeValue
  • MelissaIdentityKey
  • MoveDate
  • Occupation
  • OwnRent
  • PhoneCountryCode
  • PhoneCountryName
  • Plus4
  • PrivateMailBox
  • Suite
GrpAddressDetails - Address Details
  • AddressTypeCode
  • CarrierRoute
  • CityAbbreviation
  • CountryCode
  • CountryName
  • DeliveryIndicator
  • DeliveryPointCheckDigit
  • DeliveryPointCode
  • StateName
  • UrbanizationName
  • UTC
GrpCensus - Census Details
  • CBSACode
  • CBSADivisionCode
  • CBSADivisionLevel
  • CBSADivisionTitle
  • CBSALevel
  • CBSATitle
  • CensusBlock
  • CensusTract
  • CongressionalDistrict
  • CountyFIPS
  • CountyName
  • PlaceCode
  • PlaceName
GrpCensus2 - Additional Census Details
  • CensusKey
  • CountySubdivisionCode
  • CountySubdivisionName
  • ElementarySchoolDistrictCode
  • ElementarySchoolDistrictName
  • SecondarySchoolDistrictCode
  • SecondarySchoolDistrictName
  • UnifiedSchoolDistrictCode
  • UnifiedSchoolDistrictName
  • StateDistrictUpper
  • StateDistrictLower
GrpGeocode - Geocode Details
  • Latitude
  • Longitude
GrpDemographicBasic - Basic Demographics
  • ChildrenAgeRange
  • CreditCardUser
  • DateOfBirth
  • DateOfDeath
  • DemographicsGender
  • DemographicsResults
  • Education
  • EthnicCode
  • EthnicGroup
  • HouseholdIncome
  • HouseholdSize
  • LengthOfResidence
  • MaritalStatus
  • MedianHouseholdIncome
  • PoliticalParty
  • PresenceOfChildren
  • PresenceOfSenior
GrpIPAddress - IP Address Details
  • DistanceAddressToIP
  • IPAddress
  • IPCity
  • IPConnectionSpeed
  • IPConnectionType
  • IPContinent
  • IPCountryAbbreviation
  • IPCountryName
  • IPDomainName
  • IPISPName
  • IPLatitude
  • IPLongitude
  • IPPostalCode
  • IPProxyDescription
  • IPProxyType
  • IPRegion
  • IPUTC
GrpNameDetails - Name Details
  • Gender
  • Gender2
  • NameFirst
  • NameFirst2
  • NameLast
  • NameLast2
  • NameMiddle
  • NameMiddle2
  • NamePrefix
  • NamePrefix2
  • NameSuffix
  • NameSuffix2
  • Salutation
GrpParsedAddress - Parsed Address Details
  • AddressDeliveryInstallation
  • AddressHouseNumber
  • AddressLockBox
  • AddressPostDirection
  • AddressPreDirection
  • AddressPrivateMailboxName
  • AddressPrivateMailboxRange
  • AddressRouteService
  • AddressStreetName
  • AddressStreetSuffix
  • AddressSuiteName
  • AddressSuiteNumber
GrpParsedEmail - Parsed Email Details
  • DomainName
  • MailboxName
  • TopLevelDomain
GrpParsedPhone - Parsed Phone Details
  • AreaCode
  • NewAreaCode
  • PhoneExtension
  • PhonePrefix
  • PhoneSuffix
idany(password)required

The License Key issued by Melissa.

Example: id={REPLACE-WITH-YOUR-LICENSE-KEY}
optstring

Options - Specify which options to use for the selected action. List of options in <OptionName>:<Parameter> format. Multiple options are delimited with a ;.

For example: OptionName:Parameter;OptionName:Parameter.

  • AdvancedAddressCorrection:< On | Off > - Uses the name input to perform more advanced address corrections. This can correct or append house numbers, street names, cities, states, and ZIP codes. Default of Off means no advanced address corrections will occur.
  • AdvancedAddressType:< On | Off > - This option allows you to select whether to return the simplified address type codes or the advanced and more complete address type codes. Default of Off means only Default Address Types are returned (S, G, M, P, R, and U).
  • AliasMode:< ConvertAlias | PreserveAlias > - Option to convert an address to the USPS preferred street name or preserve the original address. Default of ConvertAlias will convert the street address alias to the USPS preferred street name.
  • Append:< Blank | CheckError | Always > - Determines the behavior when appending information. Default of Blank returns information only when the input field is blank.
  • CentricHint:< Auto | Address | Phone | Email > - This option tells the service which piece of information to use as the primary pivot when verifying information. Default of Auto first uses Address if available, followed by Phone if no Address is available, and lastly Email if neither Address nor Phone are available.
  • CorrectFirstName:< On | Off > - Default of On allows common spelling corrections for the FirstName field.
  • CorrectSyntax:< On | Off > - Default of On corrects the syntax of the Email field.
  • DatabaseLookup:< On | Off > - Default of On will attempt to verify domain names using a database of valid domains.
  • DecennialCensusKey:< Off | 2020 | 2010 > - Set the preferred Census information returned, whether the latest one or the decennial version. Default of Off returns the latest Census information available.
  • Demographics:< Yes | Mask | MaskOnly | ValueOnly > - Determines the data masking of demographics columns. Default of Yes means no data masking will be performed.
  • Diacritics:< Auto | On | Off > - Determines whether or not French language characters are returned. Default of Auto will only return those characters if they are in the input.
  • EmailAppendFilter:< [blank] | CatchAll | SpamTrap > - option to prevent certain categories of emails to append, including accept-all/catch-all emails and spam trap emails. Default of [blank] means no filtering will be done.
  • FuzzyLookup:< On | Off > - Determines whether or not to apply fuzzy matching algorithms to the input domain for correction. Default of On will apply fuzzy matching correction to the domain.
  • GenderAggression:< Neutral | Conservative | Aggressive > - Sets how aggressive genderization is for neutral first names. Default of Neutral sets gender aggression to neutral.
  • GenderPopulation:< Mixed | Male | Female > - Sets the gender balance of the source data, either predominantly male, female, or mixed (evenly split). Default of Mixed sets source data gender balance to mixed.
  • LongAddressFormat:< Off | On | Auto > - Controls how abbreviations of suffixes and directionals are handled when standardizing a street address. Default of Off will abbreviate suffixes and directionals.
  • MiddleNameLogic:< ParseLogic | HypenatedLast | MiddleName > - Determines the handling of middle names. Default of ParseLogic means that middle names that are typically last names are considered to be part of a hyphenated last name.
  • NameHint:< Varying | DefinitelyFull | VeryLikelyFull | ProbablyFull | ProbablyInverse | VeryLikelyInverse | DefinitelyInverse | MixedFirstName | MixedLastName > - Sets the name hint for the input name. Default of Varying means if necessary, statistical logic will be employed to determine name order, with no bias toward either name order.
  • SalutationFormat:< Formal | Informal | FirstLast > - Sets the salutation format for the response. Default of Formal Sets the salutation format to formal.
  • StandardizeCasing:< On | Off > - Determines whether to standardize casing in the email field before any checking occurs. Default of On will standardize all letters to lower case.
  • StandardizeCompany:< On | Off > - Determines whether to standardize the CompanyName field. Default of On will perform standard abbreviation, capitalization, and punctuation on the CompanyName field.
  • UpdateDomain:< On | Off > - Determines whether to update the domain name. Default of On will update the domain if it is out of date.
  • UsePreferredCity:< Off | On > - Determines whether to substitute the preferred city name for all vanity names when verifying an address. Default of Off means no substitution will occur.
Example: opt=Append:blank
tstring

Transmission Reference - Serves as a unique identifier for this set of records.

Example: t=Test
a1stringrequired

Address Line 1.

Example: a1=22382 Avenida Empresa
a2string

Address Line 2.

ageapproxstring

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

agegtstring

Age Greater Than - Filter results to return individuals whose age is greater than the provided age.

ageltstring

Age Less Than - Filter results to return individuals whose age is less than the provided age.

bdaystring

Birth Day - In DD format.

bmostring

Birth Month - In MM format.

byrstring

Birth Year - In YYYY format.

citystringrequired

City Name.

Example: city=Rancho Santa Margarita
compstring

Company Name.

ctrystring

Country - This can only take in variations of US or Canada. All other countries will return AS09 (Foreign Address). Invalid or blank inputs will default to US and Canada.

emailstring

Email Address.

firststring

First Name.

formatstring

Format of the request.

Enum"json""xml"
Example: format=JSON
ffstring

FreeForm - The delimited or undelimited free form input that will be parsed by the service.

fullstring

Full Name - Name parsing will only happen if the first name and last name fields are blank.

ipstring

IP Address.

lastlinestring

The city, state, and ZIP.

laststring

Last Name.

makstring

Melissa Address Key - A proprietary unique key identifier for an address.

mikstring

Melissa Identity Key - A unique number for each individual.

phonestring

Phone Number.

postalstring

Postal or ZIP Code.

statestringrequired

US State.

Example: state=California
curl -i -X GET \
  'https://personator.melissadata.net/v3/WEB/ContactVerify/doContactVerify?act=Append&id={REPLACE-WITH-YOUR-LICENSE-KEY}&a1=22382+Avenida+Empresa&city=Rancho+Santa+Margarita&state=California'

Responses

Successful response

Body
TotalRecordsstring

Total number of records.

TransmissionReferencestring

A pass-through of the input TransmissionReference field.

TransmissionResultsstring

Lists error codes from any errors caused by the most recent request as a whole. For more information, see Personator Consumer Result Codes.

Versionstring

The current service version number.

RecordsArray of objects(ResponseRecord)
Response
{
  "Records": [
    { … }
  ],
  "TotalRecords": "1",
  "TransmissionReference": " ",
  "TransmissionResults": " ",
  "Version": "5.6.13"
}

Verify consumers

Request

An HTTP POST is issued with the "ContentType" header specifying the format of the request and the "Accept" header specifying the format of the response.

Note: The minimum input requirements differ depending on the Action(s) selected. Please check the documentation for more details.

Body
required
TransmissionReferencestring

Optional. Serves as a unique request identifier.

CustomerIDstringrequired

The License Key issued by Melissa.

Actionsstringrequired

Actions - The action(s) to take. Delimit multiple actions with a ,.

Enum"Check""Verify""Move""Append"
Columnsstring

Columns - The column names or groups to be output.

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

Delimit multiple columns with a ,.

For example: ColumnName,ColumnName.

Columns:

[No Group] - These fields have no group and have to be requested by the field name.
  • DateLastConfirmed
  • EstimatedHomeValue
  • MelissaIdentityKey
  • MoveDate
  • Occupation
  • OwnRent
  • PhoneCountryCode
  • PhoneCountryName
  • Plus4
  • PrivateMailBox
  • Suite
GrpAddressDetails - Address Details
  • AddressTypeCode
  • CarrierRoute
  • CityAbbreviation
  • CountryCode
  • CountryName
  • DeliveryIndicator
  • DeliveryPointCheckDigit
  • DeliveryPointCode
  • StateName
  • UrbanizationName
  • UTC
GrpCensus - Census Details
  • CBSACode
  • CBSADivisionCode
  • CBSADivisionLevel
  • CBSADivisionTitle
  • CBSALevel
  • CBSATitle
  • CensusBlock
  • CensusTract
  • CongressionalDistrict
  • CountyFIPS
  • CountyName
  • PlaceCode
  • PlaceName
GrpCensus2 - Additional Census Details
  • CensusKey
  • CountySubdivisionCode
  • CountySubdivisionName
  • ElementarySchoolDistrictCode
  • ElementarySchoolDistrictName
  • SecondarySchoolDistrictCode
  • SecondarySchoolDistrictName
  • UnifiedSchoolDistrictCode
  • UnifiedSchoolDistrictName
  • StateDistrictUpper
  • StateDistrictLower
GrpGeocode - Geocode Details
  • Latitude
  • Longitude
GrpDemographicBasic - Basic Demographics
  • ChildrenAgeRange
  • CreditCardUser
  • DateOfBirth
  • DateOfDeath
  • DemographicsGender
  • DemographicsResults
  • Education
  • EthnicCode
  • EthnicGroup
  • HouseholdIncome
  • HouseholdSize
  • LengthOfResidence
  • MaritalStatus
  • MedianHouseholdIncome
  • PoliticalParty
  • PresenceOfChildren
  • PresenceOfSenior
GrpIPAddress - IP Address Details
  • DistanceAddressToIP
  • IPAddress
  • IPCity
  • IPConnectionSpeed
  • IPConnectionType
  • IPContinent
  • IPCountryAbbreviation
  • IPCountryName
  • IPDomainName
  • IPISPName
  • IPLatitude
  • IPLongitude
  • IPPostalCode
  • IPProxyDescription
  • IPProxyType
  • IPRegion
  • IPUTC
GrpNameDetails - Name Details
  • Gender
  • Gender2
  • NameFirst
  • NameFirst2
  • NameLast
  • NameLast2
  • NameMiddle
  • NameMiddle2
  • NamePrefix
  • NamePrefix2
  • NameSuffix
  • NameSuffix2
  • Salutation
GrpParsedAddress - Parsed Address Details
  • AddressDeliveryInstallation
  • AddressHouseNumber
  • AddressLockBox
  • AddressPostDirection
  • AddressPreDirection
  • AddressPrivateMailboxName
  • AddressPrivateMailboxRange
  • AddressRouteService
  • AddressStreetName
  • AddressStreetSuffix
  • AddressSuiteName
  • AddressSuiteNumber
GrpParsedEmail - Parsed Email Details
  • DomainName
  • MailboxName
  • TopLevelDomain
GrpParsedPhone - Parsed Phone Details
  • AreaCode
  • NewAreaCode
  • PhoneExtension
  • PhonePrefix
  • PhoneSuffix
Optionsstring

Options - Specify which options to use for the selected action. List of options in <OptionName>:<Parameter> format. Multiple options are delimited with a ;.

For example: OptionName:Parameter;OptionName:Parameter.

  • AdvancedAddressCorrection:< On | Off > - Uses the name input to perform more advanced address corrections. This can correct or append house numbers, street names, cities, states, and ZIP codes. Default of Off means no advanced address corrections will occur.
  • AdvancedAddressType:< On | Off > - This option allows you to select whether to return the simplified address type codes or the advanced and more complete address type codes. Default of Off means only Default Address Types are returned (S, G, M, P, R, and U).
  • AliasMode:< ConvertAlias | PreserveAlias > - Option to convert an address to the USPS preferred street name or preserve the original address. Default of ConvertAlias will convert the street address alias to the USPS preferred street name.
  • Append:< Blank | CheckError | Always > - Determines the behavior when appending information. Default of Blank returns information only when the input field is blank.
  • CentricHint:< Auto | Address | Phone | Email > - This option tells the service which piece of information to use as the primary pivot when verifying information. Default of Auto first uses Address if available, followed by Phone if no Address is available, and lastly Email if neither Address nor Phone are available.
  • CorrectFirstName:< On | Off > - Default of On allows common spelling corrections for the FirstName field.
  • CorrectSyntax:< On | Off > - Default of On corrects the syntax of the Email field.
  • DatabaseLookup:< On | Off > - Default of On will attempt to verify domain names using a database of valid domains.
  • DecennialCensusKey:< Off | 2020 | 2010 > - Set the preferred Census information returned, whether the latest one or the decennial version. Default of Off returns the latest Census information available.
  • Demographics:< Yes | Mask | MaskOnly | ValueOnly > - Determines the data masking of demographics columns. Default of Yes means no data masking will be performed.
  • Diacritics:< Auto | On | Off > - Determines whether or not French language characters are returned. Default of Auto will only return those characters if they are in the input.
  • EmailAppendFilter:< [blank] | CatchAll | SpamTrap > - option to prevent certain categories of emails to append, including accept-all/catch-all emails and spam trap emails. Default of [blank] means no filtering will be done.
  • FuzzyLookup:< On | Off > - Determines whether or not to apply fuzzy matching algorithms to the input domain for correction. Default of On will apply fuzzy matching correction to the domain.
  • GenderAggression:< Neutral | Conservative | Aggressive > - Sets how aggressive genderization is for neutral first names. Default of Neutral sets gender aggression to neutral.
  • GenderPopulation:< Mixed | Male | Female > - Sets the gender balance of the source data, either predominantly male, female, or mixed (evenly split). Default of Mixed sets source data gender balance to mixed.
  • LongAddressFormat:< Off | On | Auto > - Controls how abbreviations of suffixes and directionals are handled when standardizing a street address. Default of Off will abbreviate suffixes and directionals.
  • MiddleNameLogic:< ParseLogic | HypenatedLast | MiddleName > - Determines the handling of middle names. Default of ParseLogic means that middle names that are typically last names are considered to be part of a hyphenated last name.
  • NameHint:< Varying | DefinitelyFull | VeryLikelyFull | ProbablyFull | ProbablyInverse | VeryLikelyInverse | DefinitelyInverse | MixedFirstName | MixedLastName > - Sets the name hint for the input name. Default of Varying means if necessary, statistical logic will be employed to determine name order, with no bias toward either name order.
  • SalutationFormat:< Formal | Informal | FirstLast > - Sets the salutation format for the response. Default of Formal Sets the salutation format to formal.
  • StandardizeCasing:< On | Off > - Determines whether to standardize casing in the email field before any checking occurs. Default of On will standardize all letters to lower case.
  • StandardizeCompany:< On | Off > - Determines whether to standardize the CompanyName field. Default of On will perform standard abbreviation, capitalization, and punctuation on the CompanyName field.
  • UpdateDomain:< On | Off > - Determines whether to update the domain name. Default of On will update the domain if it is out of date.
  • UsePreferredCity:< Off | On > - Determines whether to substitute the preferred city name for all vanity names when verifying an address. Default of Off means no substitution will occur.
RecordsArray of objects(RequestRecord)[ 1 .. 100 ] itemsrequired
Records[].​AddressLine1string

The input field for the address line 1.

Records[].​AddressLine2string

The input field for the address line 2.

Records[].​AgeApproximatestring

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

Records[].​AgeGreaterThanstring

Optional. Filter results to return individuals whose age is greater than the provided age.

Records[].​AgeLessThanstring

Optional. Filter results to return individuals whose age is less than the provided age.

Records[].​BirthDaystring

The birth day of the contact record in DD format.

Records[].​BirthMonthstring

The birth month of the contact record in MM format.

Records[].​BirthYearstring

The birth year of the contact record in YYYY format.

Records[].​Citystring

The city name.

Records[].​CompanyNamestring

The company name.

Records[].​Countrystring

The country. This can only take in variations of US or Canada. All other countries will return AS09 (Foreign Address). Invalid or blank inputs will default to US and Canada.

Records[].​EmailAddressstring

The email address.

Records[].​FirstNamestring

The given (first) name.

Records[].​Formatstring

The format of the response.

Records[].​FreeFormstring

The delimited or undelimited free form input that will be parsed by the service.

Records[].​FullNamestring

The full name. Name parsing will only happen if the first name and last name fields are blank.

Records[].​IPAddressstring

The IP Address for the record.

Records[].​LastLinestring

The city, state, and ZIP.

Records[].​LastNamestring

The family (last) name.

Records[].​MelissaAddressKeystring

A proprietary unique key identifier for an address.

Records[].​MIKstring

The input field for the Melissa Identity Key, a unique number for each individual.

Records[].​PhoneNumberstring

The phone number.

Records[].​PostalCodestring

The postal or ZIP Code.

Records[].​RecordIDstring

A unique identifier for the current record.

Records[].​Statestring

The US state.

curl -i -X POST \
  https://personator.melissadata.net/v3/WEB/ContactVerify/doContactVerify \
  -H 'Content-Type: application/json' \
  -d '{
    "Actions": "Append",
    "Columns": "",
    "CustomerID": "{REPLACE-WITH-YOUR-LICENSE-KEY}",
    "Options": "Append:blank",
    "TransmissionReference": "Test",
    "Records": [
      {
        "AddressLine1": "22382 Avenida Empresa",
        "AddressLine2": "",
        "BirthDay": "",
        "BirthMonth": "",
        "BirthYear": "",
        "City": "Rancho Santa Margarita",
        "CompanyName": "",
        "Country": "",
        "EmailAddress": "",
        "FirstName": "",
        "Format": "JSON",
        "FreeForm": "",
        "FullName": "",
        "IPAddress": "",
        "LastLine": "",
        "LastName": "",
        "MelissaAddressKey": "",
        "MIK": "",
        "PhoneNumber": "",
        "PostalCode": "",
        "RecordID": "1",
        "State": "California"
      },
      {
        "AddressLine1": "",
        "AddressLine2": "",
        "BirthDay": "",
        "BirthMonth": "",
        "BirthYear": "",
        "City": "",
        "CompanyName": "",
        "Country": "",
        "EmailAddress": "",
        "FirstName": "",
        "Format": "JSON",
        "FreeForm": "",
        "FullName": "",
        "IPAddress": "",
        "LastLine": "",
        "LastName": "",
        "MelissaAddressKey": "",
        "MIK": "",
        "PhoneNumber": "",
        "PostalCode": "",
        "RecordID": "2",
        "State": ""
      }
    ]
  }'

Responses

Successful response

Body
TotalRecordsstring

Total number of records.

TransmissionReferencestring

A pass-through of the input TransmissionReference field.

TransmissionResultsstring

Lists error codes from any errors caused by the most recent request as a whole. For more information, see Personator Consumer Result Codes.

Versionstring

The current service version number.

RecordsArray of objects(ResponseRecord)
Response
{
  "Records": [
    { … },
    { … }
  ],
  "TotalRecords": "2",
  "TransmissionReference": " ",
  "TransmissionResults": " ",
  "Version": "5.6.13"
}