Personator Identity:Request: Difference between revisions

Latest revision as of 22:49, 15 April 2024

Personator Identity Navigation

Introduction
Licensing

Input/Output
Request Fields
Response Fields

Examples
REST JSON
POST JSON

Result Codes
Result Code Use
Personator Identity 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
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.
DeliveryLines	`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.
CorrectFirstName	`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:

Conservative
	Male				Female
Aggression	Always [7]	Often [6]	Normally [5]	Neutral [4]	Normally [3]	Often [2]	Always [1]
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.
VerifyMailBox	`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.
DomainCorrection	`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.
CallerID	`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.
VerifyPhone	`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.
Consent	`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`