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 #

GET JSON

curl -X GET "https://personatorsearch.melissadata.net/WEB/doPersonatorSearch?\
&id={{customerId}}\
&t=Test\
&a1=22382%20Avenida%20Empresa\
&city=Rancho%20Santa%20Margarita\
&full=Melissa%20Data\
&postal=92688\
&state=CA"

Request Parameters #

GET JSON

Code

Description

Record Level Parameters

cols

The column names or groups to be output. See Columns for more information.

id

The License Key issued by Melissa.

opt

Set Options
AgeRange
MaxEmail
MaxPhone
MaxHint
Page
RecordsPerPage
ReturnAllPages
SearchConditions
SearchType
ShowAllRecords
SortBy

t

Optional. Serves as a unique request identifier.

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.

ageapprox

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

agegt

Optional. Filter results to return individuals who’s age is greater than the provided age.

agelt

Optional. Filter results to return individuals who’s age is less than the provided age.

bday

The birth day for the record in DD format. Entering the Birth Day will filter results to return only when the day of birth matches.

bmonth

The birth month for the record in MM format. Entering the Birth Month will filter results to return only when the month of birth matches.

byear

The birth year for the record in YYYY format. Entering the Birth Year will filter results to return only when the year of birth matches.

city

The city.

email

The email address.

ff

Accepts delimited or undelimited free form input. This will be parsed by the service.

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. Each individual is assigned a unique MIK number in the Melissa Personator Database.

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] Always return in the output structure.

CurrentAddress

RecordID

Results

TotalPages

TotalRecords

TransmissionReference

TransmissionResults

Version

[DEFAULT] CurrentAddress - This returns the current address in an object container.

AddressLine1

City

FirstName

FullName

LastName

MelissaAddressKey

MelissaAddressKeyBase

Plus4

PostalCode

State

Suite

GrpAll - This group will return all available fields.

[All Fields]

PreviousAddress - This returns any previous addresses in an array of object containers.

AddressLine1

City

FirstName

FullName

LastName

MelissaAddressKey

MelissaAddressKeyBase

Plus4

PostalCode

State

Suite

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. Strict: Name, City, State, & Age Strict: Name, State, & Age Strict: Name & Age Loose: Name & Age
`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 #

GET JSON

Content-Type: application/json
Accept: application/json

Response #

GET JSON

{
   "TransmissionResults": "US01",
   "TransmissionReference": "Test",
   "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	A pass-through of the input TransmissionReference field.
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 `YYYYMM`. Accuracy is only to the month.

DateOfDeath #

Output Name	Description
DateOfDeath	This is a string value of the date of death of the individual. `YYYYMMDD` Format.

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
email	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 `YYYYMMDD`.

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
`BA01`	Batch Result 01	The search condition matched the batch result: Strict: Name, City, State, & Age.
`BA02`	Batch Result 02	The search condition matched the batch result: Strict: Name, State, & Age.
`BA03`	Batch Result 03	The search condition matched the batch result: Strict: Name & Age.
`BA04`	Batch Result 04	The search condition matched the batch result: Loose: Name & Age.
VS - Verify Status
`VS01`	Historical Address Match	The current address is outdated and a newer address match was found. Use the “Move” action to get the latest address.
`VS02`	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.
`VS12`	Last Name Match	A match was made to the last name only.
`VS13`	First Name Match	A match was made to the first name only.
US - Personator Search Status
`US01`	Match Found	A match was found in the data.
`US02`	No Exact Match Found	No exact match was found, partial matches were returned.
`US03`	Too Many Matches	There were too many matches found. Please narrow down your search by entering additional contact information.
UE - Personator Search Error
`UE01`	No Match	No match was found.
`UE02`	Record Limit Exceeded	Number of records returned by the Web Service is too many. Please refine your search.
`UE03`	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.
`UE04`	No Exact Matches	No exact matches found for SearchCondition:Exact. However, results will be returned for a loose search (SearchCondition:Loose).
`UE05`	Invalid State or Zip	Invalid State or Zip.
`UE06`	Name Character Limit Exceeded	The FirstName or LastName exceeded 30 characters.
SE - Transimission Service Error
`SE01`	Cloud Service Internal Error	The cloud service experienced an internal error.
GW - General Transmission Warning
`GW01`	Expiring License	Your License Key is expiring soon. Please contact your sales representative for a new License Key.
`GW11`	Option Name Error	The option name is either misspelled or incorrect.
`GW12`	Option Value Error	The option value is misspelled or incorrectly formatted.
GE - General Transmission Error
`GE01`	Empty Request Structure	The SOAP, JSON, or XML request structure is empty. Not to be confused with the GE01 GeoCode result code.
`GE02`	Empty Request Record Structure	The SOAP, JSON, or XML request record structure is empty. Not to be confused with the GE02 GeoCode result code.
`GE03`	Records Per Request Exceeded	The counted records sent more than the number of records allowed per request.
`GE04`	Empty License Key	The License Key is empty.
`GE05`	Invalid License Key	The License Key is invalid.
`GE06`	Disabled License Key	The License Key is disabled.
`GE07`	Invalid Request	The SOAP, JSON, or XML request is invalid.
`GE08`	Product/Level Not Enabled	The License Key is invalid for this product or level.
`GE09`	Customer Does Not Exist	The Customer ID is not in our system.
`GE10`	Customer License Disabled	The encrypted license is on the ban list.
`GE11`	Customer Disabled	The Customer ID is disabled.
`GE12`	IP Blacklisted	The IP Address is on the global ban list.
`GE13`	IP Not Whitelisted	The IP Address is not on the customer’s whitelist.
`GE14`	Out of Credits	The account has ran out of credits. Add more credits to continue using the service.
`GE15`	Unacceptable License Key	License key not accepted, please request an encrypted license key from your sales representative.
`GE20`	Verify Not Activated	The Verify package was requested but is not active for the License Key.
`GE21`	Append Not Activated	The Append package was requested but is not active for the License Key.
`GE22`	Move Not Activated	The Move package was requested but is not active for the License Key.
`GE23`	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.
`GE24`	Demographics Not Activated	The Demographics package was requested but is not active for the License Key.
`GE25`	No License For Business Demographic	The License Key is not subscribed/licensed for the requested business demographic(s).
`GE26`	CallerID Not Enabled	The license key or ID does not have CallerID enabled.
`GE27`	IP Columns Not Activated	IP Columns requested but not active for the customer ID.
`GE28`	SSN Verification Not Activated	SSN Verification requested but not active for the customer ID.
`GE29`	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.
`GE50`	Job ID Not Found	The job ID was not found.
`GE51`	Job Not Ready	The job is not ready.
`GE52`	No Record in Job	There was no record found in the job.
`GE53`	Record Total Mismatch	The received record total does not match the user-specified RecordCount.
`GE54`	Job in Queue	The job is in the queue.
`GE55`	Job Processing	The job is being processed.
`GE56`	Job Complete	The job is complete.
`GE57`	Cloud Service Internal Error	The cloud service experienced an internal error.
`GE59`	DataFrame Not Found	The DataFrame was not found.

Reference Guide

Contents

Reference Guide#