Match Name and SSN

Implementation Guide

Introduction

Please see the Overview Page to review account setup, authentication instructions, and other common API features.

The Searchbug® SSN and Name Match API helps businesses verify if an SSN provided by employees, customers, or 1099 contractors matches the name associated with that SSN. This API helps prevent fraudulent claims and incorrect reporting, which could result in penalties imposed by the IRS.

For added flexibility, Searchbug lets you match SSNs in two ways: 1) using the full 9-digit SSN or 2) only the last 4 digits.

If the name and SSN matches, the API returns names and aliases associated with the SSN, recorded date of birth, and cities lived. SSN status returned: active or deceased, and when and where the SSN was issued. This API is only available for customers with the SSN Verification Add-on.

Are you curious how to easily integrate this into your existing systems? This API Documentation is here to guide you!

This guide includes:

  1. Sending Request
  2. Receiving Results

Sending Request

The request should be sent to Searchbug using the following URL using the POST method:

https://data.searchbug.com/api/search.aspx

Search Parameters

You can submit your request via:

  • POST Header: Parameters sent as custom headers
  • POST Body: Parameters sent as form-data
Parameter Value Example Description
CO_CODE 12345678 Required. Your account number
PASS H4z865i3$1 API Key or account password (not needed if using Bearer Token)
TYPE api_ssnn Required. Use api_ssnn for this API
SSN 123-45-6789 9-digit Social Security Number in any format (e.g. “123-45-6789” or “123456789”). Restricted Access Add-On is required.

Partial SSN searches by the last 4 digits is also supported. First and Last Name are required for partial SSN searches. Restricted Access Add-On is required.
FNAME Mark First name
LNAME Baker Last name
FORMAT XML Optional. The default is XML. To get results in JSON format, pass FORMAT=JSON

Receiving Results

Example of MATCH in XML format (Full 9-digit SSN + Last Name Search): 


<results>
    <mySSN_MESSAGE/>
    <mySSNformated>123-45-6789</mySSNformated>
    <match>1</match>
    <myMATCH>MATCH</myMATCH>
    <ssnVALID/>
    <ssnSTATE>CALIFORNIA</ssnSTATE>
    <ssnYear>1976</ssnYear>
    <ssnALERT/>
    <ssnNameALERT/>
    <ssnSSDI/>
    <ssnAGE_ISSUED/>
    <ssnSTATUS/>
    <ssnFNAME>Mark</ssnFNAME>
    <ssnMNAME>A</ssnMNAME>
    <ssnLNAME>Baker</ssnLNAME>
    <ssnNAMES>
        <NAME>Mark Albert Baker</NAME>
        <NAME>Mark A Baker</NAME>
    </ssnNAMES>
    <ssnDOB>
        <DOB>11/08/1976</DOB>
    </ssnDOB>
    <ssnCityState>
        <CityState>Saratoga, CA</CityState>
        <CityState>San Jose, CA</CityState>
        <CityState>Campbell, CA</CityState>
    </ssnCityState>
</results>

Example of MATCH in JSON format (Full 9-digit SSN + Last Name Search): 

                             

{
    Status: "Success",
    - Data: {
        mySSN_MESSAGE: null,
        mySSNformated: "123-45-6789",
        match: "2",
        myMATCH: "MATCH",
        ssnVALID: null,
        ssnSTATE: "NEW YORK",
        ssnYear: "1991-1992",
        ssnALERT: null,
        ssnNameALERT: null,
        ssnSSDI: null,
        ssnAGE ISSUED: null,
        ssnSTATUS: null,
        ssnFNAME: "David", 
        ssnMNAME: "p",
        ssnLNAME: "Baker",
        - ssnNAMES: {
            - NAME: [
                "David P Baker",
                "David Baker",    
                "David Peter Baker"
            ]
        },
        - ssnDOB: {
            DOB: "12/04/1991"
        },
        - ssnCityState: {
            - CityState: [
                "New York, NY", 
                "Smithtown, NY", 
                "Rego Park, NY",
            ]
        }
    },
    Error: null
}

Example of MATCH in JSON format (Partial last 4-digit SSN + First Name + Last Name Search): 

                             
    
{
    "results": { 
        "mySSN_MESSAGE": "",
        "mySSNformated": 7890, 
        "match": 1,
        "myMATCH": "MATCH", 
        "ssnVALID": "",
        "ssnSTATE": "California",
        "ssnYear": 1968,
        "ssnALERT": "",
        "ssnNameALERT":  "",
        "ssnSSDI": "",
        "ssnAGE ISSUED": "",
        "ssnSTATUS": "",
        "ssnFNAME": "David",
        "ssnMNAME": "",
        "ssnLNAME": "Baker",
        "ssnNAMES": {
            "NAME": [
            "David Baker",
            "David P Baker",
            "David Peter Baker"
            ]
        },
        "ssnDOB": {
            "DOB": "5/16/1968"
        },
        "ssnCityState": {
        "CityState": "IRVINE, CA"
        }
    }
}

Example of NO MATCH with valid SSN: 

                                             
<results>
    <mySSN_MESSAGE/>
    <mySSNformated>123-45-6789</mySSNformated>
    <match>-1</match>
    <myMATCH>DO NOT Match</myMATCH>
    <ssnVALID/>
    <ssnSTATE>VIRGINIA</ssnSTATE>
    <ssnYear>1976</ssnYear>
    <ssnALERT/>
    <ssnNameALERT/>
    <ssnSSDI/>
    <ssnAGE_ISSUED/>
    <ssnSTATUS/>
    <ssnFNAME/>
    <ssnMNAME/>
    <ssnLNAME/>
    <ssnNAMES/>
    <ssnDOB/>
    <ssnCityState/>
</results>

Example of NO MATCH with INVALID SSN: 

                         
<results>    
    <mySSN_MESSAGE>No Records are Found for this SSN</mySSN_MESSAGE>
    <mySSNformated>999-91-2345</mySSNformated>
    <match>--1</match>
    <myMATCH>DO NOT Match</myMATCH>
    <ssnVALID/>
    <ssnSTATE/>
    <ssnYear/>
    <ssnALERT/>
    <ssnNameALERT/>
    <ssnSSDI/>
    <ssnAGE_ISSUED/>
    <ssnSTATUS/>
    <ssnFNAME/>
    <ssnMNAME/>
    <ssnLNAME/>
    <ssnNAMES/>
    <ssnDOB/>
    <ssnCityState/>
</results>

For further technical details and customer support, please chat with us, email us, or call us (800) 990-2939.

For sales and pricing information please contact sales@searchbug.com.