Reference Guide

Reference Guide#

Introduction#

The SSN Name Match Web Service validates First and Last Names against Social Security Numbers for verification.

Base URL#

https://namessn.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 by Requesting a Demo or by calling 800-MELISSA ext. 3 (800-635-4772 ext. 3). Without a license key, SSN Name Match will not function.

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

Endpoints#

/v4/web/SSN/doLookup#

Check if the Social Security Number is within the acceptable range, and match against the First and Last Name.

Try It Now#

  • GET JSON
  • POST JSON
curl -X GET "https://namessn.melissadata.net/v4/web/SSN/doLookup?\
&format=json\
&id={{customerId}}\
&first=John\
&full=John%20Doe\
&last=Doe\
&ssn=111222333" \

curl -X POST "https://namessn.melissadata.net/v4/web/SSN/doLookup" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
      "CustomerID": {{customerId}},
      "Records": [
         {
            "FirstName": "John",
            "FullName":"John Doe",
            "LastName": "Doe",
            "RecordID": "1",
            "SSN": "111222333"
         }
      ]
   }'

Request Parameters#

  • GET JSON
  • POST JSON

Code

Description

Request Level Parameters

format

Sets the format of the response.

id

This is a string value containing the License Key issued to the customer by Melissa Data for the web service.

t

Optional. Serves as a unique request identifier.

Record Level Parameters

first

The given (first) name.

full

This field can contain a full name. We will parse and check Names only if the First Name and Last Name fields are left blank.

last

The family (last) name.

ssn

This is a string value containing the Social Security Number. All hyphens are ignored when submitting the SSN. We recommended using only numbers when submitting the SSN.

Code

Description

Request Level Parameters

TransmissionReference

Optional. Serves as a unique request identifier.

UserId

This is a string value containing the License Key issued to the customer by Melissa Data for the web service.

Record Level Parameters

FirstName

The given (first) name.

FullName

This field can contain a full name. We will parse and check Names only if the First Name and Last Name fields are left blank.

LastName

The family (last) name.

RecordID

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 what is inputted.

SSN

This is a string value containing the Social Security Number. All hyphens are ignored when submitting the SSN. We recommended using only numbers when submitting the SSN.

Headers#

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

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

Response#

  • GET JSON
  • POST JSON
{
  "TransmissionResults":"",
  "TransmissionReference":"",
  "Version":"6.2.0.1028",
  "TotalRecords":"1",
  "Records":[
      {
          "RecordID":"1",
          "SSN":"111222333",
          "IssuingState":"New York",
          "Results":"SN07",
          "ResultsFromDataSource":"TU01"
      }
  ]
}

{
  "TransmissionResults":"",
  "TransmissionReference":"",
  "Version":"6.2.0.1028",
  "TotalRecords":"1",
  "Records":[
      {
          "RecordID":"1",
          "SSN":"111222333",
          "IssuingState":"New York",
          "Results":"SN07",
          "ResultsFromDataSource":"TU01"
      }
  ]
}
Service Level Response Fields#

Output Name

Description

Version

The current service version number.

TransmissionReference

A pass-through of the input TransmissionReference field.

TransmissionResults

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

TotalRecords

Total number of records.
Record Level Response Fields#

Output Name

Description

RecordID

The number of the record. Always 1 for a single request, otherwise it serves as an index of the array of records.

SSN

Returned string value of the Social Security Number submitted for validation.

IssuingState

A string value of the issued state calculated by using the SSN Area Number (first 3 digits of the SSN).

Results

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

Input Best Practices#

This service can deal with multiple languages and scripts. It expects UTF-8 encoding. Be on the lookout for question marks (?), squares (▖) or other unwanted 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.

Result Codes#

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

Understanding the Code#

To fully understand result codes, you need to know them. Knowing what codes are possible and what they indicate will be key in building an effective application. It is useful to know all the codes, but this does not necessarily mean you will use them all. Just because you have a toolbox, doesn’t mean you will also try to use a screwdriver along with a hammer on a nail.

SSN Name Match Result Codes

Contents