> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verisoul.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Identity Intelligence

Identity Intelligence extends the Email Intelligence API with deeper identity analysis. When enabled, Verisoul pulls in additional data sources to build a picture of the person behind an email address — their online presence, connected identities, and whether provided claims (name, phone, country) match the data.

This is particularly valuable for:

* **Account creation** — verify that the person signing up is real and matches the information they provided
* **High-value transactions** — add an extra layer of identity confidence before approving a purchase or transfer
* **KYC/onboarding workflows** — cross-reference claims against independent data sources

## How to Enable It

Set `identity_intelligence: true` in your request. In batch mode, this applies to all emails in the batch.

**Single email:**

```json theme={null}
{
  "email": "john.doe@example.com",
  "identity_intelligence": true,
  "claims": {
    "name": { "first": "John", "last": "Doe" },
    "phone": "+15550109988",
    "country": "US"
  }
}
```

**Batch:**

```json theme={null}
{
  "emails": [
    {
      "email": "john.doe@example.com",
      "claims": {
        "name": { "first": "John", "last": "Doe" },
        "country": "US"
      }
    },
    {
      "email": "jane.smith@company.com",
      "claims": {
        "name": { "first": "Jane", "last": "Smith" },
        "phone": "+14155551234"
      }
    }
  ],
  "identity_intelligence": true
}
```

In batch mode, each email has its own `claims`, so you can verify different identities in a single request.

## Claims

Claims are pieces of information your customer has provided that you want to verify against Verisoul's identity data. All claims are optional.

| Claim        | Type   | Description                                  |
| ------------ | ------ | -------------------------------------------- |
| `name.first` | string | Customer's first name                        |
| `name.last`  | string | Customer's last name                         |
| `phone`      | string | Phone number (E.164 format recommended)      |
| `country`    | string | Two-letter country code (ISO 3166-1 alpha-2) |

When claims are provided, Verisoul matches them against identity data linked to the email and returns match results.

## What You Get Back

When `identity_intelligence` is enabled, the webhook payload includes an additional `identity_intelligence` section inside `data.result`:

```json theme={null}
{
  "identity_intelligence": {
    "match_risk_score": -0.4,
    "online_accounts_count": 5,
    "online_accounts": ["google", "linkedin", "github", "facebook", "instagram"],
    "connected_names": ["John Doe"],
    "connected_phones": ["+1555*******"],
    "claim_matches": {
      "name": "match",
      "phone": "skipped",
      "country": "match"
    }
  }
}
```

### Fields

| Field                   | Type      | Description                                                                                                                                                          |
| ----------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `match_risk_score`      | number    | Composite identity risk score from -1 (verified identity) to 1 (ghost / no identity footprint). Factors in online presence, claim matches, and identity consistency. |
| `online_accounts_count` | number    | Number of platforms where the email is registered.                                                                                                                   |
| `online_accounts`       | string\[] | Platforms where the email is registered (e.g., `google`, `facebook`, `linkedin`, `twitter`, `github`). A rich online presence is a strong trust signal.              |
| `connected_names`       | string\[] | Names associated with this email across data sources.                                                                                                                |
| `connected_phones`      | string\[] | Phone numbers linked to this email.                                                                                                                                  |
| `claim_matches`         | object    | Results of matching each submitted claim against identity data.                                                                                                      |

### Claim Match Values

Each claim is matched independently and returns one of:

| Value           | Meaning                                                                |
| --------------- | ---------------------------------------------------------------------- |
| `match`         | The claim matches identity data linked to the email                    |
| `partial_match` | Partial overlap (e.g., first name matches but last name differs)       |
| `no_match`      | The claim does not match any known identity data                       |
| `skipped`       | No claim was provided for this field, or identity data was unavailable |

## How It Affects the Score

When Identity Intelligence is enabled, the identity data directly influences the overall `risk_score`:

* **Identity Match** — a strong name/phone match pushes the score toward trust, while mismatches or ghost identities push toward risk.
* **Online presence** — emails registered on many legitimate platforms (Google, LinkedIn, Facebook, etc.) are more likely to belong to real people, which is a strong trust signal.

A verified identity match can pull an otherwise neutral email into the "trusted" range, while a complete identity mismatch can significantly increase risk.

## Without Identity Intelligence

If `identity_intelligence` is not set or is `false`, the webhook payload will not include the `identity_intelligence` section. Identity-related signals will not factor into the overall risk score.

The Email Intelligence API still provides full risk scoring, deliverability, domain classification, and breach intelligence without Identity Intelligence enabled.