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

# Identity Graph

> Visualize connections between identities, devices, and documents to detect fraud networks.

Identity Graph maps relationships between verification sessions, linking shared devices, documents, phone numbers, email addresses, and facial biometrics into a network graph. Use it to uncover fraud rings, detect synthetic identities, and identify repeat offenders.

## Overview

Every verification session generates identity data points -- device fingerprints, phone numbers, email addresses, facial embeddings, and document numbers. Identity Graph connects sessions that share any of these data points, building a network of linked identities over time.

## Link Types

Verilock detects the following relationship types between sessions:

| Link Type         | Description                                                      |
| ----------------- | ---------------------------------------------------------------- |
| `same_device`     | Sessions from the same device fingerprint                        |
| `same_face`       | Face match detected across sessions (above similarity threshold) |
| `same_document`   | Same document number used in multiple sessions                   |
| `same_phone`      | Same phone number across sessions                                |
| `same_email`      | Same email address across sessions                               |
| `same_ip`         | Sessions from the same IP address                                |
| `same_address`    | Matching extracted address across sessions                       |
| `name_similarity` | High name similarity with different documents                    |

## Cluster Detection

When multiple sessions share links, they form clusters. Verilock automatically identifies clusters and assigns a risk level:

| Cluster Size    | Risk Level | Description                                                      |
| --------------- | ---------- | ---------------------------------------------------------------- |
| 2 -- 3 sessions | **Low**    | May be legitimate (e.g., re-verification, family members)        |
| 4 -- 7 sessions | **Medium** | Worth investigation -- possible identity farming                 |
| 8+ sessions     | **High**   | Strong indicator of a fraud ring or synthetic identity operation |

Clusters with mixed link types (e.g., same device AND same face with different documents) receive elevated risk scores.

## Dashboard Visualization

Access Identity Graph from **Dashboard > Intelligence > Identity Graph**:

* **Graph view** -- interactive node-and-edge visualization showing connections between sessions
* **Cluster list** -- all detected clusters sorted by risk level and size
* **Session drilldown** -- click any node to view the full session detail
* **Link filtering** -- filter by link type to focus on specific relationship patterns
* **Time range** -- narrow the graph to sessions within a date range

## API: Get Identity Graph

Retrieve the identity graph for a specific session:

```bash theme={null}
GET /v1/sessions/{id}/identity-graph
```

```json theme={null}
{
  "session_id": "ses_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "cluster_id": "cluster_x9y8z7",
  "cluster_size": 4,
  "cluster_risk_level": "medium",
  "links": [
    {
      "linked_session_id": "ses_f6e5d4c3-b2a1-0987-fedc-ba9876543210",
      "link_type": "same_device",
      "confidence": 0.98,
      "detected_at": "2026-03-18T10:00:00Z"
    },
    {
      "linked_session_id": "ses_11223344-5566-7788-99aa-bbccddeeff00",
      "link_type": "same_face",
      "confidence": 0.91,
      "detected_at": "2026-03-17T15:30:00Z"
    },
    {
      "linked_session_id": "ses_aabbccdd-eeff-0011-2233-445566778899",
      "link_type": "same_phone",
      "confidence": 1.0,
      "detected_at": "2026-03-16T08:00:00Z"
    }
  ],
  "nodes": [
    {
      "session_id": "ses_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "person_name": "John Smith",
      "status": "approved",
      "created_at": "2026-03-18T09:45:00Z"
    },
    {
      "session_id": "ses_f6e5d4c3-b2a1-0987-fedc-ba9876543210",
      "person_name": "Jon Smyth",
      "status": "declined",
      "created_at": "2026-03-15T14:00:00Z"
    }
  ]
}
```

## Response Fields

| Field                       | Type    | Description                            |
| --------------------------- | ------- | -------------------------------------- |
| `session_id`                | string  | The queried session ID                 |
| `cluster_id`                | string  | Identifier for the linked cluster      |
| `cluster_size`              | integer | Number of sessions in the cluster      |
| `cluster_risk_level`        | string  | `low`, `medium`, or `high`             |
| `links`                     | array   | Connections to other sessions          |
| `links[].linked_session_id` | string  | ID of the linked session               |
| `links[].link_type`         | string  | Type of relationship                   |
| `links[].confidence`        | number  | Link confidence score (0-1)            |
| `nodes`                     | array   | Summary of all sessions in the cluster |

## List Clusters

Retrieve all detected clusters:

```bash theme={null}
GET /v1/identity-graph/clusters?risk_level=high&min_size=4
```

| Parameter    | Type    | Default | Description                          |
| ------------ | ------- | ------- | ------------------------------------ |
| `risk_level` | string  | all     | Filter by `low`, `medium`, or `high` |
| `min_size`   | integer | `2`     | Minimum cluster size                 |
| `page`       | integer | `1`     | Page number                          |
| `per_page`   | integer | `20`    | Results per page                     |

<Warning>
  Identity Graph data requires at least two sessions with shared data points. Single isolated sessions will not appear in the graph.
</Warning>

<Tip>
  Set up orchestration rules to automatically flag or decline sessions that belong to high-risk clusters with 8 or more linked identities.
</Tip>