Vendor Data Linking

vendor_data is the identifier you supply on every session and transaction to link it to a User or Business entity. It is the single most important field for entity aggregation — get it right and every downstream feature (profile history, transaction monitoring, blocklist enforcement, ongoing AML) works seamlessly.

What it is

vendor_data is a string you choose. Didit treats it as an opaque identifier and does not interpret its contents. Typical values:

Your system	Good `vendor_data` values
Internal user database	`user_1234`, `uuid-v4` of the user
Customer-facing ID	`CUST-2026-00042`, hashed email
Multi-tenant SaaS	`tenant_acme:user_1234`
B2B platform	`company-hq-global`, `tax-id-US-123456789`

Do not put PII (emails, phone numbers, raw tax IDs) directly in vendor_data. Hash or prefix them. vendor_data appears in webhook payloads and is persisted indefinitely while the entity exists.

How it binds things together

When you submit a session or transaction with a vendor_data value:

Didit looks up the entity in your application with that vendor_data.
If it exists, the new object is linked to that entity.
If it does not exist, Didit creates the entity (with status: ACTIVE) and links the new object.

This is true for:

POST /v3/session/ — KYC and Business Verification (KYB) sessions
POST /v3/transactions/ — transactions (for both applicant and counterparty)
The applicant.vendor_data / counterparty.vendor_data fields inside transaction payloads

Uniqueness and scope

vendor_data is unique per application, not globally across Didit:

Scope	Uniqueness guarantee
Within one application	`vendor_data` is unique per entity type (User and Business are separate namespaces)
Across applications in your organization	`vendor_data` is not shared — the same value in two apps refers to two different entities
Across organizations	Not shared — every organization has its own entity tables

This means you can use the same vendor_data in a staging app and a production app without collisions, and you can have a User user-42 and a Business user-42 without collision (though this is discouraged for clarity).

What happens if you omit `vendor_data`

You can create a session without vendor_data. In that case:

No entity is created for the session.
The session is orphaned — it won’t appear in any User or Business profile.
You cannot later look up the session by vendor_data — only by session_id.

Use this pattern only for anonymous or one-off verifications where no entity aggregation is needed. For every integration that involves re-verification, transactions, or ongoing monitoring, always provide vendor_data.

Example: pre-create an entity, then run sessions

# 1. Pre-create the User with initial metadata
curl -X POST https://verification.didit.me/v3/users/create/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data": "user-42",
    "display_name": "Jane Doe",
    "metadata": { "tier": "premium", "signup_date": "2026-04-01" }
  }'

# 2. Create a User Verification (KYC) session for the same user
curl -X POST https://verification.didit.me/v3/session/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "wf_kyc_standard",
    "vendor_data": "user-42"
  }'

# 3. Later, submit a transaction tied to the same user
curl -X POST https://verification.didit.me/v3/transactions/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "txn_id": "tx-0001",
    "direction": "OUTBOUND",
    "amount": "500.00",
    "currency": "EUR",
    "applicant": { "vendor_data": "user-42" },
    "counterparty": { "name": "Acme Corp" }
  }'

All three calls are linked to the same User entity. When you later GET /v3/users/user-42/, you’ll see the session count, approved/declined counters, linked transactions, and latest profile data.

Migrating external IDs

If you’re adopting Didit after an existing KYC vendor, pass your existing stable user IDs as vendor_data from day one. This makes it easy to:

Reconcile Didit data with your internal database.
Bulk-load historical users via console CSV import before running any sessions.
Preserve relationships when you later migrate to Didit for transaction monitoring.

Rules, conventions, and best practices

Rule	Why
Choose one canonical identifier per entity and never change it	Changes create a new entity and orphan history
Prefix `vendor_data` values by entity type (`user_...`, `biz_...`)	Prevents accidental collisions between namespaces in your own code
Keep `vendor_data` case-sensitive stable	Didit does not normalize case
Keep `vendor_data` length under 128 chars	Fits comfortably in database indexes
Never expose raw PII	`vendor_data` appears in webhooks, audit logs, and API responses

Next steps

Users overview

Deep dive on User entities and operations.

Businesses overview

Deep dive on Business entities and operations.

Create session

Start a verification for a vendor_data.

Create transaction

Submit a transaction linked to an entity.

Overview

Pricing

Workflows & Verification

Review & Operations

Entities (Users & Businesses)

Settings & Customization

Security & Compliance

Resources

What it is

How it binds things together

Uniqueness and scope

What happens if you omit `vendor_data`

Example: pre-create an entity, then run sessions

Migrating external IDs

Rules, conventions, and best practices

Next steps

Users overview

Businesses overview

Create session

Create transaction

​What it is

​How it binds things together

​Uniqueness and scope

​What happens if you omit vendor_data

​Example: pre-create an entity, then run sessions

​Migrating external IDs

​Rules, conventions, and best practices

​Next steps

Users overview

Businesses overview

Create session

Create transaction

What it is

How it binds things together

Uniqueness and scope

What happens if you omit `vendor_data`

Example: pre-create an entity, then run sessions

Migrating external IDs

Rules, conventions, and best practices

Next steps