Quickstart Guide

Personator Identity

Personator Identity can be used to:

  • Verify, Correct, & Standardize names, addresses, emails and phones in real time.
  • Verify Individuals in real time using the follow matching options:
    • Proof of Address
      • Name and Address Match only
    • Identity Verification (eIDV)
      • Name, Address, Date of Birth, National ID, Phones, and Emails.
    • 2x2 Match (AML)
      • Match against two sources using eIDV configurations for both sources.
  • Screen Individuals against National Watchlists
    • Politically Exposed Persons (PEP)
    • Government Sanctions
    • Anti-Terrorism
    • Anti-Money Laundering
    • Government Agency Lists
  • Append latitude & longitude
  • Return address as parsed components
  • Return address in mailing label format according to the standards of each country
  • Append additional information like unique identifier, delivery indicator, & more depending on the country.
Last Updated 05/04/2020

Real Time

  • Put the contact data into JSON, XML, or REST format.
  • Make sure to include your license key.
  • Specify the actions to the level of verification required
    • Check: Cleanse, Validate and format the contact data.
    • Verify: Identity Verification on the individual
    • Screen: Search Individual against Watchlists.
  • Send the request to the service URL: https://globalpersonator.melissadata.net/v1/doContactVerify using HTTP GET.
  • Receive the result back from the service.
Last Updated 05/04/2020

NOTE: This service can deal with multiple languages and scripts. It expects UTF-8 encoding. Be on the lookout for question marks (?), squares (▖) or other weird characters like �. They may be an indication of encoding issues and can result in data loss. Bad encoding or character loss is not something our service can correct for you.

Real Time

With a REST request, you can include all the input along with the URL for an easy and quick way of sending a single record.

curl -X GET "https://globalpersonator.melissadata.net/v1/doContactVerify?act=Check,Verify&addrOpt=&emailOpt=&phoneOpt=&nameOpt=NameHint:DefinitelyFull&id=LICENSE_KEY&full=&fname=John&lname=Smith&nat=123456789&a1=22382%20Avenida%20Empresa&a2=&a3=&loc=Rancho%20Santa%20Margarita&admarea=CA&postal=92688&ctry=US&phone=123-456-7890&email=testingemail@melissa.com"

You will have to replace the fields surrounded by “< >” to generate a result (see example above).

You can also put the URL without the “curl -X GET” command directly into your browser. This service will only return a JSON result. You can also use JSON POST to send requests.

JSON POST

Header

Make sure the header includes this line.

Accept: application/json

Body

{
  "TransmissionReference":"Test",
  "CustomerID":"LICENSE_KEY"
  "Actions":"Check,Verify",
  "AddressOptions":"",
  "EmailOptions":"",
  "PhoneOptions":"",
  "NameOptions":"NameHint:DefinitelyFull",
  "Options":"",
  "NationalID":"123456789",
  "FirstName":"John",
  "LastName":"Smith",
  "FullName":"",
  "Company":"",
  "PhoneNumber":"123-456-7890",
  "Email":"testingemail@melissa.com",
  "DateOfBirth":"01/01/1965",
  "AddressLine1":"22382 Avenida Empresa",
  "AddressLine2":"",
  "AddressLine3":"",
  "AddressLine4":"",
  "AddressLine5":"",
  "AddressLine6":"",
  "AddressLine7":"",
  "AddressLine8":"",
  "Locality":"Rancho Santa Margarita",
  "AdministrativeArea":"CA",
  "PostalCode":"92688",
  "Country":"US",
  "CountryOfOrigin":""
}
Last Updated 05/04/2020
JSON Input REST Input Description REQUIRED
TransmissionReference t Value passed through unchanged to the response for identification or any other purpose No
CustomerID id The License Key issued by Melissa Yes
Options opt Delivery Lines
Code Description
On Only Put Delivery Address into the address lines and move all area information into their parsed fields.
Off (Default) Put the full address into the Address lines.
OutputScript
Code Description
NOCHANGE Leave the output in the same script as the input.
Actions act
Code Description
Check Cleanse, Validate, and Format the contact data.
Verify Identify the individual against sources.
Screen Screen Individuals against National Watchlists
Yes
AddressOptions addrOpt DeliveryLines
Code Description
On Only Put Delivery Address into the address lines and move all area information into their parsed fields.
Off (Default) Put the full address into the Address lines.
OutputScript
Code Description
NOCHANGE Leave the output in the same script as the input.
LATN Return output in Latin Script.
NATIVE Return output in the script of the native language of the country.
No
NameOptions nameOpt CorrectFirstName
Code Description
On Allows first name misspelling corrections.
Off Default. Preserve first name spellings; no correction allowed.
NameHint
Code Description
DefinitelyFull Name will always be treated as normal name order regardless of formatting or punctuation.
VeryLikelyFull Name will be treated as normal name order unless inverse order is clearly indicated by formatting or punctuation.
ProbablyFull If necessary, statistical logic will be employed to determine name order, with a bias towards normal name order.
Varying Default. If necessary, statistical logic will be employed to determine name order, with no bias toward either name order.
ProbablyInverse If necessary, statistical logic will be employed to determine name order, with a bias toward inverse name order.
VeryLikelyInverse Name will be treated as inverse name order unless normal order is clearly indicated by formatting or punctuation.
DefinitelyInverse Name will always be treated as inverse name order, regardless of formatting or punctuation.
MixedFirstName Name element is expected to only contain first names.
MixedLastName Name element is expected to only contain last names.
GenderPopulation
Code Description
Male Bias toward male.
Mixed Default. No bias toward either gender.
Female Bias toward female.
GenderAggression
Code Description
Aggressive Aggressive name genderizing.
Neutral Default. Neutral name genderizing.
Conservative Conservative name genderizing.
MiddleNameLogic
Code Description
ParseLogic Default. The service behaves as described above.
HyphenatedLast The middle word is assumed to be part of the last name. “Matthew Edward Jones” is treated as “Matthew Edward-Jones.”
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.
No
EmailOptions emailOpt VerifyMailbox
Code Description
Express Default. Quickly validates against database of known email addresses.
Premium A real time check is performed to determine email deliverability.
Domain Correction
Code Description
On Default. Activates fuzzy email domain correction if the domain is a suspected typo.
Off No email domain correction.
TimeToWait
Code Description
# [5-45] Default set to 25. Select how long the web service will wait before it times out on an email.
No
PhoneOptions phoneOpt Caller ID
Code Description
FALSE Default. CallerID is turned off.
TRUE Adds the CallerID to the queried phone, if we found it to be valid.
DefaultCallingCode
Code Description
[##] Country Calling Code
TimeToWait
Code Description
# [5-45] Default set to 25. Select how long the web service will wait before it times out on an email.
VerifyPhone
Code Description
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.
No
Options opt Consent
Code Description
No Default. Indicates that no consent was given.
Yes Indicates that consent was given.
No
NationalID nat A string containing the national ID specific to the country. (e.g. in the US the Social Security Number) No
FirstName first The given (first) name. Yes
LastName last The family (last name) or surname. Yes
FullName full The full name to be genderized, standardized, and parsed. Yes
Company comp The company/organization name to be standardized. No
PhoneNumber phone The phone number to be verified. No
Email email The email address to be verified. No
DateOfBirth dob The date of birth to be verified. The expected input format is YYYYMMDD. No
AddressLine1 a1 The Input Address Line 1 Yes
AddressLine2 a2 The Input Address Line 2 No
AddressLine3 a3 The Input Address Line 3 No
AddressLine4 a4 The Input Address Line 4 No
AddressLine5 a5 The Input Address Line 5 No
AddressLine6 a6 The Input Address Line 6 No
AddressLine7 a7 The Input Address Line 7 No
AddressLine8 a8 The Input Address Line 8 No
Locality loc The Input Locality (Also called City, Canton, etc. The most common area name for almost all countries) No
AdministrativeArea admarea The Input Administrative Area (Also common called State, Municipality, etc. Common in larger countries) No
PostalCode postal The Input Postal Code No
Country ctry The Country ISO2, ISO3, or spelled out name Yes
CountryOfOrigin ctryorg The country from where the verification is being done.  No
Last Updated 05/07/2020

Generally, the more information you can provide for an individual, the more data sources can be used to better verify & match an individual.

If you have the necessary information to send through Personator Identity for ID verification, you will need to form a simple REST request that passes in that information to the web service.

Note, when you want to verify the identity of an individual, make sure that you have “Verify” set in the Actions parameter.

Different countries will have different capabilities on what fields can be matched.

Last Updated 05/05/2020

Real Time

Here is a sample response of the real-time request and JSON POST from above.

{
  "Name": {
    "Results": "",
    "Company": "",
    "NamePrefix": "",
    "NameFirst": "",
    "NameMiddle": "",
    "NameLast": "",
    "NameSuffix": "",
    "Gender": "",
    "NamePrefix2": "",
    "NameFirst2": "",
    "NameMiddle2": "",
    "NameLast2": "",
    "NameSuffix2": "",
    "Gender2": ""
  },
  "Address": {
    "Results": "AC16,AV24,GS05",
    "FormattedAddress": "22382 Avenida Empresa;Rancho Santa Margarita, CA 92688-2112",
    "Organization": "",
    "AddressLine1": "22382 Avenida Empresa",
    "AddressLine2": "Rancho Santa Margarita, CA 92688-2112",
    "AddressLine3": "",
    "AddressLine4": "",
    "AddressLine5": "",
    "AddressLine6": "",
    "AddressLine7": "",
    "AddressLine8": "",
    "SubPremises": "",
    "DoubleDependentLocality": "",
    "DependentLocality": "",
    "Locality": "Rancho Santa Margarita",
    "SubAdministrativeArea": "Orange",
    "AdministrativeArea": "CA",
    "PostalCode": "92688-2112",
    "AddressType": "S",
    "AddressKey": "92688211282",
    "SubNationalArea": "",
    "CountryName": "United States of America",
    "CountryCode": "US",
    "CountryISO3": "USA",
    "CountryNumber": "840",
    "CountrySubdivisionCode": "US-CA",
    "Thoroughfare": "Avenida Empresa",
    "ThoroughfarePreDirection": "",
    "ThoroughfareLeadingType": "",
    "ThoroughfareName": "Avenida Empresa",
    "ThoroughfareTrailingType": "",
    "ThoroughfarePostDirection": "",
    "DependentThoroughfare": "",
    "DependentThoroughfarePreDirection": "",
    "DependentThoroughfareLeadingType": "",
    "DependentThoroughfareName": "",
    "DependentThoroughfareTrailingType": "",
    "DependentThoroughfarePostDirection": "",
    "Building": "",
    "PremisesType": "",
    "PremisesNumber": "22382",
    "SubPremisesType": "",
    "SubPremisesNumber": "",
    "PostBox": "",
    "Latitude": "33.637572",
    "Longitude": "-117.606868"
  },
  "Email": {
    "Results": "ES01,ES07,ES21",
    "EmailAddress": "testingemail@melissa.com",
    "MailboxName": "testingemail",
    "DomainName": "melissa",
    "TopLevelDomain": "com",
    "TopLevelDomainName": "Commercial",
    "DateChecked": "11/18/2019 8:34:04 PM"
  },
  "Phone": {
    "Results": "PE01",
    "Carrier": "",
    "CallerID": "",
    "InternationalPhoneNumber": "",
    "PhoneNumber": "123-456-7890",
    "PhoneInternationalPrefix": "",
    "PhoneNationPrefix": "",
    "PhoneCountryDialingCode": "",
    "PhoneNationalDestinationCode": "",
    "PhoneSubscriberNumber": "",
    "Locality": "",
    "AdministrativeArea": "",
    "CountryName": "",
    "CountryAbbreviation": "US",
    "DST": "",
    "UTC": "",
    "Language": "",
    "Latitude": "",
    "Longitude": "",
    "TimeZoneCode": "",
    "TimeZoneName": ""
  },
  "Identity": {
    "Results": "KV02,KV03,KV31,KV04,KV01,KV10,KV11,KV12,KV13,KV14",
    "Confidence": "High",
    "Datasources": [
      {
        "DatasourceName": "Credit-1A",
        "Results": "KV02,KV03,KV31,KV04,KV01,KV10,KV11,KV12,KV13,KV14",
        "Messages": [
          {
            "ResultCode": "KV02",
            "Description": "National ID matched"
          },
          {
            "ResultCode": "KV03",
            "Description": "First/given/forename matched"
          },
          {
            "ResultCode": "KV31",
            "Description": "Full match was made on First Initial"
          },
          {
            "ResultCode": "KV04",
            "Description": "Last/surname name matched"
          },
          {
            "ResultCode": "KV01",
            "Description": "Address matched"
          },
          {
            "ResultCode": "KV10",
            "Description": "Postal code matched"
          },
          {
            "ResultCode": "KV11",
            "Description": "Administrative area matched"
          },
          {
            "ResultCode": "KV12",
            "Description": "Locality matched"
          },
          {
            "ResultCode": "KV13",
            "Description": "Thoroughfare matched"
          },
          {
            "ResultCode": "KV14",
            "Description": "Premise/house number matched"
          }
        ]
      }
    ],
    "Watchlists": {
      "Hit": "",
      "Sources": null
    },
    "WatchlistPersons": "",
    "NationalID": "123456789",
    "DateOfBirth": ""
  },
  "TransactionID": "eaf2717a4075b4d38094a69bb02d13ea",
  "TransmissionReference": "",
  "Results": "",
  "Version": "1.0.83"
}
Last Updated 05/05/2020

Response (Base Level)

Output Name Description
TransactionID This is a string value that serves as a unique identifier for this record. A unique transaction ID is generated for every record handled by Personator Identity .
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.
Results This is a string value that lists error codes from any errors caused by the most recent request as a whole.
Version This is a string value that is the current revision number of Personator Identity web service.
Results This is a string value that lists the ID verification codes (KV*).

Identity

Output Name Description
Confidence
Value Description
High Passing or high quality score
Medium Possible pass with multiple matching elements
Low None or minimal match rate
Datasources Contains an array of data sources where a match is found against the input. This field is only available when the Verify action is specified. Otherwise a null value is returned.
Watchlists
Value Description
Hit Returns a boolean string containing either true or false.
Sources Returns an array of the names of watchlists the individual was found on.
WatchlistPersons A string value listing the potential names that were found matched on a watchlist.
NationalID A string value containing the input national ID returned as is.
DateOfBirth A string value containing the input date of birth returned as is.

Name

Output Name Description
Results This is a string value with comma delimited status, error codes, and change codes for the record.
Company This is a string value of the standardized company name.
NamePrefix This is a string value of the first prefix (such as “Mr.” or “Dr.”) from an inputted full name.
NameFirst This is a string value of the first name from an inputted full name.
NameMiddle This is a string value of the middle name from an inputted full name.
NameLast This is a string value of the last name from an inputted full name.
NameSuffix This is a string value of the first suffix (such as “Jr.” or “III”) from an inputted full name.
Gender This is a one-character string value indicating the gender of the first name from the input.
NamePrefix2 This is a string value of the second prefix (such as “Mr.” or “Dr.”) from an inputted full name.
NameFirst2 This is a string value of the second first name from an inputted full name.
NameMiddle2 This is a string value of the second middle name from an inputted full name.
NameLast2 This is a string value of the second last name from an inputted full name.
NameSuffix2 This is a string value of the second suffix (such as “Jr.” or “III”) from an inputted full name.
Gender2 This is a one-character string value indicating the gender of the inputted full name.

Address

Output Name Description
Results This is a string value with comma delimited status, error codes, and change codes for the record.
FormattedAddress This is the Mailing Label version of the address with all pieces included in the format for the country.
Organization The organization tied to the address. Will use the input organization if one if one from the database is not available for override.
AddressLine1 The first line of the address in database format.
AddressLine2 The second line of the address in database format.
AddressLine3 The third line of the address in database format.
AddressLine4 The fourth line of the address in database format.
AddressLine5 The fifth line of the address in database format.
AddressLine6 The sixth line of the address in database format.
AddressLine7 The seventh line of the address in database format.
AddressLine8 The eighth line of the address in database format.
DoubleDependentLocality Double Dependent Locality is the area smaller than a dependent locality but bigger than a thoroughfare. Very rarely used.
SubAdministrativeArea The area smaller than an Administrative Area but bigger than a city (like a county). Often used in larger countries but rarely included as part of an official address.
AdministrativeArea The common administrative division larger than locality, also called State, Municipality
PostalCode The postal code
AddressType The type of the address. Currently only available for the US.
AddressKey A identification value for the US making up the postal code, Plus4, and delivery point.
SubNationalArea The area larger than administrative area but smaller than the nation. Rarely used.
CountryName The official ISO 3166 2 character code of the country
CountryCode The official ISO 3166 3 character code of the country
CountryISO3 The official ISO 3166 number of the country
CountrySubdivisionCode The ISO 3166-2 Subdivisioncode value for the address
Thoroughfare The full named street that correspond to the address. This value includes the Pre Direction, Leading Type, Name, Trailing Type, and Post Direction.
ThoroughfarePreDirection The directional that preceeds the thoroughfare name. Ex: North
ThoroughfareLeadingType The street type of the thoroughfare that preceeds the thoroughfare name. EX: Rue de
ThoroughfareName The main name of the thoroughfare. Ex: Main
ThoroughfareTrailingType The street type of the thoroughfare that comes after the thoroughfare name. EX: Blvd
ThoroughfarePostDirection The directional that comes after the thoroughfare name. Ex: South
DependentThoroughfare A second (usually smaller) thoroughfare value attached to the address if necessary.
DependentThoroughfarePreDirection The predirection of the dependent thoroughfare
DependentThoroughfareLeadingType The leading type of the dependent thoroughfare
DependentThoroughfareName The name of the dependent thoroughfare
DependentThoroughfareTrailingType The trailing type of the dependent thoroughfare
DependentThoroughfarePostDirection The post direction of the dependent thoroughfare
Building The name of the building attached to the address.
PremisesType The house number type of the address. Ex: No. (Rarely used)
PremisesNumber The house number value of the address
SubPremisesType The type value of the SubPremises. Ex: Suite
SubPremisesNumber The number value of the SubPremises. Ex: 10A
PostBox The post office box value if it exists
Latitude The Latitude of the output address
Longitude The Longitude of the output address

Email

Output Name Description
Results This is a string value with comma delimited status, error codes, and change codes for the record.
EmailAddress This is a string value listing the email address, including any corrections or changes made by Global Email.
MailboxName This is a string value listing the mailbox or user name portion of the email address (All characters preceding the "@" character).
DomainName This is a string value listing the domain name portion of the email address (All characters between the "@" and "." characters).
TopLevelDomain This is a string value listing the description associated with the top-level domain name of the email address.
TopLevelDomainName This is a string value listing the top level domain name portion of the email address (All characters after the ".").
DateChecked This is a string value listing the date the email was last checked. DateChecked field returns a UTC, Unix Time (Epoch Time).

Phone

Output Name Description
Results This is a string value with comma delimited status, error codes, and change codes for the record.
Carrier This is a string that returns the name of the phone’s carrier.
CallerID This is the result from our CallerID service, which it appends the name to the targeted phone number.
InternationalPhoneNumber This is the number you would dial, given your output fields, in order to successfully send a call.
PhoneNumber This is a string value of the standardized phone number after a successful call to the service.
PhoneInternationalPrefix This is a string value that returns the international exit code needed to call a number outside of the dialing country.
PhoneNationPrefix This is a string that returns a digit, or combination of digits, known as the national prefix.
PhoneCountryDialingCode This is a string that returns a digit, or combination of digits, known as the country dialing code.
PhoneNationalDestinationCode This is a string that returns a digit, or combination of digits, known as the national destination code.
PhoneSubscriberNumber This is string that returns the subscriber number associated with the phone number passed in.
Locality This is a string that returns the locality (city) associated with the phone number passed to the Lookup function.
Administrative area This is a string that returns the administrative area associated with the inputted phone number.
Country name This is a string that returns the name of the country for the inputted phone number.
Country abbreviation This is a string that returns the abbreviation of the country for the inputted phone number.
DST This is a string that returns a ‘Y’ (for yes) or ‘N’ (for no) to distinguish whether the region of the inputted phone number observes daylight savings time.
UTC This is a string that returns the universal time code for the time zone associated with the inputted phone number.
Language This is a string that returns the predominant language of the phone’s detected geographical location.
Latitude This is a string that returns the latitude of the geographically identifiable service area of the exchange.
Longitude This is a string that returns the longitude of the geographically identifiable service area of the exchange.
Last Updated 05/08/2020

Personator Identity also returns a string of KV* result codes which provides the details on what fields got matched.

Code Description
KV01 Address matched
KV10 Postal code matched
KV11 Administrative area (state/province) matched
KV12 Locality matched
KV13 Thoroughfare/street matched
KV14 Premise/house number matched
KV15 Subpremise matched
KV02 National ID matched
KV03 First/given/forename matched
KV31 First Initial Matched
KV04 Last/surname matched
KV05 Phone number matched
KV50 Last 4 digits of phone matched
KV06 Email matched
KV07 Date of birth matched
KV70 Day of birth matched
KV71 Month of birth matched
KV72 Year of birth matched
KV08 Organization matched

In nearly all situations, a match on the name is necessary before any other consideration:

  • KV03 – match on first name/forename
  • KV04 – match on last name/surname

In addition to matching on the name, an additional match on at least another element is necessary as well. Some common ones:

  • KV01 – match on address
  • KV02 – match on national ID
  • KV07 – match on date of birth

In the JSON example provided above, we can see KV03 and KV04, which means we found a match on the name. Then additionally we can see the KV01 result code is also returned, meaning that the address was matched. Since both the name & address matched, this can be considered a good individual to on-board.

Confidence Scoring

In the JSON example provided above, Confidence returned a High score. As an alternative to the KV* result codes, the Confidence field provides a quick way to see if an individual has been verified or not. Confidence can be one of the following:

  • High – the individual matched with a high level of confidence and can be safely on-boarded
  • Medium – the individual matched with a medium level of confidence, meaning that while a decent amount of the provided information had been verified, further due diligence may be required before the individual can be on-boarded
  • Low – the individual matched with a low level of confidence and therefore should not be on-boarded

Data Sources

In the JSON example above, a match was found on a postal data source. We can see from the "Datasources" field that an array of data sources is returned along with individual result codes & messages indicating how the individual matched on the particular data sources. From the result codes & messages in this example, we can see that this individual's name (both first & last) along with their address (house, street, city, postal code) matched against this postal data source. Personator Identity leverages multiple types of data sources including the following:

  • Postal
  • Government
  • Credit
  • Property
  • Consumer
  • Utility
  • Telco

To meet compliance and regulations, there may be a need to verify an individual on multiple data sources (such as for AML). For example, there may be a requirement that an individual has their name (KV03 [first name] + KV04 [last name]) and DOB (KV07 [date of birth]) match on one data source and then name and address match (KV01 [address match]) on another. For situations like this, the "Datasources" field will list out all data sources matches were found on and the respective fields that matched.

Last Updated 05/06/2020