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}}\
&full=Melissa%20Data\
&a1=22382%20Avenida%20Empresa\
&city=Rancho%20Santa%20Margarita\
&state=CA\
&postal=92688"

Request Parameters#

  • GET JSON

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

Set Options

AgeRange

MaxEmail

MaxPhone

MaxHint

Page

RecordsPerPage

ReturnAllPages

SearchConditions

SearchType

ShowAllRecords

SortBy

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

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

  1. Strict: Name, City, State, & Age

  2. Strict: Name, State, & Age

  3. Strict: Name & Age

  4. 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": "",
    "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 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.