Quickstart Guide

Global Name

Introduction

Global Name API can be used to:

  • Recognize over 6,000,000 last names and 4,000,000 first names across different countries and languages.
  • Split dual names (ex. Mr and Mrs John and Mary Jones)
  • Assign gender based on known first names and prefixes.
  • Output preferred output Salutation name parts.

Basic Order of Operations

  • Create an instance of the request object
  • Populate the request element CustomerID with your product license key
  • Add input Names to the “Records” array with anywhere from 1 to 100 records
  • Call the method and pass in the request to the service using the WEB endpoint for JSON requests
  • Examine and parse the response from the reply object back from the service
  • Interpret the result codes

Input Request

NOTE: It expects UTF-8 character encoding. Be on the lookout for question marks (?), squares (▖) or other weird characters like �. They may be an indication of encoding issues and may result in data loss. Bad encoding or character loss is not something our service can correct for you.

Real Time

With a REST request, you can include all the input along with the URL for an easy and quick way of sending a single record.

curl –X GET https://globalName.melissadata.net/V3/WEB/GlobalName/doGlobalName?id=LICENSE_KEY &full=Doktor Enna Schäfer&ctry=DE&t=Global Name CurlExample

You can also put the URL without the "curl -X GET" command directly into your browser. You can also toggle between getting XML or JSON back using the format input parameter. As you can see, in this example, we are asking for JSON back.

Batch

You can send batch requests of up to 100 records per batch that are sent using HTTPS POST. This means you cannot send it in a browser like with HTTPS GET.

Header

The following values are required in the header:

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

Body

{
    "TransmissionReference":"Global Name Request Test",
    "CustomerID":"LICENSE_KEY_HERE",
    "Options":"",
    "Records":[{
      "RecordID":"1",
      "Company":"",
      “Country”: “US”,
      "FullName":"Mary J Jones"
    },
    {
      "RecordID":"2",
      "Company":"",
      “Country”: “Germany”,
      "FullName":"Doktor Enna Schäfer"
    }]
  }
  

Input Fields

Batch Input REST Input Description REQUIRED
TransmissionReference t This is a string value that serves as a unique identifier for this set of records. It is returned as sent. NO
CustomerID id The License Key issued by Melissa. YES
Options opt CorrectFirstName
Code Description
OFF Default. Preserve first name spellings; no correction allowed.
ON Allows first name misspelling corrections.
NameHint
Code Description
DefinitelyFull Name will always be treated as normal name order regardless of formatting or punctuation.
Varying Default. If necessary, statistical logic will be employed to determine name order, with no bias toward either name order.
DefinitelyInverse Name will always be treated as inverse name order, regardless of formatting or punctuation.
GenderPopulation
Code Description
Male Bias toward male.
Mixed Default. No bias toward either gender.
Female Bias toward female.
GenderAggression
Code Description
Aggressive Aggressive name genderizing.
Neutral Default. Neutral name genderizing.
Conservative Conservative name genderizing.
Salutation
Code Description
Formal Default. Contains the name prefix, last name, and suffix. Ex: Mr. Smith MD
Informal Contains the first name. Ex: John
FirstLast Contains the fist name and last name. Ex: John Smith
Blank Returns <blank>. Ex: <blank>
Company comp Company name to be standardized (Optional; Required if FullName is not inputted) YES/NO
FullName full Full name to be genderized, standardized, and parsed (Optional; Required if Company is not inputted) YES/NO
Country ctry The Country ISO2, ISO3, or spelled out name. (Optional; default is US) NO

Input Best Practices

Single Record vs Batch Processing

Melissa Data cloud services are capable of both single record real-time processing and batch processing. The difference is simply in the number of records sent in each request. Melissa Data cloud services take an array of records. This array can contain a single record or 100 records. For a real time process like a web form entry or a call center application, send in a request with one record. For batch processing scenario like a database, send requests of up to 100 records until all the records are processed.

Error Handling

Since Melissa Data uses multiple clustered servers, in the unlikely event that one server is temporarily overloaded or down, it is very likely that another server is up and running. For this reason, it is best to catch any errors returned by the service and retry. We recommend retrying up to 5 times.

int Retry = 0;
  Boolean ReqRet = false;
  do
  {
    try
    {
      // Perform Phone Lookup and store results to the Response
      ResPhone = PhoneClient.doPhoneCheck(ReqPhone);
      ReqRet = true;
    }
    catch (Exception ex)
    {
      MessageBox.Show(ex.ToString());
      Retry++;
    }
  } while ((ReqRet == false) && (Retry < 5));2

Output Response

JSON Response

Here is a sample response of the real-time request from above.

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

JSON Batch Response

Here is a sample response of the batch request.

{
    "Version": "4.0.0.24",
      "TransmissionReference": "GlobalNameWSExample",
      "TransmissionResults": "",
      "TotalRecords": "2",
      "Records": [
          {
              "RecordID": "1",
              "Results": "NS01,NS05,NS06",
              "Company": "",
              "NamePrefix": "",
              "NameFirst": "Mary",
              "NameMiddle": "J",
              "NameLast": "Jones",
              "NameSuffix": "",
              "NameNickname": "",
              "NameProfTitle": "",
              "Gender": "F",
              "NamePrefix2": "",
              "NameFirst2": "",
              "NameMiddle2": "",
              "NameLast2": "",
              "NameSuffix2": "",
              "Gender2": "",
              "NameNickname2": "",
              "NameProfTitle2": "",
              "Salutation": "Mary"
          },
          {
              "RecordID": "2",
              "Results": "NS01,NS05,NS06",
              "Company": "",
              "NamePrefix": "Doktor",
              "NameFirst": "Enna",
              "NameMiddle": "",
              "NameLast": "Schäfer",
              "NameSuffix": "",
              "NameNickname": "",
              "NameProfTitle": "",
              "Gender": "U",
              "NamePrefix2": "",
              "NameFirst2": "",
              "NameMiddle2": "",
              "NameLast2": "",
              "NameSuffix2": "",
              "Gender2": "",
              "NameNickname2": "",
              "NameProfTitle2": "",
              "Salutation": "Doktor Schäfer"
          }
      ]
  }

Output Fields

Response (Base Level)

Output Name Description
Version The current service version
TransmissionReference Optional request identifier
TransmissionResults Service and General Transmission Errors
Total Records The total number of records returned.
Records The returned array of records.

Record Level

Output Name Description
RecordID 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.
Company The standardized company name.
NamePrefix The first identified prefix from the input full name.
NameFirst The first identified first name from the input full name.
NameMiddle The first identified middle name from the input full name.
NameLast The first identified last from the input full name.
NameSuffix The first identified suffix from the input full name.
NameNickname The first identified nickname from the input full name.
NameProfTitle The first professional title from the input full name.
Gender A one-character string value indicating the gender of the first name from the input.
NamePrefix2 The second identified prefix from the input full name.
NameFirst2 The second identified first name from the input full name
NameMiddle2 The second identified middle name from the input full name.
NameLast2 The second identified last from the input full name.
NameSuffix2 The second identified suffix from the input full name.
NameNickname2 The second identified nickname from the input full name.
NameProfTitle2 The second professional title from the input full name.
Gender2 A one-character string value indicating the gender of the second name from the input.
Salutation The first identified name properties which you can use to create the desired salutation format.

Interpreting Results

Melissa products use a result code system to indicate data quality; the status and any errors. These result codes are four-character codes (two letters followed by two numbers), delimited by commas. Result code definitions are shared among Melissa products. Instead of looking at multiple properties and methods to determine status, you can look at the output of the results parameter.

Example

This example input: ‘Mr John and Mrs Mary Jones’ will return the result code string:

NS01, NS05, NS06, NS07, NS08

From these Result codes you can determine that the disposition of the Name is:

Code Description Recommendation
NS01 Name Parsing Successful Medium
NS03 First Name 1 Spelling Corrected Medium
NS04 First Name 2 Spelling Corrected Medium
NS05 First Name 1 Found Good
NS06 Last Name 1 Found Good
NS07 First Name 2 Found Good
NS08 Last Name 2 Found Good
NS02 Error Detected. Check name error codes. Bad
NE03 Vulgar Detected Bad
NE04 Suspicious Word Detected Bad

For a list of the common transmission errors, see the General Info - Response Level Errors page.

For the full list of all possible result codes, please visit our Result Wiki page at Global Name Result Code Details.