Global Name:Request

From Melissa Data Wiki
Jump to navigation Jump to search

← Global Name

Global Name Navigation
Introduction
Licensing
Input/Request
Request Fields
Response Fields
Examples
REST JSON
REST JSONP
REST XML
Batch JSON
Batch SOAP
Batch XML
Result Codes
Result Code Use
Global Name Result Codes
Sample Code



A request consists of a protocol to make a call detailing desired elements. The minimum required elements in a request are your Customer ID (License Key) and at least a full name or company name.

Global Name supports JSON, JSONP, REST, SOAP, and XML protocols.


URL

REST, XML, JSON, etc.

Use URL
Secure https://globalname.melissadata.net/V3/WEB/GlobalName/doGlobalName


Header

HTTP headers need to match the protocols and formats being used.

Global Name requires the values of Content-Type and Accept.

Example JSON Request Header

{
    "Content-Type": "application/json; charset=utf-8",
    "Accept": "application/json"
}


Field Names

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

Field Name Level REST JSON/XML
Transmission Reference Request t TransmissionReference
License Key id CustomerID
Options opt Options
Format format Format
Record ID Record RecordID
Company comp Company
Full Name full FullName
Country ctry Country


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
SOAP/XML <TransmissionReference>string</TransmissionReference>


License Key

Required.
This is a string value containing the License Key issued to the customer by Melissa Data for Global Name.
If this element is absent, the Cloud 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
SOAP/XML <CustomerID>string</CustomerID>


Options

Optional.
This is a string value containing the options set by the user.
Protocol Syntax
JSON "Options":"string"
REST ?opt = string
SOAP/XML <Options>string</Options>


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.
Global Name uses a database of commonly misspelled first names 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 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.


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


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


Notes on Gender assignment
Gender values are assigned on the probability of a gender - compiled genders associated with known names.
For example:
Input Assigned Gender Notes
John Smith M John most always represents a male.
Pat Smith N Pat is a common male and female name.
Mary Smith F Mary most always represents a female.
Smith Input doesn't contain data necessary to determine gender.
Unknown Smith U Input has tokens where gender is unknown to the service.


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.


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.


SalutationOrder

Optional. This option creates a pipe delimited list of preferred salutation formats and precedence to use when generating salutations. There are five possible formats to use for creating salutations. The options in default order are:


Option Name Parameter Name Definition Example
Salutation Formal Contains name prefix and lastname and suffix Mr. Smith MD
Informal Contains firstname. John
FirstLast Contains firstname and lastname. John Smith
Slug Substitution when desired in SalutationOrder Valued Customer
Blank <return blank> <blank>
For example, if the request is configured as:
opt=Salutation:Formal|FirstLast|Blank|Informal
This requests a formal salutation to be built where possible but would rather have a blank salutation than an informal salutation (this could replace a blank with a proprietary slug like ‘Valued Customer:’).


SalutationSlug

Optional. Accepts a string value and sets the text that will be substituted for a name into salutations generated when salutationOrder:Slug can be returned.


Option Name Parameter Name Definition
SalutationSlug <your custom slug> Sets the text for substituting a name in salutations.
For example:
opt=SalutationSlug:Valued Customer
Will return 'Dear Valued Customer' when other formats are lower in the salutationOrder


SalutationPrefix

Optional. This option lets you set the preferred text that you want before the proper name in generated salutations.


Option Name Parameter Name Definition
SalutationPrefix <your custom prefix> Sets the prefix for the salutation name.
For example:
opt=SalutationPrefix:Dear
Will return 'Dear John Smith'


SalutationSuffix

Optional. This option lets you set the preferred text that follows the proper name in salutations generated.
Use a _ (underscore) if your suffix requires a space in the response.


Option Name Parameter Name Definition
SalutationSuffix <your custom suffix> Sets the suffix for the salutation name.
For example:
opt=SalutationSuffix:_and family
Will return 'John Smith and family'


LegacySalutation (US/CAN only)

Optional. This option will create a formal (Mr/Mrs) salutation from an assigned FirstName gender for US/CAN.


Option Name Parameter Definition
LegacySalutation On Creates a formal salutation.
Off Default. Will not create a formal salutation.
For example:
opt=LegacySalutation:On
Will return 'Mr. John Smith' when the input was 'John Smith'


Format

Optional.
The desired format of the response. Possible values for this option are "json" or "xml". The default value is "xml".
Protocol Syntax
REST &format = string


Request Record Elements

JSON will only contain the Records element.

Protocol Definition
JSON Each name will be contained within [{}] under the Records element.
REST The REST interface only allows a single record per request.
SOAP This element is an array of object variables of the type RequestRecords.
XML There will be one RequestRecord element per address being submitted to the Cloud Service.


RecordID

Optional.
This is a string value containing a unique identifier for the current record. Use this to match the record submitted with the record returned. It will return the input.
Protocol Syntax
JSON "RecordID":"string"
SOAP/XML <RecordID>string</RecordID>


Company

Optional. (Required if FullName is not inputted).
The company name to be standardized.
Protocol Syntax
JSON "Company":"string"
REST &comp = string
SOAP/XML <Company>string</Company>


FullName

Optional. (Required if Company is not inputted).
The full name to be genderized, standardized, and parsed.
Protocol Syntax
JSON "FullName":"string"
REST &full = string
SOAP/XML <FullName>string</FullName>


Country

Optional. (Default is US if not specified).
The country name, abbreviation, or ISO code of the input name.
Protocol Syntax
JSON "Country":"string"
REST &ctry = string
XML <Country>string</Country>