Reference Guide

Introduction

Welcome to Melissa Data’s Personator Identity web service. This new ID verification solution makes it easy to check and verify your data in real time. Using trusted reference and national databases, the service can verify a person’s name, address, phone, email, date of birth and national ID. As a cloud web service, it can be integrated into applications and services that need to maintain trust in their data as well as detect and prevent fraud globally such as in shopping/eCommerce platforms or other applications involving financial transactions.

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

• Identify and verify businesses for any current and future B2B relationships.

  • Verify against government sources in multiple countries

  • Verify Company Name, Address, Business ID

  • Enrich Business information for select countries

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

Base URL

https://globalpersonator.melissadata.net

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 by Requesting a Demo or by calling 800-MELISSA ext. 3 (800-635-4772 ext. 3). Without a license key, Personator Identity will not function.

To set the license key, use the id/CustomerID property in your requests.

Endpoints

/v1/doContactVerify

The Personator Identity doContactVerify endpoint does all the contact verification you need by choosing the actions and options you need.

Try It Now

Note

Make sure to replace {{customerId}} with your license key.

Get it here!

• GET JSON
• POST JSON

curl -X GET "https://globalpersonator.melissadata.net/v1/doContactVerify?\
&t=Test\
&id={{customerId}}\
&act=check\
&comp=Melissa\
&phone=1-800-635-4772\
&email=info@melissa.com\
&a1=22382%20Avenida%20Empresa\
&loc=Rancho%20Santa%20Margarita\
&admarea=CA\
&postal=92688\
&ctry=US" \
-H "Content-Type: application/json" \
-H "Accept: application/json"

curl -X POST "https://globalpersonator.melissadata.net/v1/doContactVerify" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
      "TransmissionReference": "Test",
      "CustomerID": "{{customerId}}",
      "Actions": "check",
      "Company": "Melissa",
      "PhoneNumber": "1-800-635-4772",
      "Email": "info@melissa.com",
      "AddressLine1": "22382 Avenida Empresa",
      "Locality": "Rancho Santa Margarita",
      "AdministrativeArea": "CA",
      "PostalCode": "92688",
      "Country": "US"
    }
   '

Request Parameters

• GET JSON
• POST JSON

Code	Description
Record Level Parameters
act	The actions the service will perform on input data. For every request, a Check action is always performed on the input. 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. 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. 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.
id	Required. The License Key issued by Melissa.
t	Optional. This is a string value that serves as a unique identifier for this set of records. It is returned as sent.
Option Parameters
addrOpt	Set AddressOptions CountryOfOrigin DeliveryLines LineSeparator OutputScript
emailOpt	Set EmailOptions DomainCorrection TimeToWait VerifyMailBox
nameOpt	Set NameOptions CorrectFirstName GenderAggression GenderPopulation MiddleNameLogic NameHint
opt	Set Options Consent
phoneOpt	Set PhoneOptions CallerID DefaultCallingCode TimeToWait VerifyPhone
privacy	Set Privacy Privacy
Record Parameters
a1	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.
a2	Optional. The input field for the address.
a3	Optional. The input field for the address.
a4	Optional. The input field for the address.
a5	Optional. The input field for the address.
a6	Optional. The input field for the address.
a7	Optional. The input field for the address.
a8	Optional. The input field for the address.
accountNumber	Optional. The input field for account number. This should contain an IBAN or SWIFT number.
admarea	Required. State, Province. The most common geographic data element.
comp	Optional. The company/organization name to be standardized.
ctry	Required. The country name, abbreviation, or code.
ctryorg	Optional. This is used to determine whether or not to include the country name as the last line in the FormattedAddress field.
dob	Optional. The date of birth to be verified. The expected input format is YYYYMMDD.
email	Optional. The email address to be verified.
first	Recommended. The given (first) name for the individual.
full	Recommended. The full name to be genderized, standardized, and parsed. This will only be done if the first name and last name fields are left blank.
last	Recommended. The family (last) name or surname for the individual.
loc	Required. City, Municipality. The most common population center data element.
nat	Optional. Social Security Number. The national ID specific to the country.
phone	Optional. The phone number to be verified.
postal	Required. ZIP, Postcode. 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.

Code	Description
Record Level Parameters
Actions	The actions the service will perform on input data. For every request, a Check action is always performed on the input. 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.
CustomerID	Required. The License Key issued by Melissa.
TransmissionReference	Optional. This is a string value that serves as a unique identifier for this set of records. It is returned as sent.
Option Parameters
AddressOptions	Set AddressOptions CountryOfOrigin DeliveryLines LineSeparator OutputScript
EmailOptions	Set EmailOptions DomainCorrection TimeToWait VerifyMailBox
NameOptions	Set NameOptions CorrectFirstName GenderAggression GenderPopulation MiddleNameLogic NameHint
Options	Set Options Consent
PhoneOptions	Set PhoneOptions CallerID DefaultCallingCode TimeToWait VerifyPhone
Privacy	Set Privacy Privacy
Record Parameters
AccountNumber	Optional. The input field for account number. This should contain an IBAN or SWIFT number.
AddressLine1	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.
AddressLine2	Optional. The input field for the address.
AddressLine3	Optional. The input field for the address.
AddressLine4	Optional. The input field for the address.
AddressLine5	Optional. The input field for the address.
AddressLine6	Optional. The input field for the address.
AddressLine7	Optional. The input field for the address.
AddressLine8	Optional. The input field for the address.
AdministrativeArea	Required. State, Province. The most common geographic data element.
Company	Optional. The company/organization name to be standardized.
Country	Required. The country name, abbreviation, or code.
CountryOfOrigin	Optional. This is used to determine whether or not to include the country name as the last line in the FormattedAddress field.
DateOfBirth	Optional. The date of birth to be verified. The expected input format is YYYYMMDD.
Email	Optional. The email address to be verified.
FirstName	Recommended. The given (first) name for the individual.
FullName	Recommended. The full name to be genderized, standardized, and parsed. This will only be done if the first name and last name fields are left blank.
LastName	Recommended. The family (last) name or surname for the individual.
Locality	Required. City, Municipality. The most common population center data element.
NationalID	Optional. Social Security Number. The national ID specific to the country.
PhoneNumber	Optional. The phone number to be verified.
PostalCode	Required. ZIP, Postcode. 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.

AddressOptions

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

OptionName:Parameter,OptionName:Parameter

CountryOfOrigin

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

Parameter

Description

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

DeliveryLines

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

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

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

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

EmailOptions

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

OptionName:Parameter,OptionName:Parameter

DomainCorrection

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

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

VerifyMailBox

Express

The Express option will use cached mailbox validations, so any submitted emails will be checked against a database of known bad and known good emails. Any emails that are sent into the EXPRESS will also be cached so they can be looked up during a 90-day cycle. Use this option for increased cost savings or where speed and performance are of upmost importance.

Premium

The Premium option always does the most comprehensive type of real-time checking by using domain-specific logic as well as SMTP commands and other proprietary mechanisms to validate email boxes. Use the PREMIUM option when you absolutely require the highest level of Mailbox verification. Bear in mind it can sometimes take up to 12 seconds to verify an email box. Applications that are time sensitive in nature should be programmed to call the express mode instead.

Parameter	Description
Express	Default. Quickly validates against database of known email addresses.
Premium	A real time check is performed to determine email deliverability.

NameOptions

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

OptionName:Parameter,OptionName:Parameter

CorrectFirstName

This option enables or disables spelling correction of first names.

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

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

GenderAggression

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

By default, Global Name will assign a value of N 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.

Parameter Code	Parameter Name	Description
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:

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.

Parameter Code	Parameter Name	Description
1	Male	Bias towards Male.
2	Mixed	Default No bias towards either gender.
3	Female	Bias towards Female.

MiddleNameLogic

Deprecated. Middle name logic will be determined by the supplied Country, enabling simultaneous processing of records from different countries.

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.

Parameter Code	Parameter Name	Description
1	ParseLogic	Default The service behaves as described above.
2	HyphenatedLast	The middle word is assumed to be part of the last name. “Matthew Edward Jones” is treated as “Matthew Edward-Jones.”
3	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.

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.

Parameter Code	Parameter Name	Description
1	DefinitelyFull	Name will always be treated as normal name order regardless of formatting or punctuation.
2	ProbablyFull	Deprecated. Will resolve to Varying (Name hint:4). Name will be treated as normal name order unless inverse order is clearly indicated by formatting or punctuation.
3	ProbablyFull	Deprecated. Will resolve to Varying (Name hint:4). 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	Deprecated. Will resolve to Varying (Name hint:4). If necessary, statistical logic will be employed to determine name order, with a bias toward inverse name order.
6	VeryLikelyInverse	Deprecated. Will resolve to Varying (Name hint:4). 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	Obsolete. Will resolve to Varying (Name hint:4). Name element is expected to only contain first names.
9	MixedLastName	Obsolete. Will resolve to Varying (Name hint:4). Name element is expected to only contain last names.

Options

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

OptionName:Parameter,OptionName:Parameter

Consent

This option is 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.

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

PhoneOptions

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

OptionName:Parameter,OptionName:Parameter

CallerID

US and Canada Only.

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

DefaultCallingCode

Tip

For more information on country calling codes, see Wikipedia - Country Calling Codes.

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

Parameter	Description
[Country Calling Code]	Blank by Default. The sequence of digits found after the leading +.

TimeToWait

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

Parameter	Description
[#{1 - 30}]	Default set to 2. Select how long (in seconds) the service will wait before it times out.

VerifyPhone

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

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

Privacy

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

Privacy:value1,value2,value3

Privacy

This Option allows data elements to be redacted from the response. The 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.

Parameter	Description
[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.

Headers

• GET JSON
• POST JSON

Content-Type: application/json
Accept: application/json

Content-Type: application/json
Accept: application/json

Response

• GET JSON
• POST JSON

{
  "Name": {
    "Results": "NE10,NS02",
    "Company": "Melissa",
    "NamePrefix": "",
    "NameFirst": "",
    "NameMiddle": "",
    "NameLast": "",
    "NameSuffix": "",
    "Gender": "U",
    "NamePrefix2": "",
    "NameFirst2": "",
    "NameMiddle2": "",
    "NameLast2": "",
    "NameSuffix2": "",
    "Gender2": ""
  },
  "Address": {
    "Results": "AC16,AV24,GS05",
    "FormattedAddress": "Melissa;22382 Avenida Empresa;Rancho Santa Margarita, CA 92688-2112",
    "Organization": "Melissa",
    "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.637562",
    "Longitude": "-117.606887"
  },
  "Email": {
    "DeliverabilityConfidenceScore": "61",
    "Results": "ES01,ES07,ES21",
    "EmailAddress": "info@melissa.com",
    "MailboxName": "info",
    "DomainName": "melissa",
    "TopLevelDomain": "com",
    "TopLevelDomainName": "Commercial",
    "DateChecked": "10/30/2023 10:28:58 PM",
    "EmailAgeEstimated": "2175",
    "DomainAgeEstimated": "10258",
    "DomainExpirationDate": "2024-09-14T23:00:00",
    "DomainCreatedDate": "1995-09-15T23:00:00",
    "DomainUpdatedDate": "2023-09-15T07:03:42",
    "DomainEmail": "",
    "DomainOrganization": "Domains By Proxy, LLC",
    "DomainAddress1": "DomainsByProxy.com 2155 E Warner Rd",
    "DomainLocality": "Tempe",
    "DomainAdministrativeArea": "Arizona",
    "DomainPostalCode": "85284",
    "DomainCountry": "UNITED STATES",
    "DomainAvailability": "UNAVAILABLE",
    "DomainCountryCode": "US",
    "DomainPrivateProxy": "1",
    "PrivacyFlag": "N",
    "MXServer": "",
    "BreachCount": ""
  },
  "Phone": {
    "Results": "PS01,PS22",
    "Carrier": "(UNKNOWN)",
    "CallerID": "",
    "InternationalPhoneNumber": "+18006354772",
    "PhoneNumber": "8006354772",
    "PhoneInternationalPrefix": "",
    "PhoneNationPrefix": "",
    "PhoneCountryDialingCode": "1",
    "PhoneNationalDestinationCode": "800",
    "PhoneSubscriberNumber": "6354772",
    "Locality": "Toll-free",
    "AdministrativeArea": "",
    "CountryName": "United States",
    "CountryAbbreviation": "US",
    "DST": "",
    "UTC": "",
    "Language": "",
    "Latitude": "",
    "Longitude": "",
    "TimeZoneCode": "EST",
    "TimeZoneName": "Eastern Standard Time"
  },
  "Identity": {
    "Results": "",
    "Confidence": "",
    "Datasources": [],
    "Watchlists": {
      "Hit": "",
      "Sources": [],
      "Articles": [],
      "ReportLink": ""
    },
    "WatchlistPersons": "",
    "NationalID": "",
    "DateOfBirth": "",
    "AccountNumber": {
      "Validated": ""
    },
    "BusinessInformation": {
      "Name": "",
      "ID": "",
      "Status": "",
      "Type": "",
      "RegistrationDate": ""
    }
  },
  "TransactionID": "0322c916-e831-47af-8264-602950dde820",
  "TransmissionReference": "Test",
  "Results": "",
  "Version": "6.2.0.1206"
}

{
  "Name": {
    "Results": "NE10,NS02",
    "Company": "Melissa",
    "NamePrefix": "",
    "NameFirst": "",
    "NameMiddle": "",
    "NameLast": "",
    "NameSuffix": "",
    "Gender": "U",
    "NamePrefix2": "",
    "NameFirst2": "",
    "NameMiddle2": "",
    "NameLast2": "",
    "NameSuffix2": "",
    "Gender2": ""
  },
  "Address": {
    "Results": "AC16,AV24,GS05",
    "FormattedAddress": "Melissa;22382 Avenida Empresa;Rancho Santa Margarita, CA 92688-2112",
    "Organization": "Melissa",
    "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.637562",
    "Longitude": "-117.606887"
  },
  "Email": {
    "DeliverabilityConfidenceScore": "61",
    "Results": "ES01,ES07,ES21",
    "EmailAddress": "info@melissa.com",
    "MailboxName": "info",
    "DomainName": "melissa",
    "TopLevelDomain": "com",
    "TopLevelDomainName": "Commercial",
    "DateChecked": "10/30/2023 10:28:58 PM",
    "EmailAgeEstimated": "2181",
    "DomainAgeEstimated": "10258",
    "DomainExpirationDate": "2024-09-14T23:00:00",
    "DomainCreatedDate": "1995-09-15T23:00:00",
    "DomainUpdatedDate": "2023-09-15T07:03:42",
    "DomainEmail": "",
    "DomainOrganization": "Domains By Proxy, LLC",
    "DomainAddress1": "DomainsByProxy.com 2155 E Warner Rd",
    "DomainLocality": "Tempe",
    "DomainAdministrativeArea": "Arizona",
    "DomainPostalCode": "85284",
    "DomainCountry": "UNITED STATES",
    "DomainAvailability": "UNAVAILABLE",
    "DomainCountryCode": "US",
    "DomainPrivateProxy": "1",
    "PrivacyFlag": "N",
    "MXServer": "",
    "BreachCount": ""
  },
  "Phone": {
    "Results": "PS01,PS22",
    "Carrier": "(UNKNOWN)",
    "CallerID": "",
    "InternationalPhoneNumber": "+18006354772",
    "PhoneNumber": "8006354772",
    "PhoneInternationalPrefix": "",
    "PhoneNationPrefix": "",
    "PhoneCountryDialingCode": "1",
    "PhoneNationalDestinationCode": "800",
    "PhoneSubscriberNumber": "6354772",
    "Locality": "Toll-free",
    "AdministrativeArea": "",
    "CountryName": "United States",
    "CountryAbbreviation": "US",
    "DST": "",
    "UTC": "",
    "Language": "",
    "Latitude": "",
    "Longitude": "",
    "TimeZoneCode": "EST",
    "TimeZoneName": "Eastern Standard Time"
  },
  "Identity": {
    "Results": "",
    "Confidence": "",
    "Datasources": [],
    "Watchlists": {
      "Hit": "",
      "Sources": [],
      "Articles": [],
      "ReportLink": ""
    },
    "WatchlistPersons": "",
    "NationalID": "",
    "DateOfBirth": "",
    "AccountNumber": {
      "Validated": ""
    },
    "BusinessInformation": {
      "Name": "",
      "ID": "",
      "Status": "",
      "Type": "",
      "RegistrationDate": ""
    }
  },
  "TransactionID": "1c2b32c1-b457-41a1-9115-a1c4e6829265",
  "TransmissionReference": "Test",
  "Results": "",
  "Version": "6.2.0.1206"
}

Service Level Response Fields

Output Name	Description
Results	Lists error codes from any errors caused by the most recent request as a whole.
TransactionID	A unique string identifier for this record. A unique transaction ID is generated for every record handled by Personator Identity.
TransmissionReference	Optional. Serves as a unique request identifier.
Version	The current service version number.

Record Level Response Fields

Address

Output Name	Description
AddressLine1	These are the string values that will return the standardized or corrected contents of the input address. These lines will include the entire address including the locality, administrative area, and postal code.
AddressLine2	Standardized or corrected contents of the input address line 2.
AddressLine3	Standardized or corrected contents of the input address line 3.
AddressLine4	Standardized or corrected contents of the input address line 4.
AddressLine5	Standardized or corrected contents of the input address line 5.
AddressLine6	Standardized or corrected contents of the input address line 6.
AddressLine7	Standardized or corrected contents of the input address line 7.
AddressLine8	Standardized or corrected contents of the input address line 8.
AdministrativeArea	State, Province. The standardized contents of the AdministrativeArea element. This is a common geographic area unit for larger countries.
DependentLocality	Urbanization. The standardized contents of the DependentLocality element. A dependent locality is a logical area unit that is smaller than a locality but larger than a double dependent locality or thoroughfare. It can often be associated with a neighborhood or sector. Great Britain is an example of a country that uses double dependent locality. In the United States, this would correspond to Urbanization, which is used only in Puerto Rico.
DoubleDependentLocality	The standardized contents of the DoubleDependentLocality element. A double dependent locality is a logical area unit that is smaller than a dependent locality but bigger than a thoroughfare. This field is very rarely used. Great Britain is an example of a country that uses double dependent locality.
FormattedAddress	The address in the correct format for mailing from the country specified in the CountryOfOrigin element. This includes the Organization as the first line, one or more lines in the origin country’s format, and the destination country (if required).
Locality	City. The standardized contents of the Locality element. This is the most common geographic area and used by virtually all countries. This is usually the value that is written on a mailing label and referred to by terms like City, Town, or Postal Town.
Organization	Business, Company. String value that matches the Organization request element. It is not modified or populated by the service.
PostalCode	ZIP Code. The standardized contents of the PostalCode element. Most countries have some form of a postal code system.
Results	Comma delimited status, error codes, and change codes for the record. For a list of these codes, see the Result Codes list. Separate lines will be delimited by what is specified in the LineSeparator option.
SubAdministrativeArea	County. The standardized contents of the SubAdministrativeArea element. This is a logical area that that is smaller than the administrative area but larger than a locality. While many countries can have a sub-administrative area value, it is very rarely used as part of an official address.
SubPremises	Suite, Apartment. The parsed SubPremises from the AddressLine elements. A subpremise are individual units with their own addresses inside a building.

Appended Address Record Elements

Output Name	Description
AddressKey	This is a country dependent field: US: This returns a 11 digit code representing the combination of the zip code, the plus4, and the delivery point. This is a fairly good representation of a unique US address and often used as the core of postal barcode. However, this code is not guaranteed to be unique to an individual address, please use the MelissaAddressKey instead for that purpose. It is possible that this field is empty or not 11 digits if the address is a Non-USPS address (link to something about non-usps addresses). GB: This field returns the UDPRN, which stands for Unique Delivery Point Reference Number. It is an 8 character code that is assigned and maintained by Royal Mail to each delivery point address. AU: This returns the DPID (Delivery Point ID). This is a 8 digit number that identifies a mailbox according to Australia Post. The AddressKey can be used by other Melissa Data services, such as Geocoder or RBDI.
AddressType	A one-character code for the type of address coded. See the Product Codes for a list of Address Type Codes.
Building	The parsed descriptive name identifying an individual location.
CountryCode	The 2 letter ISO 3166 country code value. For example: US for United States or CA for Canada.
CountryISO3	The 3 letter ISO 3166 country code value. For example: USA for United States or CAN for Canada.
CountryName	The standardized contents of the CountryName element.
CountryNumber	The ISO 3166 country number value. For example: 840 for United States or 124 for Canada.
CountrySubdivisionCode	The ISO3166-2 code for country subdivisions, usually tied to the administrative area for a country. The format is the 2 letter country code followed by a dash followed by 2 or 3 characters or two numbers. For example: US-CA, CN-16, or AU-VIC. This field is only populated for the following countries: AE, AR, AT, AU, BB, BE, BH, BR,BS, CA, CH, CL, CN, CO, CR, DE, DK, DM, DO, ES, FI, FJ, FR, GB, GH, GT, GY, HN, ID, IE, IL, IN, IS, IT, JP, KR, KW, LT, LU, LV, MX, MY, NC, NG, NI, NL, NO, NZ, PE, PH, PK, PL, PR, PT, RS, SA, SG, SI, SV, TH, TR, UA, US, UY, VN.
DependentThoroughfare	Dependent Street. The parsed block data element. The dependent thoroughfare is a second thoroughfare that is required to narrow down the final address. This is rarely used.
DependentThoroughfareLeadingType	The parsed leading thoroughfare type indicator within the DependentThoroughfare field.
DependentThoroughfareName	The parsed name indicator within the DependentThoroughfare field.
DependentThoroughfarePostDirection	The parsed postfix directional indicator within the DependentThoroughfare field.
DependentThoroughfarePreDirection	The parsed prefix directional within the DependentThoroughfare field.
DependentThoroughfareTrailingType	The parsed trailing thoroughfare type indicator within the DependentThoroughfare field.
Latitude	The parsed geographic coordinate for a particular delivery point.
Longitude	The parsed geographic coordinate for a particular delivery point.
PostBox	The parsed post box information for a particular deliveyr point.
PremisesNumber	House Number. The parsed alphanumeric indicator within the premises field.
PremisesType	The parsed leading premise type indicator within the premises field.
SubNationalArea	The standardized arbitrary administrative region below that of the sovereign state. A sub-national area is a logical area unit that is larger than an administrative area but smaller than the country itself. It is extremely rarely used.
SubPremisesNumber	Suite Number. The parsed sub premises number indicator within the premises field.
SubPremisesType	Suite Name. The parsed sub premises type indicator within the premises field.
Thoroughfare	Street. The most common street or block data element. This value is a part of the address lines and contains all the sub-elements of the thoroughfare like trailing type, thoroughfare name, pre direction, post direction, etc.
ThoroughfareLeadingType	The parsed leading thoroughfare type indicator within the Thoroughfare field. A leading type is a thoroughfare type that is placed before the thoroughfare. For example, the thoroughfare type of Rue in Canada and France is placed before the thoroughfare, making it a leading type.
ThoroughfareName	Street Name. The parsed name indicator within the Thoroughfare field.
ThoroughfarePostDirection	Post Direction. The parsed postfix directional within the Thoroughfare field.
ThoroughfarePreDirection	Street PreDirection. The parsed prefix directional within the Thoroughfare field.
ThoroughfareTrailingType	Street Suffix. The parsed trailing thoroughfare type indicator within the Thoroughfare field. A trailing type is a thoroughfare type that is placed after the thoroughfare. For example, the thoroughfare type of Avenue in the US is placed after the thoroughfare, making it a trailing type.

Email

Output Name	Description
Breach Count	The known number of breaches that this email account has been involved in.
DateChecked	The date the email was validated. It returns UTC, Unix Time (Epoch Time) in the MM/DD/YYYY H:MM:SS format.
DeliverabilityConfidenceScore	The probability [0-100]% of an email sent to this mailbox will be successfully delivered.
DomainAddress1	The address of the DomainOrganization.
DomainAdministrativeArea	The state of the DomainOrganization.
DomainAgeEstimated	The estimated age of the domain in days.
DomainAvailability	Check to see if domain is available for purchase.
DomainCountry	The country of the DomainOrganization.
DomainCountryCode	The country code of the DomainCountry.
DomainCreatedDate	The date the domain was created in the YYYY-MM-DDTHH:MM:SS format.
DomainEmail	The email associated with the domain owner.
DomainExpirationDate	The date the domain expires/expired in the YYYY-MM-DDTHH:MM:SS format. This is When the domain will be renewed or available to buy.
DomainLocality	The city of the DomainOrganization.
DomainName	The domain name portion of the email address. (All characters between the “@” and “.” characters.).
DomainOrganization	The company associated with the domain owner.
DomainPostalCode	The postal code of the DomainOrganization.
DomainPrivateProxy	Check if domain is behind a private proxy.
DomainUpdatedDate	The date the domain was last updated in the YYYY-MM-DDTHH:MM:SS format.
EmailAddress	The email address or domain, including any correcctions or updates made by the service.
EmailAgeEstimated	The estimated minimum age of the email in days based on historical data. The value is zero when we lack historical data on a given email.
MailboxName	The mailbox or user name portion of the email address (Everything before the “@” in the email address).
MXServer	Premium only. The Mail Exchange (MX) Server used to validate the email.
PrivacyFlag	Is this email affected by additional privacy reglations, such as GDPR. Returns Y for yes and N for no.
Results	Comma delimited status, error codes, and change codes for the record. See the Result Codes for a full list.
TopLevelDomain	The description associated with the top-level domain name of the email address (e.g. com is Commercial).
TopLevelDomainName	The top level domain name portion of the email address (All characters after the “.”, e.g. com).

Identity

Output Name	Description
AccountNumber	An object that returns one field for account number status. Field Meaning Validated Returns a string containing either Y or N. Example: "AccountNumber": { "Validated":"Y" }
BusinessInformation	An object that returns the following Business Information: Field Meaning Name Name of the business that matched ID Business ID. Uses the official business ID specific to the country: US: EIN SG: Unique Entity Number CA: Corporations Number or Business Number DE: German Trade Register or Handelsregister (HRB) Status The current status of the business. e.g. Active. Type Business Type, e.g. Corporation, Limited Liability Company. Date Registration Date of the business, in the YYYY-MM-DD format.
Confidence	This indicates how reliable the record is after performing ID verification. The 3 possible values returned: Value Meaning High Passing or high quality score Medium Possible pass with multiple matching elements Low None or minimal match rate
DateOfBirth	The input date of birth returned as is.
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. Field Meaning DatasourceName A string value indicating the name/type of data source. Results A string value containing the KV* result codes, indicating how the input matched against this particular data source. Messages An array object, listing the meaning of each KV* result code for this data source. ResultCode The particular KV* result code. Descripton A string value containing the description/meaning of the KV* result code. Example: "Datasources": [ "DatasourceName":"", "Results":"", "Messages": [{ "ResultCode":"", "Description":"" }] ]
NationalID	The input national ID returned as is.
Results	Comma delimited status, error codes, and change codes for the record. See the Result Codes for a full list.
Watchlists	An object with three fields. For a list of used watchlists, see Personator Identity Watchlists. Field Meaning Hit Returns a string containing either Yes or No. Sources Returns an array of the names of watchlists the individual was found on. Name A string value containing the name of the Watchlist source that was matched. Code A two letter string representing the code attributed to the watchlist source. Premium Watchlist matches will always return PR. Type A string value containing the type or category of Watchlist that was matched against. Date A string value containing the date (YYYY-MM-DD) of when the Watchlist source was created. An empty string will be returned if the source does not have this information. Articles Returns the title, link and date of the article. Example: "Watchlists": { "Hit":"Yes", "Sources": [{ "Name":"Specially Designated Nationals OFAC", "Code":"", "Type":"sanction", "Date":"" }, { "Name":"United Kingdom HM Treasury", "Code": "PR", "Type": "sanction", "Date": "2005-12-07" }], "Articles": [{ "Title":"SampleTitleName", "Link":"http://samplereportlink.com", "Date":"2017-09-30T00:00:00Z" }], }
WatchlistsPersons	Blank (Currently reserved for future) – A string value listing the potential names that were found matched on a watchlist.

Name

Output Name	Description
Company	The standardized company name.
Gender	A one-character string value indicating the gender of the first name from the input. For a list of these codes, see the Product Codes list.
Gender2	A one-character string value indicating the gender of the inputted full name. For a list of these codes, see the Product Codes list. If the FullName input property contained multiple names, the gender of the second name will be returned here.
NameFirst	The first name from an inputted full name. If the FullName input property contained a single name, the first name, if any, will be returned here. If two names were passed, the first of the two first names will be returned by this property.
NameFirst2	The second first name from an inputted full name. If the FullName input property contained multiple names, the second first name will be returned here.
NameLast	The last name from an inputted full name. If the FullName input property contained a single name, the last name, if any, will be returned here. If two names were passed, the first of the two last names will be returned by this property.
NameLast2	The second last name from an inputted full name. If the FullName input property contained multiple names, the second last name, if any, will be returned here.
NameMiddle	The middle name from an inputted full name. If the FullName input property contained a single name, the middle name, if any, will be returned here. If two names were passed, the first of the two middle names will be returned by this property.
NameMiddle2	The second middle name from an inputted full name. If the FullName input property contained multiple names, the second middle name, if any, will be returned here.
NamePrefix	The first prefix (such as Mr. or Dr.) from an inputted full name. If the FullName input property contained a single name, the prefix, if any, will be returned here. If two names were passed, the first of the two prefixes will be returned by this property.
NamePrefix2	The second prefix (such as Mr. or Dr.) from an inputted full name. If the FullName input property contained multiple names, the second prefix will be returned here.
NameSuffix	The first suffix (such as Jr. or III) from an inputted full name. If the FullName input property contained a single name, the suffix, if any, will be returned here. If two names were passed, the first of the two suffixes will be returned by this property.
NameSuffix2	The second suffix (such as Jr. or III) from an inputted full name. If the FullName input property contained multiple names, the second suffix, if any, will be returned here.
Results	Comma delimited status, error codes, and change codes for the record. For a list of these codes, see the Result Codes list.

Phone

Output Name	Description
Administrative Area	State. The administrative area (state) associated with the phone number.
Caller ID	The user name associated with the phone number, provided by our Caller ID service.
Carrier	The phone number’s carrier name.
Country Abbreviation	The abbreviation of the country.
Country Dialing Code	The digit(s) required to reach the target country. These are dialed after the international prefix.
Country Name	The country name associated with the phone number.
Daylight Savings Time	Indicates if the phone number region observes daylight savings time. Y for yes or N for no.
International Phone Number	The number you dial to successfully send an international call. This number can change depending on the Country of Origin field.
International Prefix	The international exit code needed to call a number outside of the dialing country. This depends on the Country of Origin and Country input fields.
Language	The predominant language of the phone number’s geographical location.
Latitude	The latitude of the phone number’s service area. Latitude is measured in degrees north or south of the equator.
Locality	The locality (city) associated with the phone number.
Longitude	The latitude of the phone number’s service area. Latitude is measured in degrees east or west of the Greenwich Meridian.
Nation Prefix	The digit(s) dialed before an area (city) code when calling a number within the same country but outside the numbering area.
National Destination Code	The national destination code, the numbering area within a country (or group of countries) and/or network/services.
PhoneNumber	The standardized phone number. This will return in varying formats depending on the inputs. For more detailed information, see Phone Number Format.
Postal Code	US Only. The zip code associated with the phone number.
Results	Comma delimited status, error codes, and change codes for the record. See the Result Codes for a full list.
Subscriber Number	The significant leading digits that further define the local exchange area and/or service.
Suggestions	An array of Response Record Elements. This is for single-record requests only.
Universal Time Code	The phone number’s time zone in the format: +/- hh:mm.

Result Codes

Result codes yield more granular information about a given record. They are returned as a comma-delimited string of 4-character alpha-numeric codes, e.g. AC02,AS01 or AE01.

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

SE## and GE## Codes

The SE## and GE## codes (Transmission Service Error and General Transmission Error) are used to signify more general errors, and are returned under the key TransmissionResults in the outermost level of our responses.

Personator Identity Codes