Personator Consumer:FAQ

From Melissa Data Wiki
Revision as of 23:24, 25 May 2021 by Admin (talk | contribs)
Jump to navigation Jump to search

← Personator Consumer

Service Speed

What kinds of speeds/throughput can the Personator Consumer Web Service do?

The following are the average speeds for 1 Thread vs 10 Threads, for different combinations of Actions selected:

Action Throughput (rec / hour)
Average 1 Thread
Throughput (rec / hour)
Average 10 Threads
Check Only 150K 600K-750K
Check Only with Express hint 200K 900K-1M
Check + Verify 80K 300K-400K
Check + Append 80K 300K-400K
Check + Move 30K 150K-250K
All Actions 30K 150K-250K

What are some best practices for requesting large amounts of data?

It is recommended that when processing large amounts of records that it be submitted in batches of 100 records per request. Personator has the ability to accept multiple records for each request using either the XML or JSON protocols. An example of the Request Structure for multiple records can be found here: Personator Consumer:Batch JSON

Multi-threading is also standard practice in order to get higher throughputs.

Are there server-side limitations on threading?

The server currently does not have a limit the amount of threads that you submit to it. However, for batch processing records (having 100 records per request), it is recommended that no more than 10 simultaneous threads are running. Please advise your CSR if more threads are required so that proper accommodations can be set in place.

Minimum Input Requirements

What are the minimum input requirements for each Action?


Must satisfy any one of these combinations:

  1. (Address and Zip)
  2. (Address, City and State)
  3. Phone Number
  4. Email
  5. Full Name
  6. (First Name and Last Name)

If combinations of fields are selected, make sure that the minimum requirements are always met for those that have 2 or more fields required.

So for example, if a user selects a Phone Number and Address, it should not pass unless they also input either a Zip or the City & State


User must satisfy 2 or more of the following conditions:

  1. (Address, City and State) OR (Address and Zip) – must first make sure that the minimum requirements for an address is met
  2. Phone
  3. Email
  4. (Full Name) OR (Last Name Only) OR (First and Last Name) – must first make sure that the minimum requirements for a Name is met
  5. Company

So for example, satisfying condition 1 and 5 will meet the Minimum Input Requirements for Verify.

All combinations of 2 or more will satisfy the minimum input requirements for Verify with the exception of combination 4 and 5. Therefore, selecting Full Name and Company does not satisfy the minimum input requirements for Verify.

Move Update

User must satisfy at least one of the following combinations:

  1. Address and Full Name
  2. Address, First and Last Name
  3. Address and Company Name


The Minimum Input requirements for Append will be dependent on which field you are trying to append information for. For example, appending missing names will have a different minimum input, as opposed to appending addresses. The following are the list elements that can be appended and the minimum requirements for each:

Append Names/Company

Must have at least one of these:

  1. (Address, City and State) OR (Address and Zip) – must first make sure that the minimum requirements for an address is met
  2. Phone
  3. Email

Append Addresses

Must have at least one of these:

  1. Phone
  2. Email

Append GeoLocations

This one is going to be a little different. The minimum input requirements will depend on other Options you currently have selected.

If Only Append GeoLocations is Selected, the user must satisfy at least 1 of the following minimum input requirements:

  1. (Address, City and State) OR (Address and Zip) – must first make sure that the minimum requirements for address are first met
  2. Phone Number – Personator Consumer can give you Phone Lat Long.

If Append GeoLocations and either Append Addresses or Append Phones are also Selected, the user must satisfy at least 1 of the following minimum input requirements:

  1. (Address, City and State) OR (Address and Zip) – must first make sure that the minimum requirements for address are first met
  2. Phone Number
  3. Email Address – You can append addresses or phone numbers using just emails, which will then give you the Appended Address’ or Phone Numbers’ Lat/Long

Append Phones

Must have at least one of these:

  1. (Address, City and State) OR (Address and Zip) – must first make sure that the minimum requirements for an address is met
  2. Email

Append Emails

Must have at least one of these:

  1. (Address, City and State) OR (Address and Zip) – must first make sure that the minimum requirements for an address is met
  2. Phone

Data Sources

Where does the Data from the Personator Consumer Web Service Come from?

The Personator Consumer Database is compiled from several sources and industries such as Property Information Data, Loan Data, Credit Data, Telephone Data, Voter Data, and several other private sources. The final combined database merges all contact records including Addresses, Phone Numbers, Emails and Names amounting to over a billion records of historical and current information. This data is then exposed through the Personator Consumer Web Service which allows for checking, verifying, appending and updating contact records. Since the service revolves heavily around the contents of the data, the exact provider for the sources is not something we can disclose at the moment as we prefer to keep this information private in order to maintain the product’s uniqueness and value in the industry.

NCOA and Personator Consumer Move Differences

What is the difference between USPS National Change of Address and Personator Consumer Move?

Users who wish to make use of the USPS National Change of Address (NCOA) for detecting move addresses should use the Smart Mover Web Service. This is commonly used by users who wish to avail of USPS discounts for mailing. Personator Consumer’s Move capability on the other hand, offers a more comprehensive and extensive coverage for detecting move addresses through the use of a massive consolidated data set compiled from several different sources. Here are some of the advantages of using Personator Consumer Move that are not available through NCOA:

Non-NCOA Moves
The USPS limits its move capabilities only to people who file an NCOA Form with the Post Office. Personator Consumer Move is not limited to this, as it is able to provide Moves for even those people who do not file an NCOA form with the USPS.
10 Year Detection
Another limitation of NCOA moves is that it can only move a person who has filed an NCOA form in the last 4 years. Personator Consumer Move on the other hand can give you the latest address for a person who has moved within the last 10 years.
Chained Moves
If a person has moved 3 times within the last 4 years, NCOA will only be able to give you the most recent move based on the last previous address. Personator Consumer Move on the other hand has the ability to chain all of that person’s moves and provide you with the latest address, regardless of which of the 3 previous addresses you enter.
Personator Consumer boasts an estimated 400 million move records in the Database. Which is a much much larger coverage compared to NCOA.

Maximum Length Response

What is the Maximum Length Response that we can Expect to Receive for Each Field in Personator Consumer?

The Web Service Response, in general, does not have a maximum length for each Response Field. This is to avoid any form of truncation when returning information from our data. We do however have recommended values which you can set for defining field lengths in your table.

Response Field Length
MD_NameFull 256
MD_CompanyName 128
MD_Results 100
MD_EmailAddress 75
MD_PlaceName 60
MD_CBSATitle 55
MD_CBSADivisionTitle 55
MD_AddressExtras 50
MD_AddressLine2 50
MD_AddressLine1 50
MD_DomainName 50
MD_AddressStreetName 40
MD_NameLast2 35
MD_NameFirst2 35
MD_NameFirst 35
MD_City 35
MD_CBSALevel 35
MD_NameLast 35
MD_CBSADivisionLevel 35
MD_AddressTypeCode 31
MD_PhoneNumber 30
MD_StateName 25
MD_CountyName 25
MD_CountryName 25
MD_MailboxName 25
MD_NamePrefix 20
MD_NameSuffix 20
MD_NamePrefix2 20
MD_AddressRouteService 20
MD_Suite 20
MD_Salutation 20
MD_NameMiddle2 20
MD_NameMiddle 20
MD_AddressLockBox 20
MD_NameSuffix2 20
MD_AddressDeliveryInstallation 20
MD_State 15
MD_PrivateMailBox 15
MD_UrbanizationName 15
MD_PhoneExtension 14
MD_CityAbbreviation 13
MD_Latitude 12
MD_Longitude 12
MD_DeliveryPointCheckDigit 11
MD_AddressKey 11
MD_CountryCode 10
MD_AddressPrivateMailboxName 10
MD_AddressPrivateMailboxRange 10
MD_AddressSuiteName 10
MD_TopLevelDomain 10
MD_PostalCode 10
MD_AddressStreetSuffix 10
MD_AddressSuiteNumber 10
MD_PlaceCode 7
MD_CensusTract 6
MD_AddressPreDirection 5
MD_CBSADivisionCode 5
MD_AddressPostDirection 5
MD_CountyFIPS 5
MD_PhoneSuffix 4
MD_AddressHouseNumber 4
MD_CensusBlock 4
MD_CarrierRoute 4
MD_Plus4 4
MD_PhonePrefix 3
MD_AreaCode 3
MD_NewAreaCode 3
MD_DeliveryPointCode 2
MD_CongressionalDistrict 2
MD_Gender 1
MD_DeliveryIndicator 1
MD_Gender2 1


What are the types of demographics that Personator Consumer can return?

Personator Consumer can return the following demographics:

Date of Birth
This will be in the format YYYYMM. So the accuracy will only be to the Month.
Date of Death
We will be returning the full date of death in the format YYYYMMDD
Presence of Children
Indicates the presence of children in the household
No Children Present
Children Present
Marital Status
Indicates whether the Individual is married or not
Definitely Single
Inferred Single
Inferred Married
Definitely Married
Indicates whether the Individual is either a renter or an owner or property
Definite Renter
Inferred Renter
Inferred Owner
Definite Owner
Demographic Gender
Indicates Gender based on Demographics Data
Household Income
Indicates the range of the Household’s Income
Length of Residence
Indicates the range of the Individual’s length of residency in his current address
Less than 1 year
1-2 years
2-3 years
3-4 years
4-5 years
5-6 years
6-7 years
7-8 years
8-9 years
9-10 years
10-11 years
11-12 years
12-13 years
13-14 years
14-15 years
15+ years
Indicates the category for the Individual’s Occupation
Clerical/Service Worker
Federal Employee
Military Retired
Business Owner
Self Employed

Result Code Differences

Personator Consumer has the ability to return codes within the AS, AC, AE, VR, VS, and DA groupings (not counting the Demographic Result codes). At a high level, these groupings correlate to the following:

AS – Address Status

If we were able to validate the address to some level, we will return an AS result code, the most common being AS01 if the address is fully verified. However, we can return other AS codes to mean things such as street only match (AS02 – perhaps there is a missing apartment), non USPS match (AS03 – the address cannot receive mail from USPS but can possibly receive mail from other carriers), foreign address (AS09 – we identified this as an address from a different country), and more.

AC – Address Change

If for whatever reason the input address isn’t able to be verified outright, but there may be a misspelling, incorrect street name or number, the city has an alias, and things of that nature, we will change it to the USPS certified address and return an AC code determining what we changed. For example, if there is no input postal code, or it is incorrect compared to the city and state that is inputted, then we will correct the postal code and return AC01. If there is a misspelling in the street name that we can correct and then verify the address with, then we will correct that street name and return AC10. If for whatever reason you input a second address line into AddressLine1 and a first address line into AddressLine2 and we were able to identify the correct address, then we will swap the two lines and return AC06.

AE – Address Error

If we are not able to validate or correct any part of the input address, then we will return the input address untouched, and return an AE code determining why we couldn’t validate the address. If there is an error with the postal code, then we will return AE01, if the address is non-deliverable, we will return AE04, if you are missing the minimum pieces to validate an address (first addressline and either city/state or postal code), then we will return an AE07.

VR – Verify Results

VR codes will only return if the “Verify” action is enabled within Personator Consumer. What essentially happens with the verify action is that the input data will be compared against Personator Consumer’s proprietary database behind the scenes, and a matching record will try to be found. If the matching record is found, then we will return VR codes stating what pieces of information matched. As an example, let’s say you input:
  • Tom Smith - 123 Main Street, CA 90210 – Phone: 555 555 1234
  • And we found a record in the Personator Consumer data with: Tom Smith – 123 Main Street, CA 90210 – Phone: 555 555 5678, then we will return VR01, stating that the individual name and individual address matched what we have in Personator Consumer.
  • If we found a record in the Personator Consumer data with: Tom Smith – 123 Main Street, CA 90210 – Phone: 555 555 1234, then we will return VR01, VR04. Meaning we matched the individual name and address (VR01), and also matched the individual address and phone (VR04).
  • Note that the priority in the codes that return are in the following order: address, phone, email, name.
  • VR - Verify Results

VS – Verify Status

These codes also only return if the “Verify” action is enabled, and essentially tells the user if we couldn’t find a certain piece of information in our reference data or there was a partial match. Let’s take the same example as above:
  • Tom Smith - 123 Main Street, CA 90210 – Phone: 555 555 1234
  • We found a record in the Personator Consumer data with: Tammy Smith – 123 Main Street, CA 90210 – Phone: 555 555 5678, then we will return VR01, but also return a VS12, which is a last name match. This is because we found a matching record but only had a partial name match.
  • Let’s say for that same example, we do not have the input phone number in our data at all, then we will return a VS30, stating that the phone is not found in our reference data.
  • VS - Verify Status

DA – Append

These codes only return if the “Append” action is enabled, and tells you what piece of information we appended from our reference data to the service output. Let’s say you input the following information:
  • Tom Smith - 123 Main Street, CA 90210
  • And we found the following record in Personator Consumer: Tom Smith - 123 Main Street, CA 90210 – Phone: 555 555 1234 – Email:
  • We will then return the phone number and email, with the DA30 (phone appended) and DA40 (email appended) codes.
  • Note that all of the domains covered in Personator Consumer (name, address, phone, email) are able to be appended and centricities and append conditions can be manipulated with the “CentricHint” and “Append” options (Personator Consumer Request - Centric Hint and Personator Consumer Request - Append 2)
  • DA - Append Results

Email Validity Degree

If Personator returns ES01 / ES02 / ES03 this means that Personator did not find the email in our database; meaning that the email was validated at a domain level.

If Personator returns ES01,ES21 / ES02,EE##/ES21 this means that Personator found the email address in our database.

It’s entirely possible that Personator may return ES01 initially, and an hour later return ES02,EE04,ES21.