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 at sales@melissa.com or 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 a SSN with a name#
Check if the Social Security Number is within the acceptable range, and match against the First and Last Name
Try It Now#
curl -X GET "https://namessn.melissadata.net/v4/web/SSN/doLookup?\
&id={{customerId}}\
&ssn=111222333\
&full=John%20Doe\
&first=John\
&last=Doe\
&format=json"\
curl -X POST "https://namessn.melissadata.net/v4/web/SSN/doLookup" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"CustomerID": {{customerId}},
"Records": [
{
"RecordID": "1",
"SSN": "111222333",
"FirstName": "John",
"LastName": "Doe",
"FullName":"John Doe"
}
]
}'
Request Parameters#
Code |
Description |
|---|---|
t |
This is a string value that serves as a unique identifier for this set of records. It is returned as sent. |
id |
This is a string value containing the License Key issued to the customer by Melissa Data for the web service. |
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. |
first |
The given (first) name. |
last |
The family (last) 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. |
format |
Sets the format of the response. |
Code |
Description |
|---|---|
t |
This is a string value that serves as a unique identifier for this set of records. It is returned as sent. |
id |
This is a string value containing the License Key issued to the customer by Melissa Data for the web service. |
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. |
first |
The given (first) name. |
last |
The family (last) 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. |
format |
Sets the format of the response. |
Headers#
Content-Type: application/json
Accept: application/json
Content-Type: application/json
Accept: application/json
Response#
{
"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 |
Optional. Serves as a unique request identifier. |
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 Data’s 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.
Record Level Result Codes#
Code |
Short Description |
Long Description |
|---|---|---|
SN - Security Number Codes |
||
|
Invalid SSN Format or Number |
The SSN had too many or too few digits. |
|
SSN Not Found in our Records |
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. |
|
SSN is on the DECEASED List |
The SSN was found on the deceased list – no matching was made to the input name as this number is no longer active. |
|
SSN and FULL Name Match our Records |
The SSN matched to both the first and last name of the input record. |
|
SSN and LAST Name Match our Records |
The SSN and last name match, but the first names did not match. |
|
SSN and FIRST Name Match our Records |
The SSN and the first name matched, and first name could be female. |
|
SSN and NAME do NOT Match our Records |
The SSN belongs to a name different from the one that was input. |
|
SSN and LAST Name, First Name Initial Match our Records |
The SSN number matched the last name, but was unable to fully match the first name as only an initial was provided. |
SE - Transmission Service Error |
||
|
Cloud Service Internal Error |
The cloud service experienced an internal error. |
GE - General Transmission Error |
||
|
Empty Request Structure |
The SOAP, JSON, or XML request structure is empty. Not to be confused with the GE01 GeoCode result code. |
|
Empty Request Record Structure |
The SOAP, JSON, or XML request record structure is empty. Not to be confused with the GE02 GeoCode result code. |
|
Records Per Request Exceeded |
The counted records sent more than the number of records allowed per request. |
|
Empty License Key |
The License Key is empty. |
|
Invalid License Key |
The License Key is invalid. |
|
Disabled License Key |
The License Key is disabled. |
|
Invalid Request |
The SOAP, JSON, or XML request is invalid. |
|
Product/Level Not Enabled |
The License Key is invalid for this product or level. |
|
Customer Does Not Exist |
The Customer ID is not in our system. |
|
Customer License Disabled |
The encrypted license is on the ban list. |
|
Customer Disabled |
The Customer ID is disabled. |
|
IP Blacklisted |
The IP Address is on the global ban list. |
|
IP Not Whitelisted |
The IP Address is not on the customer’s whitelist. |
|
Out of Credits |
The account has ran out of credits. Add more credits to continue using the service. |