Social Security Number Verification API

This document highlights the details of the Social Security Number Verification API.

API Description

Objective

The SSN Verification API checks the information on a Social Security Number (SSN) and confirms if it matches the official data maintained by the issuing authority. The API confirms SSN ownership, detect mismatches or invalid cases, and support fraud prevention and compliance checks.

Info

• A Social Security number (SSN) is a unique nine-digit identifier for U.S. citizens, permanent residents, and eligible workers, issued by the Social Security Administration (SSA).
• Social Security Numbers issued by U.S. jurisdictions are commonly used for identity verification but can be counterfeit or altered. Verifying their authenticity is essential for accurate identification.

Input	Output
User details including: First name Last name SSN	The verification results indicate whether the user's name and SSN fully match, partially match, or do not match the official records, confirming if the SSN is valid, active, and correctly associated.

API URL

https://usa.thomas.hyperverge.co/v1/ssnVerification

API Endpoint

ssnVerification

Overview

The Social Security Number Verification API is RESTful and uses standard HTTP verbs and status codes. The requests are in form-data format and responses are in JSON format.

Authentication

You need a unique pair of application ID ( appId ) and application key (appKey) from HyperVerge to verify your identity for accessing the API.

Parameter	Mandatory or Optional	Description	Allowed Values
content-type	Mandatory	This parameter defines the media type for the request payload	application/json
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
transactionId	Mandatory	A unique identifier for tracking a user journey	This should be both unique and easily associated with the user's journey in your application(s)

API Request Details

Method - POST

Headers

Parameter	Mandatory or Optional	Description	Valid Values
content-type	Mandatory	This parameter defines the media type for the request payload	application/json
appId	Mandatory	The application ID shared by HyperVerge	Not Applicable - this is a unique value
appKey	Mandatory	The application key shared by HyperVerge	Not Applicable - this is a unique value
transactionId	Optional	The unique ID for the customer journey	Not Applicable

Inputs

The following table lists the parameters required for the Social Security Number Verification API's request body:

Parameter	Mandatory or Optional	Description	Allowed Values	Default Value
firstName	Mandatory	The first name of the user	Not Applicable	Not Applicable
lastName	Mandatory	The last name of the user	Not Applicable	Not Applicable
ssn	Mandatory	The SSN of the user	A nine-digit number formatted as XXX-XX-XXXX. For example, 123-45-6789	Not Applicable

Request

The following code snippet demonstrates a standard curl request for the Social Security Number Verification API:

curl --location --request POST 'https://usa.thomas.hyperverge.co/v1/ssnVerification' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "firstName": "<Enter_the_first_name>",
    "lastName": "<Enter_the_last_name>",
    "ssn": "<Enter_the_SSN>"
}'

Success Responses

The following code snippets demonstrate success responses from the Social Security Number Verification API:

Complete Match

{
    "status": "success",
    "statusCode": "200",
    "result": {
        "details": {
            "ssnMatch": "fullMatch"
        },
        "summary": {
            "action": "pass",
            "details": []
        }
    }
}

Complete Mismatch

{
    "status": "success",
    "statusCode": "200",
    "result": {
        "details": {
            "ssnMatch": "noMatch"
        },
        "summary": {
            "action": "pass",
            "details": []
        }
    }
}

Partial Match

{
    "status": "success",
    "statusCode": "200",
    "result": {
        "details": {
            "ssnMatch": "partialMatch"
        },
        "summary": {
            "action": "pass",
            "details": []
        }
    }
}

Deceased SSN

{
    "status": "success",
    "statusCode": "200",
    "result": {
        "details": {
            "ssnMatch": "deceased"
        },
        "summary": {
            "action": "pass",
            "details": []
        }
    }
}

Invalid Format

{
    "status": "success",
    "statusCode": "200",
    "result": {
        "details": {
            "ssnMatch": "invalidFormat"
        },
        "summary": {
            "action": "pass",
            "details": []
        }
    }
}

SSN Not Found

{
    "status": "success",
    "statusCode": "200",
    "result": {
        "details": {
            "ssnMatch": "notFound"
        },
        "summary": {
            "action": "pass",
            "details": []
        }
    }
}

Success Response Details

The following table outlines the details of the success response from the Social Security Number Verification API:

Parameter	Type	Description
status	string	Indicates the status of the request
statusCode	string	The HTTP status code for the request
result	object	The object containing the result details
details	object	Contains details about the SSN match result
ssnMatch	string	Indicates the verification result for the SSN and name combination. Returns "fullMatch" for complete matches, "partialMatch" for partial matches, "noMatch" for no matches, "deceased" for SSNs that are no longer active, "invalidFormat" for SSNs with incorrect length or format, and "notFound" when the SSN is valid but the name doesn't match the provided details
summary	object	Provides a summary of the verification result
action	string	Represents the action based on the verification result, such as pass or fail
details	array	An array containing additional details about the summary, if available

Error Responses

The following are the error responses for the Social Security Number Verification API:

Input Validation Error- Missing SSN

{
    "status": "failure",
    "statusCode": "400",
    "error": "ssn is required"
}

Input Validation Error- First Name is Empty

{
    "status": "failure",
    "statusCode": "400",
    "error": "firstName is required"
}

Input Validation Error- Last Name is Empty

{
    "status": "failure",
    "statusCode": "400",
    "error": "lastName is required"
}

Missing/Invalid Credentials

{
   "message": "Missing/Invalid credentials",
   "statusCode": 401,
   "status": "failure"
}

Invalid First Name Characters

{
    "status": "failure",
    "statusCode": "400",
    "error": "Please provide valid firstName"
}

Invalid Last Name Characters

{
    "status": "failure",
    "statusCode": "400",
    "error": "Please provide valid lastName"
}

Invalid SSN Characters

{
    "status": "failure",
    "statusCode": "400",
    "error": "Please provide valid SSN"
}

Error Response Details

A failure or error response from the API contains a failure status with a relevant status code and error message. The following table lists all error responses.

Status Code	Error Message	Error Description
400	ssn is required	The SSN field is missing in the request body
400	firstName is required	The first name is empty in the request body
400	lastName is required	The last name is empty in the request body
400	Please provide valid firstName	The first name contains invalid characters
400	Please provide valid lastName	The last name contains invalid characters
400	Please provide valid SSN	The SSN contains special characters or has an invalid format
401	Missing/Invalid credentials	The request is either missing the mandatory appId and appKey combination or has invalid values
500	Internal Server Error	Please check the request headers or contact the HyperVerge team for resolution