For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
  • Getting Started
    • Introduction
    • How Verifa Works
    • Quickstart
    • Choosing an Integration Method
  • Use Cases
    • KYC Onboarding
    • Age Verification
    • AML Compliance
    • Fraud Prevention
    • Marketplace Trust & Safety
  • Core Concepts
    • Overview
    • Sessions
    • Verifications & Checks
    • Workflows
    • Identities
    • Cases
    • Screening & Reports
    • Lists
  • Integration Guides
    • Overview
    • JavaScript SDK
    • Web Capture Flow
    • API-Only Integration
    • Mobile SDK
    • Webhooks Guide
    • MCP Server
    • Migrating from Persona
  • API Details
    • Overview
    • Authentication
    • Pagination
    • Rate Limiting
    • Versioning
    • Errors
    • Webhooks
    • Idempotency
    • Key Inflection
    • Data Access
    • Data Retention
  • Tutorials
    • Creating Your First Verification Session
    • Creating a Workflow
    • Receiving Webhooks & Validating Signatures
    • Handling Webhook Events
    • Custom Document Types & AI Extraction
  • Best Practices
    • Testing
    • Preventing Duplicates
    • Fraud Signals
    • Changelog
  • API Reference
      • GETList identities
      • POSTCreate an identity
      • GETGet an identity
      • PATCHUpdate an identity
      • DELRedact an identity
      • GETExport identity data (GDPR Art. 15 DSAR)
      • POSTSearch identities
      • GETList identity sessions
      • GETGet identity audit log
      • POSTAdd a tag
      • POSTRemove a tag
      • POSTSet tags
      • POSTPreview identity merge
      • POSTMerge identities
      • POSTArchive an identity
      • POSTRestore an archived identity
      • POSTPause continuous monitoring for an identity
      • POSTResume continuous monitoring for an identity
      • POSTAdvanced identity search
      • GETGet custom field values
      • PATCHSet custom field values
      • GETList identity relationships
      • POSTCreate an identity relationship
      • DELDelete an identity relationship
      • GETQuery identity relationship graph
      • GETFind cross-session image similarity matches
      • GETGet monitored lists for an identity
      • POSTAdd lists to identity monitoring
      • PUTReplace monitored lists for an identity
API ReferenceIdentities

Query identity relationship graph

GET
https://devapi.withverifa.com/api/v1/identities/:identity_id/graph
GET
/api/v1/identities/:identity_id/graph
$curl -G https://devapi.withverifa.com/api/v1/identities/identity_id/graph \
>     -H "X-API-Key: <apiKey>" \
>     --data-urlencode relationship_types=same_document,same_device \
>     --data-urlencode identity_statuses=verified,under_review \
>     --data-urlencode exclude_identity_ids=idn_skip1,idn_skip2
1{
2  "root_identity_id": "idn_abc123",
3  "depth": 2,
4  "filters": {
5    "relationship_types": [
6      "string"
7    ],
8    "identity_statuses": [
9      "string"
10    ],
11    "exclude_identity_ids": [
12      "string"
13    ]
14  },
15  "graph": {
16    "nodes": [
17      {
18        "id": "idn_abc123",
19        "external_ref": "user_1",
20        "status": "verified",
21        "depth": 0
22      }
23    ],
24    "edges": [
25      {
26        "source": "idn_abc123",
27        "target": "idn_def456",
28        "type": "same_document",
29        "hops": 1
30      }
31    ]
32  },
33  "stats": {
34    "total_nodes": 5,
35    "total_edges": 4
36  }
37}
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.
Was this page helpful?
Previous

Find cross-session image similarity matches

Next
Built with

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.

Authentication

X-API-Keystring

Organization API key. Keys are prefixed with vk_live_ (production) or vk_sandbox_ (sandbox).

Path parameters

identity_idstringRequired

Identity ID (idn_*) or external reference.

Headers

Verifa-VersiondateOptional

API version date string (e.g. 2026-02-01). If omitted, the version pinned to your API key is used.

Key-InflectionenumOptionalDefaults to snake

Response key casing. Defaults to snake.

Allowed values:

Query parameters

depthintegerOptional1-5Defaults to 2

Maximum number of hops from the root identity (1-5).

relationship_typesstringOptional
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_statusesstringOptional

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_idsstringOptional

Comma-separated list of identity IDs to exclude from traversal. Excluded identities will not appear as nodes and their edges will not be followed.

Response

Graph traversal result.
root_identity_idstring
The identity from which traversal started.
depthinteger
The depth parameter used for this query.
filtersobject
The filters applied to this query.
graphobject
statsobject

Errors

401
Unauthorized Error
404
Not Found Error
422
Unprocessable Entity Error

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.