Reference Guide#
Introduction#
Welcome to the Personator Search API. The Personator Search API is designed to enable the user to perform extremely flexible searches to Melissa Data’s consumer database. The Personator Search API is ideal for performing skip-tracing type searches, allowing you to search for consumer information with very limited amount of information, such as having just the person’s name. This flexible consumer search API also allows for restoring missing information from your data, which are typically not correctable, such as appending a missing address line, based off a person’s name and a general location such as a city.
The Personator Search API leverages a combination of a multitude of premium data sources, including consumer data, credit data, demographic data, government data, telco data, and several others. Through these combined sources, we are able to compile a database of billions of records containing current and historical data for an individual’s addresses, phone numbers, and emails.
Base URL#
https://personatorsearch.melissadata.net/WEB/doPersonatorSearch
Licensing#
The License Key is a software key required to use the web service. You will receive your license key from your Melissa representative. If you don’t have a license key, contact the Melissa sales team at sales@melissa.com or 800-MELISSA ext. 3 (800-635-4772 ext. 3). Without a license key, Personator Search will not function.
To set the license key, use the id/CustomerID property in your requests.
Endpoints#
WEB/doPersonatorSearch#
Use this endpoint to use search for consumer information using name and address
Try It Now#
curl -X GET "https://personatorsearch.melissadata.net/WEB/doPersonatorSearch\
?id={{customerId}}\
&full=Melissa%20Data\
&a1=22382%20Avenida%20Empresa\
&city=Rancho%20Santa%20Margarita\
&state=CA\
&postal=92688"
Request Parameters#
Code |
Description |
||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Record Level Parameters |
|||||||||||||
cols |
The column names or groups to be output. See Columns for more information. |
||||||||||||
ff |
Accepts delimited or undelimited free form input. This will be parsed by the service. |
||||||||||||
id |
The License Key issued by Melissa. |
||||||||||||
opt |
|||||||||||||
t |
This is a string value that serves as a unique identifier for this set of records. It is returned as sent. |
||||||||||||
Record Parameters |
|||||||||||||
a1 |
The input field for the address. 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. |
||||||||||||
bday |
The birth day for the record in |
||||||||||||
bmonth |
The birth month for the record in |
||||||||||||
byear |
The birth year for the record in |
||||||||||||
city |
The city. |
||||||||||||
The email address. |
|||||||||||||
first |
The first name. |
||||||||||||
full |
The full name. |
||||||||||||
last |
The last name. |
||||||||||||
mak |
A proprietary unique key identifier for an address. |
||||||||||||
mik |
A proprietary unique key identifier for an individual. |
||||||||||||
phone |
The phone number. |
||||||||||||
postal |
The postal code. |
||||||||||||
state |
The state. |
Columns#
Entering the column name will return the column. Specifying a group name will return all columns in the group.
Delimit multiple columns with a ,
.
Group Name |
Included Fields |
|||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
|
||||||||||||
[DEFAULT] CurrentAddress - This returns the current address in an object container. |
|
|||||||||||
GrpAll - This group will return all available fields. |
[All Fields] |
|||||||||||
PreviousAddress - This returns any previous addresses in an array of object containers. |
|
|||||||||||
DateOfBirth - This field returns as part of the respective record object in the Records array. |
DateOfBirth |
|||||||||||
DateOfDeath - This field returns as part of the respective record object in the Records array. |
DateOfDeath |
|||||||||||
Email - This field returns as an EmailRecords array containing the email field. |
||||||||||||
MoveDate - This field returns as part of the CurrentAddress object. |
MoveDate |
|||||||||||
Phone - This field returns as an PhoneRecords array containing the phoneNumber field. |
phoneNumber |
Options#
List options in the following format, with multiple options delimited with a ;
.
OptionName:Parameter;OptionName:Parameter
AgeRange#
Sets the range of ages returned. Default will return all ages.
If a record does not have a birth date or age, that record will not be returned.
Parameter |
Description |
---|---|
# |
Sets the age to be returned, with a tolerance of 2 years. (Ex. 25 will return ages 23-27.) |
#-# |
Sets the age range to be returned, inclusive. (Ex. 25-30 includes 25, 26, 27, 28, 29, 30.) |
MaxEmail#
Sets the maximum number of emails that can be returned. Default maximum is “3” if this option is not set.
Parameter |
Description |
---|---|
# [0 - #] |
Default set to 3. Sets the maximum number of emails to be returned. |
MaxPhone#
Sets the maximum number of phone numbers that can be returned. Default maximum is “3” if this option is not set.
Parameter |
Description |
---|---|
# [0 - #] |
Default set to 3. Sets the maximum number of phone numbers to be returned |
NameHint#
Sets the name hint for the input name.
Parameter |
Description |
---|---|
definitelyfull |
Name will always be treated as normal name order, regardless of 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. |
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. |
varying |
Default. If necessary, statistical logic will be employed to determine name order, with no bias toward either name order. |
verylikelyfull |
Name will be treated as normal name order unless inverse order is clearly indicated by formatting or punctuation. |
verylikelyinverse |
Name will be treated as inverse name order unless normal order is clearly indicated by formatting or punctuation. |
Page#
Specifies which “page” to return for a given request. Your “page” length is set by RecordsPerPage.
If your request returns more than your RecordsPerPage, these records will be split into “pages”. Use this option to select which “page” to view. If your specified “page” is out of the range of possible “page” numbers, an error will be returned.
This option is ignored if the option ReturnAllPages is set to “true”.
Parameter |
Description |
---|---|
# [0 - #] |
Specifies which “page” to return. |
RecordsPerPage#
Specifies how many records are in a “page”. The default value is 5.
This option is ignored if the option ReturnAllPages is set to “true”.
Parameter |
Description |
---|---|
# [0 - #] |
Default set to 5. Sets the records per “page”. |
ReturnAllPages#
Parameter |
Description |
---|---|
false |
Default. Will not return all records. |
true |
Will return all records up to a limit of 500. |
SearchConditions#
Specifies the type of search conditions to use when returning records. Only the populated input fields will be compared. A strict search condition is used by default.
Parameter |
Description |
---|---|
batch |
Runs through a set of 4 calls, returning the first result found.
|
loose |
No filtering will be done. Raw record results will be returned. |
progressive |
First acts like a strict search, then progressively drops inputs until a result is found. |
strict |
Default. The input values should match the output values exactly. |
SearchType#
This options allows you to specify the type of search to perform.
Parameter |
Description |
---|---|
AddressSearch |
Uses address data as the primary pivot when verifying or appending information. |
Auto |
Default. Performs name, address, email, and phone searches until one or more matches are found. |
EmailSearch |
Uses email data as the primary pivot when verifying or appending information. |
NameSearch |
Uses name data as the primary pivot when verifying or appending information. |
PhoneSearch |
Uses phone data as the primary pivot when verifying or appending information. |
ShowAllRecords#
This options allows you to return historical/outdated information records that have not been verified in recent sources. While more information is returned, not all information may be as accurate.
Ex: &opt=ShowAllRecords
Parameter |
Description |
---|---|
[None] |
Enables Personator Search to return historical/outdated information. |
SortBy#
Allows sorting records in a particular order.
If ascending or descending is not specified, the default order will be ascending.
Parameter |
Description |
---|---|
AddressLine1-ascending |
Sort by address line 1. |
AddressLine1-descending |
Sort by address line 1. |
CityState-ascending |
Sort by state then city. |
CityState-descending |
Sort by state then city. |
DateOfBirth-ascending |
Sort by date of birth. |
DateOfBirth-descending |
Sort by date of birth. |
DateOfDeath-ascending |
Sort by date of death. |
DateOfDeath-descending |
Sort by date of death. |
FirstName-ascending |
Sort by first name. |
FirstName-descending |
Sort by first name. |
FullName-ascending |
Sort by full name. |
FullName-descending |
Sort by full name. |
LastName-ascending |
Sort by last name. |
LastName-descending |
Sort by last name. |
MelissaAddressKeyBase-ascending |
Sort by Melissa Address Key Base. |
MelissaAddressKeyBase-descending |
Sort by Melissa Address Key Base. |
MoveDate-ascending |
Sort by move date. |
MoveDate-descending |
Sort by move date. |
PostalCode-ascending |
Sort by postal code. Plus4 is also included with the ordering. |
PostalCode-descending |
Sort by postal code. Plus4 is also included with the ordering. |
Headers#
Content-Type: application/json
Accept: application/json
Response#
{
"TransmissionResults": "US01",
"TransmissionReference": "",
"TotalPages": "1",
"TotalRecords": "1",
"Version": "7.0.1.1115",
"Records": [
{
"RecordID": "1",
"Results": "VR01",
"FullName": "Melissa MelissaData Data",
"FirstName": "Melissa",
"MiddleName": "MelissaData",
"LastName": "Data",
"CurrentAddress": {
"AddressLine1": "22382 Avenida Empresa",
"Suite": "",
"City": "Rancho Santa Margarita",
"State": "CA",
"PostalCode": "92688",
"Plus4": "2112",
"MelissaAddressKey": "8008006245",
"MelissaAddressKeyBase": ""
}
}
]
}
Service Level Response Fields#
Output Name |
Description |
---|---|
Results |
This is a string value that lists result codes for the most recent request as a whole. For a complete list of result codes, see Personator Search Result Codes. |
TotalPages |
This is a string value containing the number of totla pages returned by the request. The amount of records per page is set within the RecordsPerPage option |
TotalRecords |
This is a string value containing the number of total records returned by the request, up to a maximum of 500. |
TransmissionReference |
This is a string value that serves as a unique identifier for this request. It is returned as sent in the request, allowing you to match the response to the request. |
TransmissionResults |
This is a string value that lists result codes from the web service. For a complete list of result codes, see Personator Search Result Codes. |
Version |
This is a string value that is the current revision number of Personator Search web service. |
Record Level Response Fields#
[Default]#
Output Name |
Description |
---|---|
CurrentAddress |
This is an object container holding the current address fields. |
RecordID |
This is a string value that is a unique identifier for the current record if one was sent in the request. Use this element to match a request record and the corresponding response record. |
CurrentAddress#
The current address in an object container.
Output Name |
Description |
---|---|
AddressLine1 |
Returns address line 1. |
City |
Returns the city. |
FirstName |
Returns the first name. |
FullName |
Returns the full name. |
LastName |
Returns the last name. |
MelissaAddressKey |
Returns a unique key associated with an address. |
MelissaAddressKeyBase |
Returns a unique key associated with a building containing multiple suites/apartments. |
Plus4 |
Returns the 4-digit plus4 for the address. |
PostalCode |
Returns the 5-digit postal code for U.S. addresses and 6-digit postal code for Canadian addresses. |
State |
Returns the state. |
Suite |
Returns the suite. |
PreviousAddress#
Any previous addresses in an array of object containers.
Output Name |
Description |
---|---|
AddressLine1 |
Returns address line 1. |
City |
Returns the city. |
FirstName |
Returns the first name. |
FullName |
Returns the full name. |
LastName |
Returns the last name. |
MelissaAddressKey |
Returns a unique key associated with an address. |
MelissaAddressKeyBase |
Returns a unique key associated with a building containing multiple suites/apartments. |
Plus4 |
Returns the 4-digit plus4 for the address. |
PostalCode |
Returns the 5-digit postal code for U.S. addresses and 6-digit postal code for Canadian addresses. |
State |
Returns the state. |
Suite |
Returns the suite. |
DateOfBirth#
Output Name |
Description |
---|---|
DateOfBirth |
Returns the date of birth in the format |
DateOfDeath#
Output Name |
Description |
---|---|
DateOfDeath |
This is a string value of the date of death of the individual. |
MelissaIdentityKey#
Output Name |
Description |
---|---|
MelissaIdentityKey |
Returns a unique key associated with a person. |
Email#
This returns an EmailRecords
array containing the field below:
Output Name |
Description |
---|---|
Returns the email address associated with the individual. |
MoveDate#
Output Name |
Description |
---|---|
MoveDate |
Returns the date the individual moved-in to this address in the format |
Phone#
This returns a PhoneRecords
array containing the field below:
Output Name |
Description |
---|---|
phoneNumber |
Returns the standardized phone number for the record. |
Result Codes#
For details of all result code please visit here.
Melissa Data’s products use a result code system to indicate data quality; the status and any errors.
These result codes are four-character codes (two letters followed by two numbers), delimited by commas.
Result code definitions are shared among Melissa Data products.
Understanding the Code#
To fully understand result codes, you need to know them. Knowing what codes are possible and what they indicate will be key in building an effective application.
It is useful to know all the codes, but this does not necessarily mean you will use them all. Just because you have a toolbox, doesn’t mean you will also try to use a screwdriver along with a hammer on a nail.
Record Level Result Codes#
Code |
Short Description |
Long Description |
---|---|---|
BA - Batch Result |
||
|
Batch Result 01 |
The search condition matched the batch result: Strict: Name, City, State, & Age. |
|
Batch Result 02 |
The search condition matched the batch result: Strict: Name, State, & Age. |
|
Batch Result 03 |
The search condition matched the batch result: Strict: Name & Age. |
|
Batch Result 04 |
The search condition matched the batch result: Loose: Name & Age. |
VS - Verify Status |
||
|
Historical Address Match |
The current address is outdated and a newer address match was found. Use the “Move” action to get the latest address. |
|
Partial Address Match |
A match was made to a partial address. This could be due to matching the street address but not to the suite. |
|
Last Name Match |
A match was made to the last name only. |
|
First Name Match |
A match was made to the first name only. |
US - Personator Search Status |
||
|
Match Found |
A match was found in the data. |
|
No Exact Match Found |
No exact match was found, partial matches were returned. |
|
Too Many Matches |
There were too many matches found. Please narrow down your search by entering additional contact information. |
UE - Personator Search Error |
||
|
No Match |
No match was found. |
|
Record Limit Exceeded |
Number of records returned by the Web Service is too many. Please refine your search. |
|
Invalid Page Number |
The requested Page Number is invalid or not within the possible number of pages. Refer to the TotalPages Output Column to determine the total number of pages possible. |
|
No Exact Matches |
No exact matches found for SearchCondition:Exact. However, results will be returned for a loose search (SearchCondition:Loose). |
|
Invalid State or Zip |
Invalid State or Zip. |
|
Name Character Limit Exceeded |
The FirstName or LastName exceeded 30 characters. |
SE - Transimission Service Error |
||
|
Cloud Service Internal Error |
The cloud service experienced an internal error. |
GW - General Transmission Warning |
||
|
Expiring License |
Your License Key is expiring soon. Please contact your sales representative for a new License Key. |
|
Option Name Error |
The option name is either misspelled or incorrect. |
|
Option Value Error |
The option value is misspelled or incorrectly formatted. |
GE - General Transmission Error |
||
|
Empty Request Structure |
The SOAP, JSON, or XML request structure is empty. Not to be confused with the GE01 GeoCode result code. |
|
Empty Request Record Structure |
The SOAP, JSON, or XML request record structure is empty. Not to be confused with the GE02 GeoCode result code. |
|
Records Per Request Exceeded |
The counted records sent more than the number of records allowed per request. |
|
Empty License Key |
The License Key is empty. |
|
Invalid License Key |
The License Key is invalid. |
|
Disabled License Key |
The License Key is disabled. |
|
Invalid Request |
The SOAP, JSON, or XML request is invalid. |
|
Product/Level Not Enabled |
The License Key is invalid for this product or level. |
|
Customer Does Not Exist |
The Customer ID is not in our system. |
|
Customer License Disabled |
The encrypted license is on the ban list. |
|
Customer Disabled |
The Customer ID is disabled. |
|
IP Blacklisted |
The IP Address is on the global ban list. |
|
IP Not Whitelisted |
The IP Address is not on the customer’s whitelist. |
|
Out of Credits |
The account has ran out of credits. Add more credits to continue using the service. |
|
Unacceptable License Key |
License key not accepted, please request an encrypted license key from your sales representative. |
|
Verify Not Activated |
The Verify package was requested but is not active for the License Key. |
|
Append Not Activated |
The Append package was requested but is not active for the License Key. |
|
Move Not Activated |
The Move package was requested but is not active for the License Key. |
|
No Valid Action Requested |
No valid action was requested by the service. The request must include at least one of the following actions: Check, Verify, Append, or Move. |
|
Demographics Not Activated |
The Demographics package was requested but is not active for the License Key. |
|
No License For Business Demographic |
The License Key is not subscribed/licensed for the requested business demographic(s). |
|
CallerID Not Enabled |
The license key or ID does not have CallerID enabled. |
|
IP Columns Not Activated |
IP Columns requested but not active for the customer ID. |
|
SSN Verification Not Activated |
SSN Verification requested but not active for the customer ID. |
|
Not Available for Credit License |
The requested fields were not available for a credit license. To have access to the demographics fields, please upgrade your license to a subscription. |
|
Job ID Not Found |
The job ID was not found. |
|
Job Not Ready |
The job is not ready. |
|
No Record in Job |
There was no record found in the job. |
|
Record Total Mismatch |
The received record total does not match the user-specified RecordCount. |
|
Job in Queue |
The job is in the queue. |
|
Job Processing |
The job is being processed. |
|
Job Complete |
The job is complete. |
|
Cloud Service Internal Error |
The cloud service experienced an internal error. |
|
DataFrame Not Found |
The DataFrame was not found. |