> ## 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.

# KYB連携ガイド：アーキテクチャと実装パターン

> DiditのKYBを本番環境に組み込む方法を解説します。アーキテクチャ、セッション、ホスト型フロー、Webhook、ポーリング、判定まで網羅しています。料金はチェック1件あたり$2.00からで、国とレベルごとに設定されます。



KYB連携用プロンプト
        プロンプトをクリップボードにコピー



      
      

\<pre>

\````# Goal — ship a production-ready KYB (business verification) integration

KYB runs through the same `/v3/session/` endpoint as KYC. The session's workflow determines whether it's a KYC or KYB session — pass a KYB workflow id and Didit creates a business session automatically (`session_kind: "business"`).

\## End-to-end flow

\```
You: POST /v3/session/ (KYB workflow_id, vendor_data) → session_id, url, session_token
You: deliver url to the business contact (email / your UI / iframe)
Biz: completes the hosted flow (registry confirm → Key People → documents → AML)
Didit → Webhook: status.updated with session_kind: "business"
You: GET /v3/session/{session_id}/decision/ → full KYB decision
You: branch on decision.status ("Approved" / "Declined" / "In Review" / "Resubmitted")
\```

\## Create a KYB session

\```bash
curl -X POST https://verification.didit.me/v3/session/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflow_id": "$KYB_WORKFLOW_ID",
"vendor_data": "biz-acme",
"callback": "https://myapp.com/kyb/return",
"metadata": {"plan": "growth", "country": "GBR"}
}'
\```

Recommended fields:

\- `workflow_id` — references your KYB workflow.
\- `vendor_data` — your business id; binds the session to a [Business entity](/entities/businesses/overview).
\- `callback` — where to redirect the user after completion.
\- `metadata` — JSON attached to the session for your own reporting.

\## Webhook events for KYB

\| Event | Trigger |
\|---|---|
\| `status.updated` (with `session_kind === "business"`) | KYB session status changed. Follow this event for progress. |
\| `data.updated` (with `session_kind === "business"`) | A reviewer edited registry data or Key People in the console, or the registry reported a change (registry monitoring). Not sent for document uploads or Key People submissions. |
\| `business.status.updated` | Linked Business entity status changed |
\| `business.data.updated` | Linked Business entity profile / counters changed |

Subscribe via `POST /v3/webhook/destinations/` with `webhook_version: "v3"`. Verify the `X-Signature-V2` header (HMAC-SHA256 of canonical JSON). De-dupe on `event_id`. Respond within 5 seconds.

\## KYB decision shape (V3 plural arrays)

\```bash
curl https://verification.didit.me/v3/session/$SESSION_ID/decision/ \
-H "x-api-key: $DIDIT_API_KEY"
\```

Key V3 arrays you'll iterate:

\| Array | Holds |
\|---|---|
\| `key_people_checks[]` | UBOs, shareholders, directors, officers — bucketed into `registry` (from the registry lookup) and `submitted` (what the business confirmed). Plus a `ubo_kyc_summary` rollup. |
\| `document_verifications[]` | Each item has `status`, `node_id`, `items[]` (signed `file_url` + OCR extract), `groups`, `required_groups`. |
\| `aml_screenings[]` | Company AML and per-person AML hits. |

The KYB-specific features are `KYB_REGISTRY`, `AML`, `KYB_DOCUMENTS`, `KYB_KEY_PEOPLE`. Statuses are the exact labels `"Not Finished"`, `"Approved"`, `"Declined"`, `"In Review"`, `"Resub Requested"`.

\## Apply-decision logic

\```ts
switch (decision.status) {
case "Approved":   await onboardBusiness(decision); break;
case "Declined":   await logRejection(collectWarnings(decision), decision); break; // warnings[] tags on each feature array
case "In Review":  await markPending(decision); break; // wait for next webhook
case "Resubmitted":await notifyBusiness(decision); break; // business needs to re-upload
case "Awaiting User": await pingChildPersonForKyc(decision); break; // child Key People KYC pending
}
\```

See /business-verification/statuses for the full state machine.

\## Resubmission flow

When a session transitions to `Resubmitted` (or a feature to `Resub Requested`, or a feature is marked for resubmission), re-deliver the same `url` — the hosted flow resumes at the resubmission step. To re-verify a specific Key Person, resubmit that person's child KYC session; the parent `kyb_key_people` re-aggregates automatically.

\## Key People child KYC

If your KYB workflow has KYC required for some roles, each person triggers a child KYC session automatically. While any child is in progress, the parent's `kyb_key_people` status is `Awaiting User`. Configure per-role required/skippable behaviour at *Workflows → [KYB workflow] → Key People*. A child session expires after the session expiration time of the KYC workflow its role is mapped to, not the KYB session's. A party whose session was deleted, or whose link expired before the person started it, is reissued with `POST /v3/session/{session_id}/kyb/parties/{party_uuid}/regenerate/`.

\## Failure modes

\| Scenario | Response |
\|---|---|
\| Invalid `workflow_id` | `400 Bad Request` |
\| Wrong workflow type (KYC instead of KYB) | Session is created but runs KYC steps — verify the workflow's `workflow_type` is `"kyb"` |
\| Duplicate `vendor_data` | A new session is created — that's by design for re-KYB |
\| Company country outside the workflow's allowed countries | The registry check raises the `KYB_COUNTRY_RESTRICTED` warning |
\| Registry provider outage during company search | `502` with `code: "kyb_registry_provider_unavailable"`. Not billed. In Didit's hosted flow, the business is automatically offered manual company entry instead of a retry-only error. |
\| Rate limit | `429` with `Retry-After` header |

\## Sources of truth

\- /sessions-api/create-session — request body schema
\- /business-verification/response-schema — KYB decision payload
\- /business-verification/statuses — feature state machine
\- /business-verification/webhooks — KYB-specific event catalog
\- /entities/businesses/data-model — Business entity schema
\- /integration/integration-prompt — canonical end-to-end prompt````

\</pre>



      
      

貼り付け先

このガイドは[クイックスタート](https://docs.didit.me/ja/business-verification/quickstart.md)を補完するものです。アーキテクチャ、連携に関するあらゆる判断、本番環境でKYBを安定して運用するための運用パターンを解説します。## アーキテクチャ```mermaid theme={null}
sequenceDiagram
    participant You as Your platform
    participant Didit as Didit API
    participant Biz as Business contact
    participant Webhook as Your webhook endpoint

    You->>Didit: POST /v3/session/ (workflow_id, vendor_data)
    Didit-->>You: session_id, url, token
    You->>Biz: Deliver hosted verification URL (your email/flow)
    Biz->>Didit: Completes KYB hosted flow
    Didit->>Didit: Registry lookup, AML screening, OCR
    Didit->>Webhook: status.updated (session_kind: business)
    You->>Didit: GET /v3/session/{id}/decision/
    Didit-->>You: Full KYB decision payload
    You->>You: Onboard / reject / escalate based on status
```## 認証すべてのリクエストには、アプリケーションのAPIキーを指定した`x-api-key`ヘッダーが必要です。キーのローテーション、環境の分離、スコープについては[API認証](https://docs.didit.me/ja/getting-started/api-authentication.md)を参照してください。## セッションの作成エンドポイントは`POST /v3/session/`のみです。セッションがKYCかKYBかはワークフローの種類で決まるため、「企業」を示すフラグを明示的に指定する必要はありません。**作成時に推奨されるフィールド:**| フィールド | 用途 |
| - | - |
| `workflow_id` | 必須。KYBワークフローを参照します。 |
| `vendor_data` | 企業を識別するための独自の識別子です。セッションを[企業エンティティ](https://docs.didit.me/ja/entities/businesses/overview.md)に紐付けます。 |
| `callback_url` | 任意。完了後にユーザーをリダイレクトする先です。 |
| `expected_details` | 任意。`{ company_name, registry_country, registration_number }`を指定します。法人登記の検索に値が事前入力されます。設立国は事前に選択されて固定され（`registry_country`は`XX`、州単位の登記簿の場合は`XX-YY`の形式。例: `US-CA`）、会社名と登記番号のフィールドが事前入力され、指定された条件での検索が自動的に実行されます。両方の識別子が指定されている場合は、両方を組み合わせて検索します。事前入力のみを目的としており、不一致があっても警告は生成されません。 |
| `metadata` | 任意。セッションに付与するJSONです。 |完全なスキーマ: [セッションの作成](https://docs.didit.me/ja/sessions-api/create-session.md)。## ホスト型リンクの配信レスポンスの`url`はホスト型の認証リンクです。配信方法には次の選択肢があります。- 自社のプラットフォームからメールで送信する。
- オンボーディングUIにリンクとして埋め込む。
- アプリ内のWebView(iOS / Android / React Native)で開く。ロゴ、カラー、ドメイン、メールテンプレートなど、ホスト型の画面は[ホワイトラベル](https://docs.didit.me/ja/console/white-label.md)で**カスタマイズ**できます。## ポーリングとWebhookの比較推奨されるのはWebhookです。Diditは処理が完了するとすぐに、登録済みのエンドポイントへ完了イベントをPOSTします。開発時や、Webhookエンドポイントに到達できない場合は、ポーリングも利用できます。* `GET /v3/session/{id}/decision/`を指数バックオフでポーリングします(最初は10秒ごと、最大60秒間隔まで)。
* `status`が`"Approved"`、`"Declined"`、`"In Review"`のいずれかになったらポーリングを停止します。> [!WARNING]
>
> 高頻度でポーリングすると[レート制限](https://docs.didit.me/ja/integration/rate-limiting.md)に達する場合があります。本番環境では必ずWebhookを優先してください。## Webhookの処理必要なイベントを購読してください。KYCとKYBのどちらにも同じイベントが使われ、ペイロード内の`session_kind: "business"`で企業セッションのイベントを識別します。- `status.updated`: セッションのステータスが変更されました。KYBセッションは`session_kind === "business"`でフィルターしてください。
- `data.updated`: レビュアーがコンソールで登記データや主要人物を編集したか、法人登記から変更が報告されました。申請者が書類をアップロードしたり主要人物を送信したりした場合には送信されないため、その場合は`status.updated`を確認してください。同じ`session_kind`フィルターが適用されます。
- `business.status.updated` / `business.data.updated`: 紐付けられた[企業エンティティ](https://docs.didit.me/ja/entities/businesses/overview.md)が変更されました。イベントの一覧: [KYB Webhook](https://docs.didit.me/ja/business-verification/webhooks.md)。署名検証と再試行の仕組み: [Webhookリファレンス](https://docs.didit.me/ja/integration/webhooks.md)。## 判定の処理```typescript theme={null}
switch (decision.status) {
  case 'Approved':
    await onboardBusiness(decision);
    break;
  case 'Declined':
    // The KYB decision has no single reason code: collectWarnings is your helper
    // that flattens warnings[] from registry_checks, document_verifications,
    // key_people_checks and aml_screenings
    await logRejection(collectWarnings(decision), decision);
    break;
  case 'In Review':
    // Wait for analyst decision — another webhook will fire
    await markPending(decision);
    break;
  case 'Resubmitted':
    // The business was asked to re-upload a document
    await notifyBusiness(decision);
    break;
}
```状態遷移の全体は[KYBステータス](https://docs.didit.me/ja/business-verification/statuses.md)を、判定の理由を示すタグは[KYBの警告](https://docs.didit.me/ja/business-verification/warnings.md)を参照してください。## 再提出フロー法人確認 (KYB)セッションが`Resubmitted`に遷移した場合(または機能が再提出対象としてマークされた場合)、企業は修正済みのデータまたは追加データをアップロードする必要があります。次の対応が可能です。- 同じ`url`を**再配信する**: ホスト型フローは再提出が必要な箇所から再開されます。
- **無効になった主要人物のリンクを再発行する**: 子KYCセッションが削除された、または本人が開始する前に期限切れになった関係者には、[主要人物のKYCセッションの再生成](https://docs.didit.me/ja/sessions-api/regenerate-kyb-party.md)で新しいセッションを発行します。
- Business Consoleで**[ケース](https://docs.didit.me/ja/transaction-monitoring/cases.md)を作成する**: 社内でのやり取りを追跡できます。## 自社のフロントエンドからステップを実行する書類と主要人物のステップは、APIキーを使って自社のサーバーから操作することもできます。ユーザーインターフェースは自社で保持し、認証と判定はDiditが担います。
すべての呼び出しはKYBセッション単位で行われ、`write:businesses`権限が必要です(抽出された関係者の読み取りには`read:businesses`または`read:sessions`も使用できます)。ホスト型ページと同じチェック、請求、ステップの進行が適用されます。1) セッションがKYB書類ステップにある間に、[法人書類をアップロード](https://docs.didit.me/ja/sessions-api/kyb-upload-documents.md)します。
2) 株主や所有比率を含め、[書類に記載された関係者を読み取り](https://docs.didit.me/ja/sessions-api/kyb-extracted-parties.md)、申請者に表示します。
3) [作成](https://docs.didit.me/ja/sessions-api/kyb-list-party-drafts.md)を[編集](https://docs.didit.me/ja/sessions-api/kyb-create-party-draft.md)、[削除](https://docs.didit.me/ja/sessions-api/kyb-update-party-draft.md)、[関係者の下書き](https://docs.didit.me/ja/sessions-api/kyb-delete-party-draft.md)します。下書きは申告扱いにならず、料金も発生しません。
4) [下書きを送信](https://docs.didit.me/ja/sessions-api/kyb-submit-parties.md)します。Diditは認証が必要な関係者を判断し、それぞれにKYCセッションを作成して、送信または埋め込み用の`kyc_session_url`を返します。
5) ホスト型フローと同様に、セッションから統合された判定を読み取ります。セッションが別のステップにあるときに呼び出すと、現在のステップとともに`409 kyb_step_mismatch`が返されます。完了したセッションに対しては`409 kyb_session_not_writable`が返されます。## 企業プロファイルの集約セッション作成時に`vendor_data`を指定すると、Diditはその企業のすべてのセッションを1つの[企業エンティティ](https://docs.didit.me/ja/entities/businesses/overview.md)に集約します。エンティティの`features`マップを使えば、セッションを順に確認しなくても「この企業は現時点で完全に認証済みか」を判断できます。メリット:- 定期的な再KYBフローが同じプロファイルに追加されます。
- 同じ`vendor_data`に対して監視される取引に、企業のリスクコンテキストが引き継がれます。
- ユーザーエンティティに紐付けられたUBOや役員によって、エンティティ間の関係が構築されます。## ベストプラクティス| プラクティス | 理由 |
| - | - |
| `vendor_data`を必ず渡す | 渡さないとセッションがどこにも紐付かず、集約できません。 |
| ポーリングではなくWebhookを使う | レイテンシが低く、レート制限の負荷もありません。 |
| Webhookの署名を検証する | なりすましイベントを防止できます。 |
| `session_id`を自社側で保存する | 判定の取得やPDFの生成に必要です。 |
| `metadata`でセッションにタグを付ける | レポート作成やデバッグが簡単になります。 |
| テスト用のワークフローを用意する | 本番環境の前に、サンドボックスのワークフローで連携テストを行います。 |## エラー処理| シナリオ | レスポンス |
| - | - |
| 無効な`workflow_id` | `400 Bad Request` |
| 同じ`vendor_data`での重複セッション | 新しいセッションが作成されます。再検証が想定されているため、これは仕様どおりの動作です。 |
| 企業の所在国がワークフローで許可された国に含まれない | 登記チェックで`KYB_COUNTRY_RESTRICTED`警告が発生します。 |
| 企業検索中の登記プロバイダーの障害 | `POST /v3/kyb/search/`が`code: "kyb_registry_provider_unavailable"`とともに`502`を返します。課金されないため、再試行するか、`code`で分岐して企業情報の手動入力を提供してください。Diditのホスト型フローでは、再試行のみを促すエラーではなく、企業は自動的に手動入力へ誘導されます。詳しくは[KYB登記検索](https://docs.didit.me/ja/standalone-apis/kyb-registry-search.md#登記情報プロバイダーの障害への対応)をご覧ください。 |
| レート制限 | `Retry-After`ヘッダー付きの`429 Too Many Requests` |[レート制限](https://docs.didit.me/ja/integration/rate-limiting.md)の完全なリファレンスもご覧ください。## 次のステップ> [card] [Webhook](https://docs.didit.me/ja/business-verification/webhooks.md)
>
> すべてのKYBイベントとペイロード。> [card] [ステータス](https://docs.didit.me/ja/business-verification/statuses.md)
>
> 状態遷移のリファレンス。> [card] [レスポンススキーマ](https://docs.didit.me/ja/business-verification/response-schema.md)
>
> KYB判定の読み解き方。


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