Difference between revisions of "Personator Search:Request"

From Melissa Data Wiki
Jump to navigation Jump to search
(19 intermediate revisions by the same user not shown)
Line 9: Line 9:


The web service supports REST and JSON protocols.
The web service supports REST and JSON protocols.
==URL==
{{URL-PersonatorSearch}}




Line 19: Line 23:
|Transmission Reference || t
|Transmission Reference || t
|-
|-
|License || id
|License Key || id
|-
|-
|Options || opt
|Options || opt
Line 32: Line 36:
|-
|-
|Last Name || last
|Last Name || last
|-
|Company || comp
|-
|-
|Address Line 1 || a1
|Address Line 1 || a1
Line 41: Line 43:
|State || state
|State || state
|-
|-
|Postal || postal
|Postal Code || postal
|-
|-
|Phone Number || phone
|Phone Number || phone
Line 48: Line 50:
|-
|-
|Melissa Address Key (MAK) || mak
|Melissa Address Key (MAK) || mak
|-
|Birth Day || bday
|-
|Birth Month || bmonth
|-
|Birth Year || byear
|}
|}


Line 66: Line 74:




<h3 style="background-color:rgb(240,240,240);">License</h3>
<h3 style="background-color:rgb(240,240,240);">License Key</h3>
:''Required.''
:''Required.''


Line 98: Line 106:
|-
|-
|<code>''OptionName'':''Parameter'',''OptionName'':''Parameter''</code>
|<code>''OptionName'':''Parameter'',''OptionName'':''Parameter''</code>
|}
:<h4 style="border-bottom:1px solid black;">AgeRange</h4>
::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.
::{| class="alternate01 sortable"
!Option Name !! Parameter !! Description
|-
|rowspan="2"|'''AgeRange'''||<code>#</code>||Sets the age to be returned, with a tolerance of 2 years. (Ex. 25 will return ages 23-27.)
|-
|<code>#-#</code>||Sets the age range to be returned, inclusive. (Ex. 25-30 includes 25, 26, 27, 28, 29, 30.)
|}
|}


Line 107: Line 129:
!Option Name !! Parameter !! Description
!Option Name !! Parameter !! Description
|-
|-
|'''MaxPhone'''||<code># [0 - #]</code>||'''''Default set to 3.''''' Sets the maximum number of emails to be returned.
|'''MaxEmail'''||<code># [0 - #]</code>||'''''Default set to 3.''''' Sets the maximum number of emails to be returned.
|}
|}


Line 160: Line 182:


:<h4 style="border-bottom:1px solid black;">SearchConditions</h4>
:<h4 style="border-bottom:1px solid black;">SearchConditions</h4>
::Specifies the type of search conditions to use when returning records. Only the populated input fields will be compared. A loose search condition is used by default.
::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.


::{| class="alternate01 sortable"
::{| class="alternate01 sortable"
!Option Name !! Parameter !! Description
!Option Name !! Parameter !! Description
|-
|-
|rowspan="2"|'''SearchConditions'''||<code>exact</code>||The input values should match the output values exactly.
|rowspan="4"|'''SearchConditions'''||<code>strict</code>||'''''Default.''''' The input values should match the output values exactly.
|-
|<code>progressive</code>||First acts like a strict search, then progressively drops inputs until a result is found.
|-
|<code>loose</code>||No filtering will be done. Raw record results will be returned.
|-
|-
|<code>loose</code>||'''''Default.''''' No filtering will be done. Raw record results will be returned.
|<code>batch</code>||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
|}
|}


Line 186: Line 216:
|-
|-
|<code>PhoneSearch</code>|| Uses phone data as the primary pivot when verifying or appending information.
|<code>PhoneSearch</code>|| Uses phone data as the primary pivot when verifying or appending information.
|-
|<code>SmartSearch</code>||
|-
|<code>StraightSearch</code>||
|}
|}


Line 195: Line 221:
:<h4 style="border-bottom:1px solid black;">SortBy</h4>
:<h4 style="border-bottom:1px solid black;">SortBy</h4>
::Allows sorting records in a particular order.
::Allows sorting records in a particular order.
::If ascending or descending is not specified, the default order will be ascending.


::{| class="alternate01 sortable"
::{| class="alternate01 sortable"
Line 235: Line 263:




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


:{| class="alternate01 sortable"
:{| class="alternate01 sortable"
!Field Name !! Default Group !! Groups !! GrpAll
!Field Name !! Default Group !! Groups !! GrpAll
|-
|-
|FullName||rowspan="13"|'''[DEFAULT]''' <br> Returned by default.||rowspan="3"|'''N/A'''||rowspan="19"|'''GrpAll'''
|FullName||rowspan="11"|'''[DEFAULT]''' <br> Returned by default.||rowspan="3"|'''N/A'''||rowspan="17"|'''GrpAll'''
|-
|-
|FirstName
|FirstName
Line 246: Line 274:
|LastName
|LastName
|-
|-
|AddressLine1||rowspan="10"|'''PreviousAddress'''
|AddressLine1||rowspan="8"|'''PreviousAddress'''
|-
|AddressLine2
|-
|-
|Suite
|Suite
Line 257: Line 283:
|-
|-
|PostalCode
|PostalCode
|-
|Suite
|-
|-
|Plus4
|Plus4
Line 266: Line 290:
|MelissaAddressKeyBase
|MelissaAddressKeyBase
|-
|-
|Phone||rowspan="6"|'''N/A'''||'''Phone'''
|Phone||rowspan="5"|'''N/A'''||'''Phone'''
|-
|-
|Email||'''Email'''
|Email||'''Email'''
Line 275: Line 299:
|-
|-
|DateOfBirth||'''DateOfBirth'''
|DateOfBirth||'''DateOfBirth'''
|-
|Sources*||'''Sources'''
|}
|}


Line 325: Line 347:
|-
|-
|REST||<code>&last = '''''string'''''</code>
|REST||<code>&last = '''''string'''''</code>
|}
<h3 style="background-color:rgb(240,240,240);">Company</h3>
:''Optional.''
:The company/organization name.
:{| class="alternate01"
!Protocol !! Syntax
|-
|REST||<code>&comp = '''''string'''''</code>
|}
|}


Line 376: Line 386:




<h3 style="background-color:rgb(240,240,240);">Postal</h3>
<h3 style="background-color:rgb(240,240,240);">Postal Code</h3>
:''Optional.''
:''Optional.''


Line 421: Line 431:
|-
|-
|REST||<code>&mak = '''''string'''''</code>
|REST||<code>&mak = '''''string'''''</code>
|}
<h3 style="background-color:rgb(240,240,240);">Birth Day</h3>
:''Optional.''
:The birth day for the record in <code>DD</code> format. Entering the Birth Day will filter results to return only when the day of birth matches.
:{| class="alternate01"
!Protocol !! Syntax
|-
|REST||<code>&bday = '''''string'''''</code>
|}
<h3 style="background-color:rgb(240,240,240);">Birth Month</h3>
:''Optional.''
:The birth month for the record in <code>MM</code> format. Entering the Birth Month will filter results to return only when the month of birth matches.
:{| class="alternate01"
!Protocol !! Syntax
|-
|REST||<code>&bmonth = '''''string'''''</code>
|}
<h3 style="background-color:rgb(240,240,240);">Birth Year</h3>
:''Optional.''
:The birth year for the record in <code>YYYY</code> format. Entering the Birth Year will filter results to return only when the year of birth matches.
:{| class="alternate01"
!Protocol !! Syntax
|-
|REST||<code>&byear = '''''string'''''</code>
|}
|}



Revision as of 00:32, 19 August 2022

← Personator Search

Personator Search Navigation
Introduction
Licensing
Input/Output
Request Fields
Response Fields
Examples
REST JSON
Result Codes
Result Code Use
Personator Search Result Codes
Sample Code



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
Transmission Reference t
License Key id
Options opt
Columns cols
Free Form ff
Full Name full
First Name first
Last Name last
Address Line 1 a1
City city
State state
Postal Code postal
Phone Number phone
Email Address email
Melissa Address Key (MAK) mak
Birth Day bday
Birth Month bmonth
Birth Year byear


Request Elements

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

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


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


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.
  1. Strict: Name, City, State, & Age
  2. Strict: Name, State, & Age
  3. Strict: Name & Age
  4. 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.


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.


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


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


First Name

Optional.
The first name.
Protocol Syntax
REST &first = string


Last Name

Optional.
The last name.
Protocol Syntax
REST &last = 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


City

Optional.
The city.
Protocol Syntax
REST &city = string


State

Optional.
The US state.
Protocol Syntax
REST &state = string


Postal Code

Optional.
The postal code.
Protocol Syntax
REST &postal = string


Phone Number

Optional.
The phone number.
Protocol Syntax
REST &phone = string


Email Address

Optional.
The email address.
Protocol Syntax
REST &email = string


Melissa Address Key (MAK)

Optional.
A propietary unique key identifier for an address.
Protocol Syntax
REST &mak = 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