# SSN Check

## Run an SSN check

To run an SSN Check, you must [create a check ](/documentation/api-reference/core-resources/checks/create-a-check.md)with `type` set to `ssn_check`.

This check can only be performed on a [client](/documentation/api-reference/core-resources/clients.md) of type `person`. Furthermore, it **requires** the client to have an `ssn` attribute set.

[Learn more about SSN Checks.](/documentation/product-guides/identity-verification/ssn-check.md)

## Check request

<table><thead><tr><th width="262.4">Attribute</th><th width="93">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>clientId</code></td><td>string</td><td>The ID of the client associated with this check. (<strong>Required</strong>)</td></tr><tr><td><code>type</code></td><td>string</td><td>This must be set to <code>ssn_check</code>. (<strong>Required</strong>)</td></tr></tbody></table>

## Example requests

#### Simple request

{% tabs %}
{% tab title="cURL" %}

```bash
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"
        }'
```

{% endtab %}

{% tab title="Node.js" %}

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

{% endtab %}

{% tab title="Python" %}

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

{% endtab %}

{% tab title="PHP" %}

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

{% endtab %}

{% tab title=".NET" %}

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

var check = await checkApi.CreateAsync(checkRequest);
```

{% endtab %}
{% endtabs %}

## 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](#data-verification-match-codes) 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

<table><thead><tr><th width="271.578125">Code</th><th>Description</th></tr></thead><tbody><tr><td><code>full_name_match</code></td><td>The SSN matches both first and last names.</td></tr><tr><td><code>first_name_match</code></td><td>The SSN matches the first name only.</td></tr><tr><td><code>last_name_match</code></td><td>The SSN matches the last name only.</td></tr><tr><td><code>initial_name_match</code></td><td>The SSN matches the last name and first name initial.</td></tr><tr><td><code>name_mismatch</code></td><td>The SSN does not match the provided name. It belongs to a different individual.</td></tr><tr><td><code>deceased_match</code></td><td>The SSN appears on the deceased/mortality database.</td></tr><tr><td><code>ssn_not_found</code></td><td>The SSN was not found in the authoritative databases.</td></tr><tr><td><code>invalid_ssn_format</code></td><td>The SSN format used is invalid.</td></tr></tbody></table>

## Sample Response

{% code overflow="wrap" fullWidth="false" %}

```json
{
    "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"
}
```

{% endcode %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.complycube.com/documentation/api-reference/check-types/ssn-check.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.