Reference Guide#

Introduction#

Welcome to the Global Name Service by Melissa. The Global Name Web Service gives you the ability to parse full and multiple names, standardize common company indicators, detect dual names, identify gender, and flag vulgar/suspicious names.

Base URL#

https://globalname.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 at sales@melissa.com or 800-MELISSA ext. 3 (800-635-4772 ext. 3). Without a license key, Global Name will not function.

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

Endpoints#

/V3/WEB/GlobalName/doGlobalName#

The Global Name doGlobalName endpoint does all the name verification by choosing the actions and options needed.

Try It Now#

  • GET JSON
  • POST JSON
  • GET XML
  • POST XML
curl -X GET "https://globalname.melissadata.net/V3/WEB/GlobalName/doGlobalName?\
id={{customerId}}\
&full=Doktor%20Enna%20Sch%C3%A4fer&ctry=DE\
&t=Global%20Name%20CurlExample" \
-H "Content-Type: application/json" \
-H "Accept: application/json"

curl -X POST "https://globalname.melissadata.net/V3/WEB/GlobalName/doGlobalName?" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
    "TransmissionReference": "JSON Global Name Test",
    "CustomerID": {{customerId}},
    "Options": "",
    "Records": [
        {
            "RecordID": "1",
            "Country": "DE",
            "FullName": "Doktor Enna Schäfer"
        },
        {
            "RecordID": "2",
            "Country": "US",
            "FullName": "Ray Melissa"
        }
    ]
  }'

curl -X GET "https://globalname.melissadata.net/V3/WEB/GlobalName/doGlobalName?\
id={{customerId}}\
&full=Doktor%20Enna%20Sch%C3%A4fer&ctry=DE\
&t=Global%20Name%20CurlExample" \
-H "Content-Type: application/xml" \
-H "Accept: application/xml"

curl -X POST "https://globalname.melissadata.net/V3/WEB/GlobalName/doGlobalName?" \
-H "Content-Type: application/xml" \
-H "Accept: application/xml" \
-d '<Request>
      <TransmissionReference>XML Global Name Test</TransmissionReference>
      <CustomerID>{{customerId}}</CustomerID>
      <Options></Options>
      <Records>
        <RequestRecord>
            <RecordID>1</RecordID>
            <Country>DE</Country>
            <FullName>Doktor Enna Schäfer</FullName>
        </RequestRecord>
        <RequestRecord>
            <RecordID>2</RecordID>
            <Country>US</Country>
            <FullName>Ray Melissa</FullName>
        </RequestRecord>
      </Records>
    </Request>'

Request Parameters#

Code

Description

Record Level Parameters

format

Specify the desired format of the response (XML or JSON). Defaults to XML.

id

The License Key issued by Melissa.

opt

Set Options

CorrectFirstName

NameHint

GenderPopulation

GenderAggression

MiddleNameLogic

SalutationOrder

SalutationSlug

SalutationPrefix

SalutationSuffix

LegacySalutation (US/CAN Only)

t

This is a string value that serves as a unique identifier for this set of records. It is returned as sent.

Name Parameters

comp

The company name to be standardized.

ctry

The country name, abbreviation, or ISO code of the input name.

full

The full name to be genderized, standardized, and parsed. 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.

Headers#

  • GET JSON
  • POST JSON
  • GET XML
  • POST XML
Content-Type: application/json
Accept: application/json

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

Content-Type: application/xml
Accept: */*

Content-Type: application/xml
Accept: */*

Response#

  • GET JSON
  • POST JSON
  • GET XML
  • POST XML
{
  "Version": "7.4.1.4108",
  "TransmissionReference": "Global Name CurlExample",
  "TransmissionResults": "",
  "TotalRecords": "1",
  "Records": [
    {
      "RecordID": "1",
      "Results": "NS01,NS05,NS06",
      "Company": "",
      "NamePrefix": "Doktor",
      "NameFirst": "Enna",
      "NameMiddle": "",
      "NameLast": "Schäfer",
      "NameSuffix": "",
      "NameNickname": "",
      "NameProfTitle": "",
      "Gender": "F",
      "NamePrefix2": "",
      "NameFirst2": "",
      "NameMiddle2": "",
      "NameLast2": "",
      "NameSuffix2": "",
      "NameNickname2": "",
      "NameProfTitle2": "",
      "Gender2": "",
      "Salutation": "",
      "Extras": ""
    }
  ]
}

{
   "Version": "7.4.1.4108",
   "TransmissionReference": "Global Name CurlExample",
   "TransmissionResults": "",
   "TotalRecords": "1",
   "Records": [
     {
       "RecordID": "1",
       "Results": "NS01,NS05,NS06",
       "Company": "",
       "NamePrefix": "Doktor",
       "NameFirst": "Enna",
       "NameMiddle": "",
       "NameLast": "Schäfer",
       "NameSuffix": "",
       "NameNickname": "",
       "NameProfTitle": "",
       "Gender": "F",
       "NamePrefix2": "",
       "NameFirst2": "",
       "NameMiddle2": "",
       "NameLast2": "",
       "NameSuffix2": "",
       "NameNickname2": "",
       "NameProfTitle2": "",
       "Gender2": "",
       "Salutation": "",
       "Extras": ""
     }
   ]
 }

<Response
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   xmlns="urn:mdGlobalName">
   <Version>7.4.1.4108</Version>
   <TransmissionReference>Global Name CurlExample</TransmissionReference>
   <TransmissionResults />
   <TotalRecords>1</TotalRecords>
   <Records>
     <ResponseRecord>
       <RecordID>1</RecordID>
       <Results>NS01,NS05,NS06</Results>
       <Company />
       <NamePrefix>Doktor</NamePrefix>
       <NameFirst>Enna</NameFirst>
       <NameMiddle />
       <NameLast>Schäfer</NameLast>
       <NameSuffix />
       <NameNickname />
       <NameProfTitle />
       <Gender>F</Gender>
       <NamePrefix2 />
       <NameFirst2 />
       <NameMiddle2 />
       <NameLast2 />
       <NameSuffix2 />
       <NameNickname2 />
       <NameProfTitle2 />
       <Gender2 />
       <Salutation />
       <Extras />
     </ResponseRecord>
   </Records>
 </Response>

<Response
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   xmlns="urn:mdGlobalName">
   <Version>7.4.1.4108</Version>
   <TransmissionReference>Global Name CurlExample</TransmissionReference>
   <TransmissionResults />
   <TotalRecords>1</TotalRecords>
   <Records>
     <ResponseRecord>
       <RecordID>1</RecordID>
       <Results>NS01,NS05,NS06</Results>
       <Company />
       <NamePrefix>Doktor</NamePrefix>
       <NameFirst>Enna</NameFirst>
       <NameMiddle />
       <NameLast>Schäfer</NameLast>
       <NameSuffix />
       <NameNickname />
       <NameProfTitle />
       <Gender>F</Gender>
       <NamePrefix2 />
       <NameFirst2 />
       <NameMiddle2 />
       <NameLast2 />
       <NameSuffix2 />
       <NameNickname2 />
       <NameProfTitle2 />
       <Gender2 />
       <Salutation />
     </ResponseRecord>
   </Records>
 </Response>
Service Level Response Fields#

Output Name

Description

TotalRecords

Total number of records.

TransmissionReference

Optional. Serves as a unique request identifier.

TransmissionResults

Lists error codes from any errors caused by the most recent request as a whole.

Version

The current service version number.
Record Level Response Fields#

Output Name

Description

Company

This is a string value of the standardized company name.

Extras

This is a string value of the input words not associated with a parsed name part.

Gender

This is a one-character string value indicating the gender of the first name from the input.

Gender2

This is a one-character string value indicating the gender of the inputted full name. If the FullName input property contained multiple names, the gender of the second name will be returned here.

NameFirst

This is a string value of the first name from an inputted full name.

NameFirst2

This is a string value of 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

This is a string value of the last name from an inputted full name.

NameLast2

This is a string value of 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

This is a string value of the middle name from an inputted full name.

NameMiddle2

This is a string value of 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

This is a string value of the first prefix (such as “Mr.” or “Dr.”) from an inputted full name.

NamePrefix2

This is a string value of 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

This is a string value of the first suffix (such as “Jr.” or “III”) from an inputted full name.

NameSuffix2

This is a string value of 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.

Nickname

This is a string value of an identified nickname from an inputted full name.

Nickname2

This is a string value of an identified nickname from an inputted full name. If the FullName input property contained multiple names, the nickname of the second name will be returned here.

ProfessionalTitle

This is a string value of the professional title from an inputted full name.

ProfessionalTitle2

This is a string value of the professional title from an inputted full name. If the FullName input property contained multiple names, the professional title of the second name will be returned here.

RecordID

This is a string value that is a unique identifier for the current record if one was sent in the request. Use this element to match a request record and the corresponding response record.

Results

Comma delimited status, error codes, and change codes for the record.

Salutation

This is a string value of the response’s name properties which can be used to create a salutation format.

Options#

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. Global Name uses 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.
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.
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.
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.
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.

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:

Parameter Name

Definition

Example

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.

Parameter Name

Definition

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

Parameter Name

Definition

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

Parameter Name

Definition

<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. his option will create a formal (Mr/Mrs) salutation from an assigned FirstName gender for US/CAN.

Parameter

Description

OFF

Creates a formal salutation.

ON

Default. Will not create a formal salutation.

For example:

opt=LegacySalutation:On

Will return Mr. John Smith when the input was John Smith

Result Codes#

Interpreting Results#

Result codes yield more granular information about a given name. They are returned as a comma-delimited string of 4-character alpha-numeric codes, e.g. ES01,ES07,ES21 or EE04,ES22.

Result Codes (Advanced)#

NS## and NE## Codes#

The NS## and NE## codes (Name Status and Name Error) are returned alongside each name record in a request.

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.

Using Result Codes#

Service Level Result Codes#

Code

Short Description

Long Description

Transmission Service Error

SE01

Cloud Service Internal Error

The cloud service experienced an internal error.

General Transmission Error

GE02

Empty Request Record Structure

The SOAP, JSON, or XML request record structure is empty. Not to be confused with the GE02 GeoCode result code.

GE03

Records Per Request Exceeded

The counted records sent more than the number of records allowed per request.

GE04

Empty License Key

The License Key is empty.

GE05

Invalid License Key

The License Key is invalid.

GE06

Disabled License Key

The License Key is disabled.

GE08

Product/Level Not Enabled

The License Key is invalid for this product or level.

GE14

Out of Credits

The account has ran out of credits. Add more credits to continue using the service.

Record Level Result Codes#

Code

Short Description

Long Description

NS - Name Status

NS01

Parsing Successful

Name parsing was successful.

NS02

Error Parsing

An error was detected. Please check for a name error code.

NS03

First Name Spelling Corrected

The spelling in the first name field was corrected.

NS04

First Name 2 Spelling Corrected

The spelling in the second first name field was corrected.

NS05

First Name 1 Found

FirstName1 was found in our census table of names. Very likely to be a real first name.

NS06

Last Name 1 Found

LastName1 was found in our census table of names. Very likely to be a real last name.

NS07

First Name 2 Found

FirstName2 was found in our census table of names. Very likely to be a real first name.

NS08

Last Name 2 Found

LastName2 was found in our census table of names. Very likely to be a real last name.

NS09

Dual-name Parsed

Input has dual-name contents and was split it into two single-name outputs.

NS99

Company Name Standardized

The company name was standardized.

NE - Name Error

NE01

Unrecognized Format

Format of Input string was not recognized or too long to represent a valid name.

NE02

Multiple First Names Detected

Multiple first names were detected and could not be accurately genderized.

NE03

Vulgarity Detected

A vulgarity was detected in the name.

NE04

Suspicious Word Detected

The name contained words found on the list of nuisance names, such as “Mickey Mouse.”

NE05

Company Name Detected

The name contained words normally found in a company name.

NE06

Non-Alphabetic Character Detected

The name contained a non-alphabetic character.

NE07

Multiple Names Split Detected

Multiple names sets were detected when split, only the first two set are parsed.

NE08

Unicode/Non-Latin Name Input

Unicode characters detected on input. We do not support Unicode at this time; the input is returned as-is.

NE09

Multiple Formats Detected

Multiple Formats - Forward and Inverse - Detected

NE10

Missing Minimum Name

Minimum requirements for the name input data is not met. Name must have at least one Alpha Character to be parsed.

NE11

Non-Name Word Detected

Non-Name word such as a “Dept.” or Job Title detected.

NE99

Company Standardization Not Needed

Company name standardization was attempted, but did not produce a different result.

DE - Data Error

DE

Data Field Error

The data field was empty.