> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.withverifa.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.withverifa.com/_mcp/server.

# Query identity relationship graph

GET https://api.withverifa.com/api/v1/identities/{identity_id}/graph

Performs a BFS traversal of the identity relationship graph starting from
the given identity. Returns nodes (identities) and edges (relationships)
with depth metadata indicating hop distance from the root identity.

Supports filtering by relationship type, identity status, and identity exclusion
to focus queries on relevant subgraphs. Useful for programmatic fraud ring
detection, compliance audits, and network analysis.

Each node includes a `depth` field (0 = root, 1 = direct neighbor, etc.).
Each edge includes a `hops` field indicating at which depth level it was discovered.


Reference: https://docs.withverifa.com/api-reference/identities/get-identity-graph

## Authentication

- `X-API-Key` header (required) — Organization API key. Keys are prefixed with `vk_live_` (production) or `vk_sandbox_` (sandbox).

## Request

### Path parameters

- `identity_id` (string, required) — Identity ID (`idn_*`) or external reference.

### Query parameters

- `depth` (integer, optional, default: 2) — Maximum number of hops from the root identity (1-5).
- `relationship_types` (string, optional) — Comma-separated list of relationship types to include. Valid values: `same_document`, `same_name_dob`, `same_ssn`, `same_device`, `same_email`, `same_phone`, `same_address`, `same_ip`, `same_face`, `same_document_face`, `merged`, `user_linked`. If omitted, all types are included.
- `identity_statuses` (string, optional) — Comma-separated list of identity statuses to include. Valid values: `pending`, `verified`, `rejected`, `under_review`, `merged`, `redacted`. If omitted, all statuses are included. The root identity is always included regardless of this filter.
- `exclude_identity_ids` (string, optional) — Comma-separated list of identity IDs to exclude from traversal. Excluded identities will not appear as nodes and their edges will not be followed.

### Headers

- `Verifa-Version` (date, optional) — API version date string (e.g. `2026-02-01`). If omitted, the version pinned to your API key is used.
- `Key-Inflection` (enum, optional, default: snake) — Response key casing. Defaults to `snake`.
  - Allowed values: `camel`, `kebab`, `snake`

## Response

### 200

Graph traversal result.

- `root_identity_id` (string, required) — The identity from which traversal started.
- `depth` (integer, required) — The depth parameter used for this query.
- `filters` (ApiV1IdentitiesIdentityIdGraphGetResponsesContentApplicationJsonSchemaFilters, required) — The filters applied to this query.
- `graph` (ApiV1IdentitiesIdentityIdGraphGetResponsesContentApplicationJsonSchemaGraph, required)
- `stats` (ApiV1IdentitiesIdentityIdGraphGetResponsesContentApplicationJsonSchemaStats, required)

## Errors

### 401 Unauthorized Error

Missing or invalid API key.

- `error` (string, required) — Short error code.
- `status_code` (integer, required) — HTTP status code.
- `detail` (string, optional) — Human-readable error description.

### 404 Not Found Error

Resource not found.

- `error` (string, required) — Short error code.
- `status_code` (integer, required) — HTTP status code.
- `detail` (string, optional) — Human-readable error description.

### 422 Unprocessable Entity Error

Invalid filter value.

- `error` (string, required) — Short error code.
- `status_code` (integer, required) — HTTP status code.
- `detail` (string, optional) — Human-readable error description.

## Types

### ApiV1IdentitiesIdentityIdGraphGetResponsesContentApplicationJsonSchemaFilters

The filters applied to this query.

- `relationship_types` (list of string, optional, nullable)
- `identity_statuses` (list of string, optional, nullable)
- `exclude_identity_ids` (list of string, optional, nullable)

### ApiV1IdentitiesIdentityIdGraphGetResponsesContentApplicationJsonSchemaGraph

- `nodes` (list of ApiV1IdentitiesIdentityIdGraphGetResponsesContentApplicationJsonSchemaGraphNodesItems, required)
- `edges` (list of ApiV1IdentitiesIdentityIdGraphGetResponsesContentApplicationJsonSchemaGraphEdgesItems, required)

### ApiV1IdentitiesIdentityIdGraphGetResponsesContentApplicationJsonSchemaStats

- `total_nodes` (integer, required)
- `total_edges` (integer, required)

### ApiV1IdentitiesIdentityIdGraphGetResponsesContentApplicationJsonSchemaGraphNodesItems

- `id` (string, required)
- `external_ref` (string, required)
- `status` (string, required)
- `depth` (integer, required) — Hop distance from the root identity (0 = root).

### ApiV1IdentitiesIdentityIdGraphGetResponsesContentApplicationJsonSchemaGraphEdgesItems

- `source` (string, required)
- `target` (string, required)
- `type` (string, required)
- `hops` (integer, required) — The depth level at which this edge was discovered.

## Examples

**Response**

```json
{
  "root_identity_id": "idn_abc123",
  "depth": 2,
  "filters": {
    "relationship_types": [
      "string"
    ],
    "identity_statuses": [
      "string"
    ],
    "exclude_identity_ids": [
      "string"
    ]
  },
  "graph": {
    "nodes": [
      {
        "id": "idn_abc123",
        "external_ref": "user_1",
        "status": "verified",
        "depth": 0
      }
    ],
    "edges": [
      {
        "source": "idn_abc123",
        "target": "idn_def456",
        "type": "same_document",
        "hops": 1
      }
    ]
  },
  "stats": {
    "total_nodes": 5,
    "total_edges": 4
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.withverifa.com/api/v1/identities/identity_id/graph"

querystring = {"relationship_types":"same_document,same_device","identity_statuses":"verified,under_review","exclude_identity_ids":"idn_skip1,idn_skip2"}

headers = {"X-API-Key": "<apiKey>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript
const url = 'https://api.withverifa.com/api/v1/identities/identity_id/graph?relationship_types=same_document%2Csame_device&identity_statuses=verified%2Cunder_review&exclude_identity_ids=idn_skip1%2Cidn_skip2';
const options = {method: 'GET', headers: {'X-API-Key': '<apiKey>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.withverifa.com/api/v1/identities/identity_id/graph?relationship_types=same_document%2Csame_device&identity_statuses=verified%2Cunder_review&exclude_identity_ids=idn_skip1%2Cidn_skip2"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<apiKey>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.withverifa.com/api/v1/identities/identity_id/graph?relationship_types=same_document%2Csame_device&identity_statuses=verified%2Cunder_review&exclude_identity_ids=idn_skip1%2Cidn_skip2")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<apiKey>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.withverifa.com/api/v1/identities/identity_id/graph?relationship_types=same_document%2Csame_device&identity_statuses=verified%2Cunder_review&exclude_identity_ids=idn_skip1%2Cidn_skip2")
  .header("X-API-Key", "<apiKey>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.withverifa.com/api/v1/identities/identity_id/graph?relationship_types=same_document%2Csame_device&identity_statuses=verified%2Cunder_review&exclude_identity_ids=idn_skip1%2Cidn_skip2', [
  'headers' => [
    'X-API-Key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.withverifa.com/api/v1/identities/identity_id/graph?relationship_types=same_document%2Csame_device&identity_statuses=verified%2Cunder_review&exclude_identity_ids=idn_skip1%2Cidn_skip2");
var request = new RestRequest(Method.GET);
request.AddHeader("X-API-Key", "<apiKey>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["X-API-Key": "<apiKey>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.withverifa.com/api/v1/identities/identity_id/graph?relationship_types=same_document%2Csame_device&identity_statuses=verified%2Cunder_review&exclude_identity_ids=idn_skip1%2Cidn_skip2")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```