Skip to main content
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 systemGood vendor_data values
Internal user databaseuser_1234, uuid-v4 of the user
Customer-facing IDCUST-2026-00042, hashed email
Multi-tenant SaaStenant_acme:user_1234
B2B platformcompany-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:
  1. Didit looks up the entity in your application with that vendor_data.
  2. If it exists, the new object is linked to that entity.
  3. 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:
ScopeUniqueness guarantee
Within one applicationvendor_data is unique per entity type (User and Business are separate namespaces)
Across applications in your organizationvendor_data is not shared — the same value in two apps refers to two different entities
Across organizationsNot 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

RuleWhy
Choose one canonical identifier per entity and never change itChanges 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 stableDidit does not normalize case
Keep vendor_data length under 128 charsFits comfortably in database indexes
Never expose raw PIIvendor_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.