Quickstart Guide

Global Name

Global Name API can be used to:

  • Recognize over 530,000 last Names and 132,000 first Names.
  • Flag inappropriate words.
  • Detect company Names accidentally entered as a full Name.
  • Add casing for company Names.
Last Updated 05/13/2020
  • 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
Last Updated 05/13/2020

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/v4/web/Namelocation/doNamelocation?id=LICENSE_KEY &full=John Smith&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 HTTP POST. This means you cannot send it in a browser like with HTTP GET.

Header

Make sure the header includes this line.

Accept: application/json

Body

{
  "TransmissionReference":"Global Name Request Test",
  "CustomerID":"LICENSE_KEY_HERE",
  "Options":" ",
  "Records":[{
    "RecordID":"1",
    "Company":"",
    "FullName":"Mary J Jones"
  },
  {
    "RecordID":"2",
    "Company":"",
    "FullName":"John Smith"
  }]
}
Last Updated 05/13/2020
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.
VeryLikelyFull Name will be treated as normal name order unless inverse order is clearly indicated by formatting or punctuation.
ProbablyFull If necessary, statistical logic will be employed to determine name order, with a bias towards normal name order.
Varying Default. If necessary, statistical logic will be employed to determine name order, with no bias toward either name order.
ProbablyInverse If necessary, statistical logic will be employed to determine name order, with a bias toward inverse name order.
VeryLikelyInverse Name will be treated as inverse name order unless normal order is clearly indicated by formatting or punctuation.
DefinitelyInverse Name will always be treated as inverse name order, regardless of formatting or punctuation.
MixedFirstName Name element is expected to only contain first names.
MixedLastName Name element is expected to only contain last names.
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.
MiddleNameLogic
Code Description
ParseLogic Default. The service behaves as described above.
HyphenatedLast The middle word is assumed to be part of the last name. “Matthew Edward Jones” is treated as “Matthew Edward-Jones.”
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.
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
Last Updated 05/13/2020

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
Last Updated 05/13/2020

JSON Response

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

{
  "Version":"string",
  "TransmissionReference":"string",
  "TransmissionResults":"string",
  "TotalRecords":"string",
  "Records":[{
    "RecordID":"string",
    "Results":"string",
    "Company":"string",
    "NamePrefix":"string",
    "NameFirst":"string",
    "NameMiddle":"string",
    "NameLast":"string",
    "NameSuffix":"string",
    "Gender":"string",
    "NamePrefix2":"string",
    "NameFirst2":"string",
    "NameMiddle2":"string",
    "NameLast2":"string",
    "NameSuffix2":"string",
    "Gender2":"string"
  }]
}

JSON Batch Response

Here is a sample response of the batch request.

{
  "Version":"string",
  "TransmissionReference":"string",
  "TransmissionResults":"string",
  "TotalRecords":"string",
  "Records":[{
    "RecordID":"string",
    "Results":"string",
    "Company":"string",
    "NamePrefix":"string",
    "NameFirst":"string",
    "NameMiddle":"string",
    "NameLast":"string",
    "NameSuffix":"string",
    "Gender":"string",
    "NamePrefix2":"string",
    "NameFirst2":"string",
    "NameMiddle2":"string",
    "NameLast2":"string",
    "NameSuffix2":"string",
    "Gender2":"string"
  },
  {
    "RecordID":"string",
    "Results":"string",
    "Company":"string",
    "NamePrefix":"string",
    "NameFirst":"string",
    "NameMiddle":"string",
    "NameLast":"string",
    "NameSuffix":"string",
    "Gender":"string",
    "NamePrefix2":"string",
    "NameFirst2":"string",
    "NameMiddle2":"string",
    "NameLast2":"string",
    "NameSuffix2":"string",
    "Gender2":"string"
  },
  {
    ...
  }]
}
Last Updated 05/13/2020

Response (Base Level)

Output Name Description
Version The current service version
TransmissionReference Optional request identifier
TransmissionResults Service and General Transmission Errors

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.
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.
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.
Results Comma delimited status, error codes, and change codes for the record.
Last Updated 05/13/2020

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

Last Updated 05/13/2020