Global Name:Request

From Melissa Data Wiki
Revision as of 22:29, 14 October 2016 by Admin (talk | contribs)
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 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 (HTTP Header) Accept: application/json
XML (HTTP Header) Accept: application/xml


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>