SSN Check

Run an SSN check

To run an SSN Check, you must create a check with type set to ssn_check.

This check requires the client to have an ssn attribute set.

Learn more about SSN Checks.

Check request

Attribute	Type	Description
clientId	string	The ID of the client associated with this check. (Required)
type	string	This must be set to ssn_check. (Required)

Example requests

Simple request

cURL

curl -X POST https://api.complycube.com/v1/checks \
     -H 'Authorization: <YOUR_API_KEY>' \
     -H 'Content-Type: application/json' \
     -d '{
          "clientId":"CLIENT_ID",
          "type": "ssn_check"
        }'

Node.js

const check = await complycube.check.create("CLIENT_ID", {
        type: "ssn_check"
});

Python

check = cc_api.check.create(
    'CLIENT_ID', 
    'ssn_check'
)

PHP

$result = $ccapi->checks()->create('CLIENT_ID',
                                   ['type' => 'ssn_check']);

.NET

var checkRequest = new CheckRequest {
  clientId = "CLIENT_ID",
  type = "ssn_check"
};

var check = await checkApi.CreateAsync(checkRequest);

Result object

The result object is only returned when the status of the check is complete. It has two components - outcome and breakdown.

Outcome

The outcome attribute represents the overall check result. Returned values include:

1. clear: Indicates every analysis type conducted returned a successful result.

2. attention: Indicates at least one of the analysis results requires attention.

Breakdown

The breakdown comprises the following objects:

dataVerification object

The data verification results. It has the following constituents:

• firstName: Indicates whether the first name matches authoritative sources.

• lastName: Indicates whether the last name matches authoritative sources.

• ssn: Indicates whether the SSN matches authoritative sources.

• breakdown: This object has the following constituents:

  • matchCode: the match code related to the data verification performed.

databaseAnalyss object

The database analysis results. It has the following constituents:

• governmentDatabase: Indicates whether the client’s details match authoritative government sources.

• mortalityDatabase: Indicates whether the client’s details matches mortality/deceased records.

Data verification match codes

Code	Description
full_name_match	The SSN matches both first and last names.
first_name_match	The SSN matches the first name only.
last_name_match	The SSN matches the last name only.
initial_name_match	The SSN matches the last name and first name initial.
name_mismatch	The SSN does not match the provided name. It belongs to a different individual.
deceased_match	The SSN appears on the deceased/mortality database.
ssn_not_found	The SSN was not found in the authoritative databases.
invalid_ssn_format	The SSN format used is invalid.

Sample Response

{
    "id": "688f1e2e37d2a9000202ad7f",
    "entityName": "John Doe",
    "type": "ssn_check",
    "clientId": "688f1e2e37d2a9000202ad70",
    "status": "complete",
    "result": {
        "outcome": "clear",
        "breakdown": {
            "dataVerification": {
                "firstName": "clear",
                "lastName": "clear",
                "ssn": "clear",
                "breakdown": {
                    "matchCode": "full_name_match"
                }
            },
            "databaseAnalysis": {
                "governmentDatabase": "clear",
                "mortalityDatabase": "clear"
            }
        }
    },
    "updatedAt": "2025-01-01T08:30:40.334Z",
    "createdAt": "2025-01-01T08:30:38.527Z"
}