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 and at least a full name or company name.

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

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
Customer ID		id	CustomerID
Options		opt	Options
Format		format	Format
Record ID	Record		RecordID
Company		comp	Company
Full Name		full	FullName

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>

Customer ID

Required.

This is a string value containing the identification number 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 customer ID, 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	Name will be treated as normal name order unless inverse order is clearly indicated by formatting or punctuation.
	3	ProbablyFull	If necessary, statistical logic will be employed to determine name order, with a bias towards normal name order.
	4	Varying	Default. If necessary, statistical logic will be employed to determine name order, with no bias toward either name order.
	5	ProbablyInverse	If necessary, statistical logic will be employed to determine name order, with a bias toward inverse name order.
	6	VeryLikelyInverse	Name will be treated as inverse name order unless normal order is clearly indicated by formatting or punctuation.
	7	DefinitelyInverse	Name will always be treated as inverse name order, regardless of formatting or punctuation.
	8	MixedFirstName	Name element is expected to only contain first names.
	9	MixedLastName	Name element is expected to only contain last names.

GenderPopulation

This option sets the gender balance of the source data, predominantly male, predominantly female, or neutral.

If you know that the majority of inputted names will be predominantly one gender, meaning that gender-neutral names will likely be of a particular gender, use this property to set the gender bias while genderizing names.

Either the ‘Code’ or ‘Name’ listed below can be used to set the action.

For example, Options = GENDERPOPULATION:3 and Options = GENDERPOPULATION:Female are equivalent settings.

Option Name	Parameter Code	Parameter Name	Definition
GenderPopulation	1	Male	Bias toward male.
	2	Mixed	Default. No bias toward either gender.
	3	Female	Bias toward female.

GenderAggression

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

By default, 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

MiddleNameLogic

This option controls how middle names are handled.

Some names can be ambiguous with regards to the middle word of a full name. It may be a middle name or it may be the first part of a hyphenated last name, but the hyphen has been omitted for some reason.

Normally, the service assumes that, in the absence of a hyphen, recognizable last names in the middle of a full name are treated as part of a hyphenated last name. “Mary O’Malley Kelly” is parsed into first name “Mary” and last name “O’Malley-Kelly.”

On the other hand, “Colleen Marie Sullivan” is parsed into first name “Colleen,” middle name “Marie,” and last name “Sullivan.”

Either the ‘Code’ or ‘Name’ listed below can be used to set the action.

For example, Options = MIDDLENAMELOGIC:0 and Options = MIDDLENAMELOGIC:ParseLogic are equivalent settings.

Option Name	Parameter Code	Parameter Name	Definition
MiddleNameLogic	0	ParseLogic	Default. The service behaves as described above.
	1	HyphenatedLast	The middle word is assumed to be part of the last name. “Matthew Edward Jones” is treated as “Matthew Edward-Jones.”
	2	MiddleName	The middle word is assumed to be a middle name. for the name “Mary O’Malley Kelly,” O’Malley is assumed to be the middle name.

When a hyphen is present, the hyphenated word is always treated as the last name, regardless of content.

Format

Optional.

The desired format of the response.

Protocol	Syntax
REST	&format = string
JSON/XML	HTTP Header XML application/xml JSON application/json

Request Record Elements

JSON will only contain the Records element.

Protocol	Definition
JSON	Each email 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>