Query identity relationship 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.
Authentication
X-API-Keystring
Organization API key. Keys are prefixed with vk_live_ (production) or
vk_sandbox_ (sandbox).
Path parameters
identity_id
Identity ID (idn_*) or external reference.
Headers
Verifa-Version
API version date string (e.g. 2026-02-01). If omitted, the version
pinned to your API key is used.
Key-Inflection
Response key casing. Defaults to snake.
Allowed values:
Query parameters
depth
Maximum number of hops from the root identity (1-5).
relationship_types
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
Comma-separated list of identity statuses to include.
Valid values: created, approved, rejected, needs_review, merged, redacted.
If omitted, all statuses are included. The root identity is always included regardless of this filter.
exclude_identity_ids
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_id
The identity from which traversal started.
depth
The depth parameter used for this query.
filters
The filters applied to this query.
graph
stats
Errors
401
Unauthorized Error
404
Not Found Error
422
Unprocessable Entity Error