Global Name:Request

← Global Name

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>