Personator Identity:Request

From Melissa Data Wiki
Revision as of 22:49, 15 April 2024 by Admin (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

← Personator Identity

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