Reference Guide

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 by Requesting a Demo or by calling 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.

email

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.

Personator Search Result Codes

Reference Guide

Contents

Reference Guide#