> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# vendor_data連携：自社IDをエンティティに紐付け

> vendor_data識別子で自社システムとDiditを連携し、セッション、取引、ユーザー・企業エンティティを1つのプロファイルに紐付けます。API呼び出しごとの従量課金です。

Vendor Dataを使用した紐付けプロンプト
プロンプトをクリップボードにコピー

<pre>
  \`\`\`\`# Goal — link every session, transaction, and entity together using `vendor_data`

  `vendor_data` is the string identifier you choose and pass on every API call to bind it to a persistent [User](https://docs.didit.me/entities/users/overview.md) or [Business](https://docs.didit.me/entities/businesses/overview.md) entity. Get this right once and you never have to re-key history afterwards.

  ## Rules

  * `vendor_data` is **opaque** to Didit. Use your stable internal customer id.
  * Choose one canonical id per entity and never change it. Changing it orphans history under a new entity.
  * Prefix by entity type when convenient (`user_...`, `biz_...`) to avoid collisions in your own code.
  * Keep it under 128 chars, case-sensitive stable. Hard limit is 2000 bytes (UTF-8 encoded) - anything over that is rejected with a 400 rather than accepted.
  * **Never put raw PII in it** — it surfaces in webhooks, logs, and API responses.
  * Uniqueness is per application × entity type. User `user-42` and Business `user-42` are different entities (but don't do this).

  ## Where it goes

  | API | Field |
  | - | - |
  | `POST /v3/session/` | top-level `vendor_data` (KYC and KYB) |
  | `POST /v3/transactions/` | top-level `vendor_data` and `applicant.vendor_data` / `counterparty.vendor_data` |
  | `POST /v3/users/create/` / `POST /v3/businesses/create/` | `vendor_data` |
  | `GET /v3/sessions?vendor_data=...` | query param to retrieve history |
  | `GET /v3/users/{vendor_data}/` / `GET /v3/businesses/{vendor_data}/` | path param |

  ## Pattern — pre-create the entity, then run a session

  ```bash
  # 1) Seed the entity with metadata before any session
  curl -X POST https://verification.didit.me/v3/users/create/ \
  -H "x-api-key: $DIDIT_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) Run a KYC session linked to the same entity
  curl -X POST https://verification.didit.me/v3/session/ \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "workflow_id": "$WORKFLOW_ID",
  "vendor_data": "user-42",
  "callback": "https://myapp.com/return"
  }'

  # 3) Later, retrieve every session for the entity
  curl -G https://verification.didit.me/v3/sessions/ \
  -H "x-api-key: $DIDIT_API_KEY" \
  --data-urlencode "vendor_data=user-42"
  ```

  ## Auto-create semantics

  If you create a session with a new `vendor_data` and no entity exists, Didit creates the entity automatically with `status: ACTIVE` and links the session.

  ## Failure modes

  * Missing `vendor_data` on session create → session is orphaned, won't appear in any entity profile, cannot be filtered by `vendor_data` later (only by `session_id`).
  * Different case (`User-42` vs `user-42`) → two separate entities. Pick a casing convention and stick to it.
  * Same `vendor_data` across staging and prod apps → no collision; `vendor_data` is scoped per application.

  ## Sources of truth

  * /entities/users/operations — full User CRUD
  * /entities/businesses/operations — full Business CRUD
  * /sessions-api/create-session — session body shape
  * /integration/integration-prompt — canonical end-to-end prompt\`\`\`\`
</pre>

貼り付け先

`vendor_data`は、各セッションと取引を[ユーザー](https://docs.didit.me/ja/entities/users/overview.md)または[企業](https://docs.didit.me/ja/entities/businesses/overview.md)エンティティに紐付けるために指定する識別子です。エンティティの集約において最も重要なフィールドであり、正しく設定すれば、その後のすべての機能(プロフィール履歴、トランザクションモニタリング、ブロックリストの適用、継続的なAMLモニタリング)がスムーズに動作します。

## 概要

`vendor_data`は、お客様が任意に決める**文字列**です。Diditはこれを不透明な識別子として扱い、内容を解釈しません。代表的な値は次のとおりです。

| お客様のシステム | 適切な`vendor_data`の値 |
| - | - |
| 社内のユーザーデータベース | `user_1234`、ユーザーの`uuid-v4` |
| 顧客向けID | `CUST-2026-00042`、ハッシュ化したメールアドレス |
| マルチテナントSaaS | `tenant_acme:user_1234` |
| B2Bプラットフォーム | `company-hq-global`、`tax-id-US-123456789` |

> [!WARNING]
>
> 個人情報(メールアドレス、電話番号、加工していない納税者番号)を`vendor_data`に直接**入れないでください**。ハッシュ化するか、プレフィックスを付けてください。`vendor_data`はWebhookのペイロードに含まれ、エンティティが存在する限り無期限に保存されます。

## 紐付けの仕組み

```mermaid theme={null}
flowchart TD
    subgraph YourSystem["Your system"]
      Customer["Customer record: user-42"]
    end
    subgraph Didit["Didit platform"]
      Entity["User entity (vendor_data = user-42)"]
      S1[Session #1]
      S2[Session #2]
      T1[Transaction #1]
      T2[Transaction #2]
      F[Face biometric]
    end
    Customer -.vendor_data.-> Entity
    S1 --> Entity
    S2 --> Entity
    T1 --> Entity
    T2 --> Entity
    F --> Entity
```

`vendor_data`の値を指定してセッションまたは取引を送信すると、次のように処理されます。

1. Diditは、お客様のアプリケーション内でその`vendor_data`を持つエンティティを検索します。
2. エンティティが存在する場合、新しいオブジェクトはそのエンティティに紐付けられます。
3. エンティティが存在しない場合、Diditはエンティティを（`status: ACTIVE`として）作成し、新しいオブジェクトを紐付けます。

これは次の場合に当てはまります。

* `POST /v3/session/`:KYCおよび法人確認 (KYB) のセッション
* `POST /v3/transactions/`:取引(申請者と取引相手の両方)
* 取引ペイロード内の`applicant.vendor_data`/`counterparty.vendor_data`フィールド

## 一意性とスコープ

`vendor_data`は**アプリケーションごとに一意**であり、Didit全体で一意なわけではありません。

| スコープ | 一意性の保証 |
| - | - |
| 1つのアプリケーション内 | `vendor_data`はエンティティの種類ごとに一意です(ユーザーと企業は別々の名前空間です) |
| 組織内の複数のアプリケーション間 | `vendor_data`は共有**されません**。2つのアプリで同じ値を使うと、それぞれ別のエンティティを指します |
| 組織間 | 共有されません。各組織が独自のエンティティテーブルを持ちます |

そのため、ステージング用アプリと本番環境用アプリで同じ`vendor_data`を使っても衝突しません。また、ユーザー`user-42`と企業`user-42`を同時に持っても衝突しません(ただし、わかりやすさのために推奨されません)。

## `vendor_data`を省略した場合

`vendor_data`を指定せずにセッションを作成することもできます。その場合は次のようになります。

* そのセッションに対してエンティティは作成されません。
* セッションはどこにも属さず、どのユーザーまたは企業のプロフィールにも表示されません。
* 後からそのセッションを`vendor_data`で検索することはできず、`session_id`でのみ検索できます。

この方法は、エンティティの集約が不要な匿名または単発の認証にのみ使用してください。再検証、取引、継続的なモニタリングを伴う連携では、必ず`vendor_data`を指定してください。

## エンティティを事前に作成してからセッションを実行する例

```bash theme={null}
# 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" }
  }'
```

3つの呼び出しはすべて同じユーザーエンティティに紐付けられます。後から`GET /v3/users/user-42/`を呼び出すと、セッション数、承認済み/却下の件数、紐付けられた取引、最新のプロフィールデータを確認できます。

## 外部IDの移行

既存のKYCベンダーからDiditに移行する場合は、初日から既存の固定ユーザーIDを`vendor_data`として渡してください。これにより、次のことが容易になります。

* Diditのデータを社内データベースと照合する。
* セッションを実行する前に、コンソールのCSVインポートで過去のユーザーを一括登録する。
* 後から取引モニタリングをDiditに移行する際に、関係性を維持する。

## ルール、規約、ベストプラクティス

| ルール | 理由 |
| - | - |
| エンティティごとに正規の識別子を1つ決め、決して変更しない | 変更すると新しいエンティティが作成され、履歴が切り離されます |
| `vendor_data`の値にエンティティの種類を示すプレフィックス(`user_...`、`biz_...`)を付ける | お客様のコード内で名前空間どうしが誤って衝突するのを防ぎます |
| `vendor_data`の大文字・小文字を変えずに保つ | Diditは大文字・小文字を正規化しません |
| `vendor_data`の長さを128文字未満にする | データベースのインデックスに無理なく収まります |
| 加工していない個人情報を決して公開しない | `vendor_data`はWebhook、監査ログ、APIレスポンスに含まれます |

## 次のステップ

> [card] [ユーザーの概要](https://docs.didit.me/ja/entities/users/overview.md)
>
> ユーザーエンティティと操作について詳しく説明します。

> [card] [企業の概要](https://docs.didit.me/ja/entities/businesses/overview.md)
>
> 企業エンティティと操作について詳しく説明します。

> [card] [セッションの作成](https://docs.didit.me/ja/sessions-api/create-session.md)
>
> vendor\_dataに対する認証を開始します。

> [card] [取引の作成](https://docs.didit.me/ja/management-api/transactions/create.md)
>
> エンティティに紐付けた取引を送信します。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.