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

New to Melissa Cloud Services?#

We highly recommend first time users of our web services to review our Using Melissa Cloud APIs section. It will cover critical topics like:

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.

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 #

Please visit SSN Name Match Result Codes for a full list of result codes returned by SSN Name Match.

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.

The following shows you the indicators for the different results:

Code	Description	Quality Indicator
`SN04`	The SSN matched to both the first and last name of the input record.	Good Data
`SN05`	The SSN and last name match, but the first names did not match.	Good Data
`SN06`	The SSN and the first name matched, and first name could be female.	Good Data
`SN08`	The SSN number matched the last name, but was unable to fully match the first name as only an initial was provided.	Good Data
`SN01`	The SSN had too many or too few digits.	Bad Data
`SN02`	The SSN was not found in the reference database. This indicates either a number not issued or a number that has been issued but is not available.	Potentially Bad Data
`SN03`	The SSN was found on the deceased list – no matching was made to the input name as this number is no longer active.	Potentially Bad Data
`SN07`	The SSN belongs to a name different from the one that was input.	Potentially Bad Data