# SSN Check

## Run an SSN check

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

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

[Learn more about SSN Checks.](https://app.gitbook.com/s/KyFKMqftsmT6qln9zo5y/identity-verification/ssn-check)

## 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 %}