Personator Identity:Request

← Personator Identity

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
Secure	https://globalpersonator.melissadata.net/v1/doContactVerify

Field Names

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

Field Name	REST	JSON
Transmission Reference	t	TransmissionReference
Customer ID	id	CustomerID
Actions	act	Actions
Address options	addrOpt	AddressOptions
Name options	nameOpt	NameOptions
Email options	emailOpt	EmailOptions
Phone options	phoneOpt	PhoneOptions
Options	opt	Options
National ID	nat	NationalID
First name	first	FirstName
Last name	last	LastName
Full name	full	FullName
Company	comp	Company
Phone number	phone	PhoneNumber
Email	email	Email
Date of birth	dob	DateOfBirth
Account Number	accountNumber	AccountNumber
Address line 1	a1	AddressLine1
Address line 2	a2	AddressLine2
Address line 3	a3	AddressLine3
Address line 4	a4	AddressLine4
Address line 5	a5	AddressLine5
Address line 6	a6	AddressLine6
Address line 7	a7	AddressLine7
Address line 8	a8	AddressLine8
Locality	loc	Locality
Administrative area	admarea	AdministrativeArea
Postal code	postal	PostalCode
Country	ctry	Country
Country of origin	ctryorg	CountryOfOrigin

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
JSON	"TransmissionReference":"string"
REST	?t = string

Customer ID

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
JSON	"CustomerID":"string"
REST	&id = string

Actions

Required.

This field determines what actions the service will perform on the input data. These actions are available:

• Check

Determines whether the data within a submitted record is valid, e.g. whether or not a given postal code contains the given city. It can also make limited corrections and appends to the data. Check looks at each data point separately.

• Verify

After the data has been checked, identity verification is performed and result codes (KV*) are returned to indicate what pieces of input data have been matched against trusted referenced data.

• Screen

Screens the provided input against various government sanctions and watchlists and returns back a list of matches. For a list of used watchlists, see Personator Identity Watchlists.

For every request, a Check action is always performed on the input.

Protocol	Syntax
JSON	"Actions":"string"
REST	&act = string

Address Options

Optional.

This is a string value containing the address options set by the user when the address is being validated during the Check action.

Protocol	Syntax
JSON	"AddressOptions":"string"
REST	&addrOpt = string

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

Syntax
OptionName:Parameter,OptionName:Parameter

DeliveryLines

This options allows you to specify if the Address Lines 1-8 should contain just the delivery address or the entire address.

Option Name	Parameter	Description
DeliveryLines	Off	Default. Address Lines 1-8 return the entire address.
	On	Address Lines 1-8 return just the street address and dependent locality. It will not contain locality, administrative area, postal code, etc.

LineSeparator

This is the line separator used for the FormattedAddress result.

Option Name	Parameter	Description
LineSeparator	SEMICOLON	Default. A semicolon (;).
	PIPE	A pipe (|).
	CR	A carriage return.
	LF	A line feed.
	CRLF	A carriage return + line feed.
	TAB	A tab.
	BR	A line break.

OutputScript

This is the script type used for all applicable fields.

Option Name	Parameter	Description
OutputScript	NOCHANGE	Default. Returns the same script that is sent in.
	LATN	Returns in the Latin script.
	NATIVE	Returns in the native script for the designated country.

CountryOfOrigin

This is used to determine whether or not to include the country name as the last line in FormattedAddress.

Option Name	Parameter	Description
CountryOfOrigin	(Any valid ISO-3166-1 Alpha-2, ISO-3166-1 Alpha-3, or ISO-3166-1 Numeric code)	If blank, invalid, or the same as the destination country, then the destination country is not appended to the end of the formatted address. If valid and different from the destination country, then the destination country is appended to the formatted address. US or US Territory: If CountryOfOrigin and destination country being verified are both US or US Territories then the country will not be appended to FormattedAddress. US Territories will have "United States of America" appended if the CountryOfOrigin is not a US Territory, but the CountryName and ISO codes will be that of the territory. Canada is treated like any other non-US Territory.

Name Options

Optional.

This is a string value containing the name options set by the user when the name is being validated during the Check action.

Protocol	Syntax
JSON	"NameOptions":"string"
REST	&nameOpt = string

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

Syntax
OptionName:Parameter,OptionName:Parameter

CorrectFirstName

This option enables or disables spelling correction of first names.

A database of commonly misspelled first names is used to correct the values of the First Name properties.

Option Name	Parameter	Description
CorrectFirstName	OFF	Default. Preserve first name spellings; no correction allowed.
	ON	Allows first name misspelling corrections.

NameHint

This option sets the most likely format of the FullName input string.

This helps the service in cases where the order and formatting of the FullName input string are unclear.

• Full or normal name order is: <Prefix> <First> <Middle> <Last> <Suffix>.
• Inverse name order is: <Last> <Suffix>, <Prefix> <First> <Middle>.

Either the Code or Name listed below can be used to set the action.

For example, Options = NAMEHINT:4 and Options = NAMEHINT:Varying are equivalent settings.

Option Name	Parameter Code	Parameter Name	Definition
NameHint	1	DefinitelyFull	Name will always be treated as normal name order regardless of formatting or punctuation.
	2	VeryLikelyFull	Name will be treated as normal name order unless inverse order is clearly indicated by formatting or punctuation.
	3	ProbablyFull	If necessary, statistical logic will be employed to determine name order, with a bias towards normal name order.
	4	Varying	Default. If necessary, statistical logic will be employed to determine name order, with no bias toward either name order.
	5	ProbablyInverse	If necessary, statistical logic will be employed to determine name order, with a bias toward inverse name order.
	6	VeryLikelyInverse	Name will be treated as inverse name order unless normal order is clearly indicated by formatting or punctuation.
	7	DefinitelyInverse	Name will always be treated as inverse name order, regardless of formatting or punctuation.
	8	MixedFirstName	Name element is expected to only contain first names.
	9	MixedLastName	Name element is expected to only contain last names.

GenderPopulation

This option sets the gender balance of the source data, predominantly male, predominantly female, or neutral.

If you know that the majority of inputted names will be predominantly one gender, meaning that gender-neutral names will likely be of a particular gender, use this property to set the gender bias while genderizing names.

Either the ‘Code’ or ‘Name’ listed below can be used to set the action.

For example, Options = GENDERPOPULATION:3 and Options = GENDERPOPULATION:Female are equivalent settings.

Option Name	Parameter Code	Parameter Name	Definition
GenderPopulation	1	Male	Bias toward male.
	2	Mixed	Default. No bias toward either gender.
	3	Female	Bias toward female.

GenderAggression

This option sets how aggressively the service will attempt to genderize neutral first names.

By default, a value of “N” will be assigned when attempting to genderize a first name that can easily be male or female, such as “Taylor,” “Chris,” or “Pat.”

Using this property in conjunction with the GenderPopulation option, you can instruct the service on how much preference to give one gender over the other when assigning a gender to a normally neutral name.

Either the ‘Code’ or ‘Name’ listed below can be used to set the action.

For example, Options = GENDERAGGRESSION:2 and Options = GENDERAGGRESSION:Neutral are equivalent settings.

Option Name	Parameter Code	Parameter Name	Definition
GenderAggression	1	Aggressive	Aggressive name genderizing.
	2	Neutral	Default. Neutral name genderizing.
	3	Conservative	Conservative name genderizing.

The table below shows how the settings for Gender Aggression and Gender Population affect genderizing:

	Male				Female
Aggression	Always [7]	Often [6]	Normally [5]	Neutral [4]	Normally [3]	Often [2]	Always [1]
Conservative
Even	M	N	N	N	N	N	F
Male	M	M	N	N	N	N	F
Females	M	N	N	N	N	F	F
Neutral
Even	M	M	N	N	N	F	F
Male	M	M	M	N	N	F	F
Females	M	M	N	N	F	F	F
Aggressive
Even	M	M	M	N	F	F	F
Male	M	M	M	M	N	F	F
Females	M	M	N	F	F	F	F

MiddleNameLogic

This option controls how middle names are handled.

Some names can be ambiguous with regards to the middle word of a full name. It may be a middle name or it may be the first part of a hyphenated last name, but the hyphen has been omitted for some reason.

Normally, the service assumes that, in the absence of a hyphen, recognizable last names in the middle of a full name are treated as part of a hyphenated last name. “Mary O’Malley Kelly” is parsed into first name “Mary” and last name “O’Malley-Kelly.”

On the other hand, “Colleen Marie Sullivan” is parsed into first name “Colleen,” middle name “Marie,” and last name “Sullivan.”

Either the ‘Code’ or ‘Name’ listed below can be used to set the action.

For example, Options = MIDDLENAMELOGIC:0 and Options = MIDDLENAMELOGIC:ParseLogic are equivalent settings.

Option Name	Parameter Code	Parameter Name	Definition
MiddleNameLogic	0	ParseLogic	Default. The service behaves as described above.
	1	HyphenatedLast	The middle word is assumed to be part of the last name. “Matthew Edward Jones” is treated as “Matthew Edward-Jones.”
	2	MiddleName	The middle word is assumed to be a middle name. for the name “Mary O’Malley Kelly,” O’Malley is assumed to be the middle name.

When a hyphen is present, the hyphenated word is always treated as the last name, regardless of content.

Email Options

Optional.

This is a string value containing the email options set by the user when the email is being validated during the Check action.

Protocol	Syntax
JSON	"EmailOptions":"string"
REST	&emailOpt = string

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

Syntax
OptionName:Parameter,OptionName:Parameter

VerifyMailBox

VerifyMailBox validates email mailbox.

Option Name	Parameter	Description
VerifyMailBox	Express	Default. Also known as fast mode. Quickly validates against database of known email addresses.
	Premium	Also known as real time mode. Perform real time, live validation of email addresses.

DomainCorrection

DomainCorrection turns on fuzzy correction on suspected email domains typos.

Option Name	Parameter	Description
DomainCorrection	On	Default. Activates fuzzy email domain correction if the domain is a suspected typo.
	Off	No email domain correction.

TimeToWait

TimeToWait allows you to select how long (in seconds) that you would like our web service to wait on a single email before it times out. Select a smaller number if time is of essence, or longer if you would prefer more accurate results.

Option Name	Parameter	Description
TimeToWait	# [5 - 45]	Default set to 25. Select how long the web service will wait before it times out on an email.

Phone Options

Optional.

This is a string value containing the phone options set by the user when the phone is being validated during the Check action.

Protocol	Syntax
JSON	"PhoneOptions":"string"
REST	&phoneOpt = string

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

Syntax
OptionName:Parameter,OptionName:Parameter

CallerID

Returns the name or association linked to the phone number at the time of registration, if available.

Option Name	Parameter	Description
CallerID	False	Default. CallerID is turned off.
	True	Adds the CallerID to the queried phone, if we found it to be valid.

DefaultCallingCode

DefaultCallingCode is used when the country could not be detected from the phone number or country input.

A calling code is a sequence of digits often found after the leading ‘+’ and is unique to a country/region.

By default, this value is blank. For more information on country calling codes, please see: https://en.wikipedia.org/wiki/List_of_country_calling_codes.

Option Name	Parameter
DefaultCallingCode	Country Calling Code

TimeToWait

Determines how long the service takes to query a phone number for Premium or CallerID, before it decides to time out.

Time to wait in seconds. Minimum value is 1, maximum value is 30.

Option Name	Parameter	Description
TimeToWait	(Time in seconds)	Default is 2. Time to wait in seconds.

VerifyPhone

VerifyPhone sets the level of verification to be done on a phone check.

Option Name	Parameter	Description
VerifyPhone	Express	Default. Quickly validates against a database of known phone numbers.
	Premium	Validates against a database of known phone numbers. If a number was last real-time validated more than 30 days ago, then a real-time check will be performed.

Options

Optional.

This is a string value containing other mscellaneous options related to the web service.

Protocol	Syntax
JSON	"Options":"string"
REST	&opt = string

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

Syntax
OptionName:Parameter,OptionName:Parameter

Consent

Option for data sources that require consent to be given – acknowledging that consent is given to allow the data to be verified by external data sources.

Option Name	Parameter	Description
Consent	No	Default. Indicates that no consent was given.
	Yes	Indicates that consent was given.

Privacy

Optional.

This Option allows data elements to be redacted from the response. User can submit any combination of data elements to redact, or all elements. All result codes will be returned to the client will be returned to the user.

Protocol	Syntax
JSON	"Privacy":"string"
REST	&privacy = string

List data elements to redact in the following format, with multiple elements delimited with a ",".

Syntax
Privacy:value1,value2,value3

Privacy

Option Name	Parameter	Description
Privacy	[None]	Default. All data elements will be returned
	name	Redact name fields.
	address	Redact address fields.
	phone	Redact phone fields.
	email	Redact email fields.
	all	Redact all fields.

National ID

Optional.

A string containing the national ID specific to the country. (e.g. in the US the Social Security Number)

Protocol	Syntax
JSON	"NationalID":"string"
REST	&nat = string

First Name

Recommended.

The given (first) name.

Protocol	Syntax
JSON	"FirstName":"string"
REST	&first = string

Last Name

Recommended.

The family (last name) or surname.

Protocol	Syntax
JSON	"LastName":"string"
REST	&last = string

Full Name

Recommended.

The full name to be genderized, standardized, and parsed.

We will parse and check full names only if the first name and last name fields are left blank.

Protocol	Syntax
JSON	"FullName":"string"
REST	&full = string

Company

Optional.

The company/organization name to be standardized.

Protocol	Syntax
JSON	"Company":"string"
REST	&comp = string

Phone Number

Optional.

The phone number to be verified.

Protocol	Syntax
JSON	"PhoneNumber":"string"
REST	&phone = string

Email

Optional.

The email address to be verified.

Protocol	Syntax
JSON	"Email":"string"
REST	&email = string

Date of Birth

Optional.

The date of birth to be verified. The expected input format is YYYYMMDD.

Protocol	Syntax
JSON	"DateOfBirth":"string"
REST	&dob = string

Account Number

Optional.

The input field for account number. This should contain an IBAN or SWIFT number.

Protocol	Syntax
JSON	"AccountNumber":"string"
REST	&accountNumber = string

Address Line 1

Required.

The input field for the address. This should contain the delivery address information (house number, thoroughfare, building, suite, etc.) but should not contain locality information (locality, administrative area, postal code, etc.) which have their own inputs.

Protocol	Syntax
JSON	"AddressLine1":"string"
REST	&a1 = string

Address Line 2

Required.

The input field for the address. This should contain the delivery address information (house number, thoroughfare, building, suite, etc.) but should not contain locality information (locality, administrative area, postal code, etc.) which have their own inputs.

Protocol	Syntax
JSON	"AddressLine2":"string"
REST	&a2 = string

Address Line 3

Required.

The input field for the address. This should contain the delivery address information (house number, thoroughfare, building, suite, etc.) but should not contain locality information (locality, administrative area, postal code, etc.) which have their own inputs.

Protocol	Syntax
JSON	"AddressLine3":"string"
REST	&a3 = string

Address Line 4

Required.

The input field for the address. This should contain the delivery address information (house number, thoroughfare, building, suite, etc.) but should not contain locality information (locality, administrative area, postal code, etc.) which have their own inputs.

Protocol	Syntax
JSON	"AddressLine4":"string"
REST	&a4 = string

Address Line 5

Required.

The input field for the address. This should contain the delivery address information (house number, thoroughfare, building, suite, etc.) but should not contain locality information (locality, administrative area, postal code, etc.) which have their own inputs.

Protocol	Syntax
JSON	"AddressLine5":"string"
REST	&a5 = string

Address Line 6

Required.

The input field for the address. This should contain the delivery address information (house number, thoroughfare, building, suite, etc.) but should not contain locality information (locality, administrative area, postal code, etc.) which have their own inputs.

Protocol	Syntax
JSON	"AddressLine6":"string"
REST	&a6 = string

Address Line 7

Required.

The input field for the address. This should contain the delivery address information (house number, thoroughfare, building, suite, etc.) but should not contain locality information (locality, administrative area, postal code, etc.) which have their own inputs.

Protocol	Syntax
JSON	"AddressLine7":"string"
REST	&a7 = string

Address Line 8

Required.

The input field for the address. This should contain the delivery address information (house number, thoroughfare, building, suite, etc.) but should not contain locality information (locality, administrative area, postal code, etc.) which have their own inputs.

Protocol	Syntax
JSON	"AddressLine8":"string"
REST	&a8 = string

Locality

Required.

The most common population center data element.

US Term: City

Canada Term: Municipality

Protocol	Syntax
JSON	"Locality":"string"
REST	&loc = string

Administrative Area

Required.

The most common geographic data element.

US Term: State

Canada Term: Province

Protocol	Syntax
JSON	"AdministrativeArea":"string"
REST	&admarea = string

PostalCode

Required.

The complete postal code for a particular delivery point.

If all three elements are provided and the PostalCode is incorrect, it can be corrected from the data on the Locality and AdministrativeArea.

Protocol	Syntax
JSON	"PostalCode":"string"
REST	&postal = string

Country

Required.

The country name, abbreviation, or code.

Protocol	Syntax
JSON	"Country":"string"
REST	&ctry = string

Country of Origin

Optional.

This is used to determine whether or not to include the country name as the last line in the FormattedAddress field.

Protocol	Syntax
JSON	"CountryOfOrigin":"string"
REST	&ctryOrg = string