Quickstart Guide

SSN Name Match

Introduction

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

In addition, the service also checks if the SSN is flagged as deceased.

SSN Name Match can be used to:

  • Verify SSN syntax is correct
  • Verify the SSN exists
  • Match First and Last Name to the SSN
  • Perform deceased surpression based upon SSN

Basic Order of Operations

Single-Record Request

Batch Request

  • Put the input request together using JSON. Put up to 10 records into the request array.
  • Make sure to include your license key.
  • Send the full request to the service URL: https://namessn.melissadata.net/v4/WEB/SSN/doLookup using HTTP POST.
  • Receive the result back for all records from the input.

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.

Single-Record Request

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.

C:\>curl -X GET “https://namessn.melissadata.net/v4/WEB/SSN/doLookup?id=LICENSE_KEY&SSN=SOCIAL_SECURITY_NUMBER&full=FULL_NAME&first=FIRST_NAME&last=LAST_NAME&t=Lookups&format=json”

You can also put the URL without the "curl -X GET" command directly into your browser. This service will only return a JSON result. You can also use JSON POST to send requests.

Batch Request (JSON POST)

Header

Make sure the header includes this line.

Content-Type: application/json; charset=utf-8

Body

{
  "CustomerID": "LICENSE_KEY",
  "Records": [
    {
      "RecordID": "1",
      "SSN": "SOCIAL_SECURITY_NUMBER",
      "FirstName": "PERSON1_FIRSTNAME",
      "LastName": "PERSON1_LASTNAME",
      "FullName":"PERSON1_FULLNAME”
    },
    {
      "RecordID": "2",
      "SSN": "SOCIAL_SECURITY_NUMBER",
      "FirstName": "PERSON2_FIRSTNAME",
      "LastName": "PERSON2_LASTNAME",
      "FullName":"PERSON2_FULLNAME
    },
    …
  ]
}

Input Fields

JSON 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
RecordID N/A Unique identifier String for the current record. It is returned as sent. No
SSN ssn String value containing the Social Security Number. All hyphens are ignored when submitting the SSN Yes
FirstName first The given (first) name. No
LastName last The family (last) name. No
FullName 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. No (Recommended)
N/A format Sets the format of the response. (JSON or XML) No

Output Response

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

{
  "TransmissionResults": "string",
  "TransmissionReference": "string",
  "Version": "string",
  "TotalRecords": "string",
  "Records": [
    {
      "RecordID": "string",
      "SSN": "string",
      "IssuingState": "string",
      "Results": "string",
      "ResultsFromDataSource": "string"
    }
  ]
}

Output Fields

Response (Base Level)

Output Name Description
TransmissionResults Service Errors (SE Codes) and General Transmission Errors (GE Codes).
TransmissionReference Returned value will be the same as the input TransmissionReference to be used as a unique identifier.
Version The current revision number of SSN Verification.
TotalRecords The total number of records returned.

Record Level

Output Name Description
RecordID 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.
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 A string value with comma delimited status, error codes, and change codes for the record. For a complete list of codes, see SSN Web Service Result Codes.

Interpreting Results

The SSN Verification API and other Melissa APIs will have a Results Output. Several different Result Codes may be returned by the service in order to give you detailed information about the status of the record submitted.

It is important to understand these result codes in order for you to make a determination of good vs bad data and how you would want to use it.

The following shows you the indicators for the different results:

Code Description Quality Indicator
SN04 SSN and FULL name match our records Good Data
SN05 SSN and LAST name match our records Good Data
SN06 SSN and FIRST name match our records Good Data
SN08 SSN and Last Name, First Name Initial match our records Good Data
SN01 Invalid SSN Format Bad Data
SN02 SSN not found in our records Potentially Bad Data
SN03 SSN is on the DECEASED list Potentially Bad Data
SN07 SSN and NAME do NOT match our records Potentially Bad Data

Common Transmission Errors

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 SSN Name Match Result Code Details.