Personator Search:Request

← Personator Search

A request consists of a protocol to make a call to the service, detailing desired elements. The minimum required elements in a request are your Customer ID (License Key) and the fields listed as Required below.

The web service supports REST and JSON protocols.

URL

REST, JSON

Use	URL
Standard	http://personatorsearch.melissadata.net/WEB/doPersonatorSearch
Secure	https://personatorsearch.melissadata.net/WEB/doPersonatorSearch

Field Names

This is a list of the request field names and their protocol naming conventions.

Field Name	REST
Columns	cols
License Key	id
Options	opt
Transmission Reference	t
Address Line 1	a1
Age Approximate	ageapprox
Age Greater Than	agegt
Age Less Than	agelt
Birth Day	bday
Birth Month	bmonth
Birth Year	byear
City	city
Email Address	email
First Name	first
Free Form	ff
Full Name	full
Last Name	last
Melissa Address Key (MAK)	mak
Melissa Identity Key (MIK)	mik
Phone Number	phone
Postal Code	postal
State	state

Request Elements

The following elements set the basic options for each request. These apply to the entire request, not the individual records.

Columns

Optional.

Specifies which column(s) to be output as a column delimited string.

Protocol	Syntax
REST	&cols = string

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

Field Name	Default Group	Groups	GrpAll
FullName	[DEFAULT] Returned by default.	N/A	GrpAll
FirstName
LastName
AddressLine1		PreviousAddress
Suite
City
State
PostalCode
Plus4
MelissaAddressKey
MelissaAddressKeyBase
Phone	N/A	Phone
Email		Email
MoveDate		MoveDate
DateOfDeath		DateOfDeath
DateOfBirth		DateOfBirth

License Key

Required.

This is a string value containing the License Key issued to the customer by Melissa Data for the web service.

If this element is absent, the web service will return an error. To receive a License Key, please contact your Melissa Data sales representative at 1-800-MELISSA.

Protocol	Syntax
REST	&id = string

Options

Optional.

Specifies the options. See the options below for more information.

Protocol	Syntax
REST	&opt = string

List options in the following format, with multiple options delimited with a ",".

Syntax
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.

Option Name	Parameter	Description
AgeRange	#	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.

Option Name	Parameter	Description
MaxEmail	# [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.

Option Name	Parameter	Description
MaxPhone	# [0 - #]	Default set to 3. Sets the maximum number of phone numbers to be returned

NameHint

Sets the name hint for the input name.

Option Name	Parameter	Description
NameHint	varying	Default. If necessary, statistical logic will be employed to determine name order, with no bias toward either name order.
	definitelyfull	Name will always be treated as normal name order, regardless of formatting or punctuation.
	verylikelyfull	Name will be treated as normal name order unless inverse order is clearly indicated by formatting or punctuation.
	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.
	verylikelyinverse	Name will be treated as inverse name order unless normal order is clearly indicated by 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.

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".

Option Name	Parameter	Description
Page	# [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".

Option Name	Parameter	Description
RecordsPerPage	# [0 - #]	Default set to 5. Sets the records per "page".

ReturnAllPages

Option Name	Parameter	Description
ReturnAllPages	true	Will return all records up to a limit of 500.
	false	Default. Will not return all records.

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.

Option Name	Parameter	Description
SearchConditions	strict	Default. The input values should match the output values exactly.
	progressive	First acts like a strict search, then progressively drops inputs until a result is found.
	loose	No filtering will be done. Raw record results will be returned.
	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

SearchType

This options allows you to specify the type of search to perform.

Option Name	Parameter	Description
SearchType	Auto	Default. Performs name, address, email, and phone searches until one or more matches are found.
	NameSearch	Uses name data as the primary pivot when verifying or appending information.
	AddressSearch	Uses address data as the primary pivot when verifying or appending information.
	EmailSearch	Uses email 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.

Option Name	Parameter	Description
ShowAllRecords	[None]	Enables Personator Search to return historical/outdated information.

Ex: &opt=ShowAllRecords

SortBy

Allows sorting records in a particular order.

If ascending or descending is not specified, the default order will be ascending.

Option Name	Parameter	Description
SortBy	PostalCode-ascending PostalCode-descending	Sort by postal code. Plus4 is also included with the ordering.
	CityState-ascending CityState-descending	Sort by state then city.
	AddressLine1-ascending AddressLine1-descending	Sort by address line 1.
	FullName-ascending FullName-descending	Sort by full name.
	FirstName-ascending FirstName-descending	Sort by first name.
	LastName-ascending LastName-descending	Sort by last name.
	DateOfBirth-ascending DateOfBirth-descending	Sort by date of birth.
	DateOfDeath-ascending DateOfDeath-descending	Sort by date of death.
	MoveDate-ascending MoveDate-descending	Sort by move date.
	MelissaAddressKey-ascending MelissaAddressKey-descending	Sort by Melissa Address Key.
	MelissaAddressKeyBase-ascending MelissaAddressKeyBase-descending	Sort by Melissa Address Key Base.

Transmission Reference

Optional.

This is a string value that serves as a unique identifier for this set of records. It is returned as sent.

Protocol	Syntax
REST	?t = string

Address Line 1

Optional.

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.

Protocol	Syntax
REST	&a1 = string

Age Approximate

Optional.

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

Protocol	Syntax
REST	&ageapprox = string

Age Greater Than

Optional.

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

Protocol	Syntax
REST	&agegt = string

Age Less Than

Optional.

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

Protocol	Syntax
REST	&agelt = string

Birth Day

Optional.

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.

Protocol	Syntax
REST	&bday = string

Birth Month

Optional.

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.

Protocol	Syntax
REST	&bmonth = string

Birth Year

Optional.

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.

Protocol	Syntax
REST	&byear = string

City

Optional.

The city.

Protocol	Syntax
REST	&city = string

Email Address

Optional.

The email address.

Protocol	Syntax
REST	&email = string

First Name

Optional.

The first name.

Protocol	Syntax
REST	&first = string

Free Form

Optional.

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

Protocol	Syntax
REST	&ff = string

Full Name

Recommended.

The full name.

Protocol	Syntax
REST	&full = string

Last Name

Optional.

The last name.

Protocol	Syntax
REST	&last = string

Melissa Address Key (MAK)

Optional.

A propietary unique key identifier for an address.

Protocol	Syntax
REST	&mak = string

Melissa Identity Key (MIK)

Optional.

The input field for the Melissa Identity Key. Each individual is assigned a unique MIK number in the Melissa Personator Database.

Protocol	Syntax
REST	&mik = string

Phone Number

Optional.

The phone number.

Protocol	Syntax
REST	&phone = string

Postal Code

Optional.

The postal code.

Protocol	Syntax
REST	&postal = string

State

Optional.

The US state.

Protocol	Syntax
REST	&state = string