Reference Guide#

Introduction#

Welcome to the NameLib Service by Melissa. The NameLib 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.

Data Path#

This is set during the containerization service setup. It is whatever data path you set.

See {{data_path}} in the Example Docker Setup

Service Port Number#

This is set during the containerization service setup. It defaults to 6245, but can be any port you set.

See {{port_number}} in the Example Docker Setup

Machine Name#

This is your local machine name. You’ll use this in every request you send to your local containerization service. You can view your machine name by using the hostname command in the command prompt.

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 the service will not function.

Endpoints#

/V3/WEB/ContactVerify/GetVersion#

Introduction#

Use this endpoint to check the version of the NameLib Service.

Try It Now#

  • GET JSON
curl -X GET \
"http://{{machine_name}}:{{port_number}}/V3/WEB/ContactVerify/GetVersion" \
-H "accept: application/json"

Headers#

  • GET JSON
cache-control: no-cache,no-store,must-revalidate,private
content-type: application/json; charset=utf-8
pragma: no-cache

Response#

  • GET JSON
{
  "Version_0": "7.4.1.17768",
  "ServiceName_0": "NameLibService",
  "InitializationErrorCode_0": "0",
  "InitializationErrorMessage_0": "No error.",
  "BuildNumber_0": "17768",
  "DatabaseDate_0": "2023-07-01",
  "ExpirationDate_0": "2024-07-02",
  "LicenseExpirationDate_0": "2024-07-02",
  "CanadaDatabaseDate_0": "2023-07-15",
  "CanadaExpirationDate_0": "2024-07-02",
  "Version_1": "7.4.1.17768",
  "ServiceName_1": "NameLibService",
  "InitializationErrorCode_1": "0",
  "InitializationErrorMessage_1": "No error.",
  "BuildNumber_1": "17768",
  "DatabaseDate_1": "2023-07-01",
  "ExpirationDate_1": "2024-07-02",
  "LicenseExpirationDate_1": "2024-07-02",
  "CanadaDatabaseDate_1": "2023-07-15",
  "CanadaExpirationDate_1": "2024-07-02",
  "Version_2": "7.4.1.17768",
  "ServiceName_2": "NameLibService",
  "InitializationErrorCode_2": "0",
  "InitializationErrorMessage_2": "No error.",
  "BuildNumber_2": "17768",
  "DatabaseDate_2": "2023-07-01",
  "ExpirationDate_2": "2024-07-02",
  "LicenseExpirationDate_2": "2024-07-02",
  "CanadaDatabaseDate_2": "2023-07-15",
  "CanadaExpirationDate_2": "2024-07-02"
}

/V3/WEB/ContactVerify/doContactVerify#

Introduction#

Use this endpoint to use all the name verification capabilities of Name Object.

Try It Now#

  • GET JSON
  • POST JSON
curl -X GET \
"http://{{machine_name}}:{{port_number}}/V3/WEB/ContactVerify/doContactVerify?\
t=test\
&id={{license_key}}\
&ctry=US\
&a1=22382%20Avenida%20Empresa\
&city=Rancho%20Santa%20Margarita\
&state=CA\
&postal=92688\
&comp=Melissa\
&format=json"\
-H "accept:application/json"

curl -X 'POST' \
  'http://{{machine_name}}:{{port_number}}/V3/WEB/ContactVerify/doContactVerify' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "customerId": "{{license_key}}",
  "options": "",
  "transmissionReference": "test",
  "records": [
    {
      "recordID": "1",
      "addressLine1": "22382 Avenida Empresa",
      "addressLine2": "",
      "suite": "",
      "city": "Rancho Santa Margarita",
      "state": "CA",
      "postalCode": "92688",
      "lastLine": "",
      "plus4": "",
      "deliverypointcode": "",
      "company": "Melissa",
      "urbanization": "",
      "lastName": "",
      "country": "US"
    }
  ]
}'
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
Content-Type: application/json
Accept: application/json

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

Response#

  • GET JSON
  • POST JSON
{
  "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": ""
     }
   ]
 }
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