sumsub-create-level

Sumsub — レベルの作成

簡潔な仕様から ApplicantLevel JSON ペイロードを作成し、Sumsub API に POST（または PATCH）して、結果の name／id を報告します。

エンドポイント

メソッド	パス	用途
POST	/resources/applicants/-/levels	新しいレベルを作成します。本文に id または key を含めてはいけません。これらはサーバーによって割り当てられます。
PATCH	/resources/applicants/-/levels	既存のレベルを更新します（本文の id で指定）。
GET	/resources/applicants/-/levels/{id}	レベルを 1 つ読み込みます。保存された内容の確認（テナントの制限により一部のフィールドが通知なく削除される場合があります）、または既知の id から name を特定するために使用します。
GET	/resources/applicants/-/levels	すべてのレベルを一覧表示します（重複を作成しないよう、新規作成前に既存のレベルを再利用する場合に使用します）。

本文：ApplicantLevel。id、createdAt、監査証跡を含む保存済みレベルを返します。

認証 — アプリトークン + シークレット（サンドボックスのみ）

このスキルは公開 Sumsub API と通信し、 認証リファレンスに従って各リクエストに署名します。 仕組みの詳細は sumsub-api-auth スキルに記載されています。401 Invalid signature が発生した場合は、そちらをお読みください。

⚠️ サンドボックスのトークンのみ使用してください。 本番環境のアプリトークンを受け入れたり、ここで使用したりしないでください。レベルの作成は、ワークスペース上で確認できる書き込み操作です。ユーザーが本番用トークンを提示した場合は、使用を断り、https://cockpit.sumsub.com/checkus/home?sbx=true でサンドボックス用のトークンとシークレットのペアを生成するよう依頼してください（Sumsub を AI エージェントに接続 -> ビルドと設定 -> トークンを生成）。トークンとシークレットは一度だけ表示されるため、ダイアログを閉じる前に両方をコピーしてください。このヘルパースクリプトはこの制限を適用し、sbx: で始まらないトークンを拒否します。

変数	例
SUMSUB_APP_TOKEN	sbx:... — ダッシュボードで発行したサンドボックスのアプリトークン。
SUMSUB_SECRET_KEY	トークン作成時に一度だけ表示される、対応するシークレット。
SUMSUB_BASE	任意。デフォルトは https://api.sumsub.com です。

ユーザーが会話ですでに認証情報を提示している場合は、それを再利用してください。提示されていない場合は、実行前に一度だけ尋ねてください。シークレットを決してそのまま返さないでください。

手順

0. テナントのエンタイトルメントを取得します。 sumsub-check-permissions スキルを呼び出し、JSON の結果を解析します。allowedChecks マップを保存します（キーは有効なエンタイトルメントです）。ステップ 2 と以下のエンタイトルメントのセクションでのすべての機能ゲート確認に、このマップを使用します。何よりも先に実行してください。

1. 既存のエンティティを確認します。 作成を始める前に、既存のレベル、POA プリセット、アンケートを一覧表示します（それぞれの一覧エンドポイントに GET します）。一致するエンティティがすでにある場合は、その id の再利用を提案し、POST を省略してください。サーバーは名前による重複排除を行わず、POST のたびに重複を作成します。

2. ユーザーのリクエストを、以下の簡潔な仕様に変換します。名前、申請者タイプ、WebSDK フローに表示する順序の書類セットのステップ一覧です。リクエストがデータベース／書類以外の検証を示唆している場合は、先に sumsub-check-databases を使用してソースを解決してください（データベース／書類以外の検証を参照）。

3. 検証します — すべての type が実在する IdDocSetType であること、すべての QUESTIONNAIRE ステップの questionnaireDefId が既存のアンケートを参照していること、すべての PROOF_OF_RESIDENCE* ステップに poaPresetId／poaStepSettingsId があること（ない場合、サーバーはレベルを拒否します。プリセットが存在しない場合は、先に sumsub-create-poa-preset を実行してください）、すべての COMPANY ステップに名前付きのサブステップが少なくとも 1 つあることを確認します。ステップ 0 の allowedChecks のキーを使い、該当するエンタイトルメントがない機能ゲート付き機能を拒否してください。

4. ペイロードを生成します — ${CLAUDE_SKILL_DIR}/scripts/build_level.py を実行し、仕様を標準入力に渡すと、完全なペイロードが標準出力に出力されます。

5. 解決済みのペイロードをユーザーに提示し、最初の POST の前に明示的な確認を求めます。

6. 作成と更新：

   • 新規レベル — ${CLAUDE_SKILL_DIR}/scripts/post_level.sh を使って POST します。レスポンスボディと HTTP ステータスが返されます。
   • 既存レベルの更新 — ${CLAUDE_SKILL_DIR}/scripts/get_level.sh を使って現在の状態を GET し、ユーザーが差分を確認できるようにしてから、${CLAUDE_SKILL_DIR}/scripts/patch_level.sh を使って PATCH します。build_level.py に渡す仕様には id: <level-id> を含める必要があります — ビルダーはこれをペイロードに保持し、含まれていないボディでは PATCH が拒否されます。PATCH は requiredIdDocs.docSets を単一の配列として置き換えます — 送信するすべての docSet に、意図する状態全体を含めてください。省略されたフィールドはサーバー上で消去されます。GET レスポンスから保持する値を PATCH 仕様にコピーしてください。

7. ${CLAUDE_SKILL_DIR}/scripts/get_level.sh を使ってレベルを GET し、送信した内容と比較します — 送信時とは異なる形で反映されるフィールドがいくつかあります（references/level-schema.md の注意点を参照）。相違があればユーザーに報告してください。

8. ダッシュボードリンクを作成します。 レスポンスボディから id、applicantType、clientId を読み取り、次の形式にします。

   https://cockpit.sumsub.com/checkus/sdkIntegrations/levels/<applicantType>Level/<id>?clientId=<clientId>&sbx=true
   

   <applicantType>Level の部分は、applicantType: individual の場合は文字どおり individualLevel（確認済み）、applicantType: company の場合は companyLevel（類推に基づく想定）です。最善の推測として提示し、404 が発生した場合はその旨を明記してください。sbx=true クエリパラメーターは Sandbox ワークスペースを指定します。これは、すべてのスキルで共通の標準的なサンドボックスリンク用パラメーターです。

9. 報告します — 人が読める名前を先頭に示します。

   • name、applicantType、作成した docSet の順序付き一覧。
   • クリック可能な Markdown リンクとしての ダッシュボードリンク。
   • 最終行：Level ID (for SDK access tokens / future PATCH): <id>。

   4xx エラーはそのまま提示してください。通常、questionnaireDefId がないか、認識されない enum 値があることを示しています。

テナントの利用権限

レベル設定の多くは、テナントの利用権限（allowedChecks）によって制限されています。機能を有効にする前に、ステップ 0 で取得した sumsub-check-permissions が返す allowedChecks マップに、必要な BackgroundCheckTarget がキーとして含まれていることを確認してください。

DocSet の種類 → 必要な権限（OR — いずれか 1 つで十分です）：

DocSet の種類	必要な権限（いずれか 1 つ）
QUESTIONNAIRE / QUESTIONNAIRE2-4	QUESTIONNAIRE
COMPANY / COMPANY_DATA	COMPANY | KYB_FULL | KYB_AUTO_AML_AND_REGISTRY | KYB_AUTO_AML_ONLY
SOLANA_ATTESTATION / LINEA_ATTESTATION	PAYMENT_METHOD_CRYPTO
PAYMENT_METHODS	PAYMENT_SOURCE | PAYMENT_METHOD | PAYMENT_METHOD_CRYPTO | KYT_UNHOSTED_WALLET_VERIFICATION
INVESTABILITY	PROOF_OF_FUNDS
PROOF_OF_RESIDENCE / PROOF_OF_RESIDENCE2	POA | ADVANCED_POA_TYPE_DETECTION（API では実際に許可されている場合でも、allowedChecks に含まれていないことがよくあります。その場合は 1 行の警告を添えて続行してください。下記を参照）
E_KYC	E_KYC_TARGET
E_SIGN	E_SIGN_TARGET
TR_RECIPIENT_INFORMATION	TRAVEL_RULE
DEVICE_CHECK	DEVICE_INTELLIGENCE

この表にない種類（IDENTITY、SELFIE、APPLICANT_DATA、EMAIL_VERIFICATION、PHONE_VERIFICATION など）は、すべてのテナントで利用できます。利用権限は不要です。

AML／ウォッチリスト審査 → WATCHLISTS。 これは docSet ではなく、レベル全体に適用される動作です。WATCHLISTS が allowedChecks に含まれている場合、AML／PEP／制裁審査はすべてのレベルでデフォルトで有効になります（レベルごとに disableWatchlists: true を設定すると無効にできます）。WATCHLISTS がない場合、審査はテナント全体で無効になり、どのレベル設定でも有効にできません。AML 審査が必要なポリシーは、権限がないためブロックされているものとして扱ってください（CSM に連絡してください）。上記の docSet の制限と同様です。

要求された機能に必要な利用権限がテナントにない場合は、直ちに停止してください。 レベルを作成したり POST したりしないでください。どの利用権限が不足しているか、そのアカウントでは機能を利用できないこと、有効化するには CSM または Sumsub サポートに連絡する必要があることをユーザーに伝えてください。利用権限が追加されたことをユーザーが確認するか、その機能を明示的に取り下げると決めた後にのみ再開してください。

例外 — POA。 POA／ADVANCED_POA_TYPE_DETECTION キーは、API が PROOF_OF_RESIDENCE レベルを実際に受け入れるテナントでも、allowedChecks に含まれていないことがよくあります（利用権限は基本機能として提供されているか、ほかのキーでカバーされているようです。テナントによっては、文書化されたマッピングが古くなっています）。POA だけがない場合は、サポートが必要になったときにユーザーが状況を把握できるよう、1 行の警告を添えて続行してください。明示的な確認を求めて一時停止してはいけません。テナントに実際に権限がなければ Sumsub 自身が書き込みを拒否するため、事前に停止するよりも、その 4xx エラーのほうが状況をよく示します。利用権限に関連するエラーが返された場合は、文言を変更せずそのまま提示してください。

安全性

レベルの作成は、共有ワークスペースへの書き込みです。常に次のことを行ってください。

• 最初の POST の前に、解決済みのペイロードをユーザーに表示してください（上記のステップ 4）。
• POST が成功するたびに、対象エンティティを GET で再取得し、送信した内容と比較してください。通知されない上書きはよく発生します。
• 依存関係（PoA プリセット、アンケート）がセッション中にすでに成功している場合は、再度 POST せず、返された id を再利用してください。
• ユーザーが明示的に指定しない限り、このセッションで作成していないレベルを削除または変更しないでください。

ユーザー向けメッセージでは、ID ではなく名前を使う

このレベルについてユーザーに送るすべてのメッセージに適用されます。最終レポートだけではありません。

• POST 前の概要： 添付するアンケートと POA プリセットを列挙するときは、それぞれの name / title を使ってください（例：「POA プリセット『POA — 60 days』」、「アンケート『Applicant basics』」）。生の id（"6a16bfd4ded0fe13aa48165d"）を文章に貼り付けないでください。ユーザーには判別できず、適切なエンティティを選んだかどうかの判断材料にもなりません。
• 最終レポート： 引き続き、最終レポートは Level ID (for SDK access tokens / future PATCH): <id> という行で終えてください。この行だけは生の ID を使って構いません。次の API 呼び出しでコピーする必要があるためです。
• 診断メッセージ： 4xx レスポンスで依存先の ID（POA プリセットが見つからない場合など）が示されたら、ユーザーに表示する前に名前に置き換えてください。

エンティティの名前がまだわからない場合（例：ユーザーがこのセッション外で得た ID だけを提示した場合）は、先にエンティティを GET して名前を確認してください。ID のまま表示してはいけません。

コンパクトな仕様形式

標準入力から JSON または YAML を受け付けます。ビルダーは各ドキュメントセットの種類に応じて適切なデフォルト値を設定します（references/level-schema.md を参照してください）。

{
  "name": "Basic KYC",
  "applicantType": "individual",
  "type": "standalone",
  "docSets": [
    {"type": "IDENTITY", "docTypes": ["PASSPORT","ID_CARD","DRIVERS"]},
    {"type": "SELFIE", "videoRequired": "passiveLiveness"},
    {"type": "PROOF_OF_RESIDENCE", "docTypes": ["UTILITY_BILL"]},
    {"type": "QUESTIONNAIRE", "questionnaireDefId": "source-of-funds"}
  ]
}

新しいレベルは WebSDK 2.0（websdkNext: true）である必要があります。 作成時は、ビルダーが自動的に websdkNext: true を設定するため、仕様に含める必要はありません。ただし、websdkNext: false は決して設定しないでください（非推奨の WebSDK 1.0 レベルが作成されます）。既存のレベルを更新する場合（仕様に id がある場合）、ビルダーは websdkNext を変更しません。こちらでも変更しないでください。稼働中のレベルの SDK をアップグレードするにはクライアント側で大規模な移行が必要となるため、無関係な PATCH の副作用として変更してはいけません。ユーザーから明示的に依頼された場合に限り変更してください。

サポートされる docSets[].type の値

APPLICANT_DATA、EMAIL_VERIFICATION、PHONE_VERIFICATION、IDENTITY、IDENTITY2/3/4、SELFIE、SELFIE2、PROOF_OF_RESIDENCE、PROOF_OF_RESIDENCE2、PROOF_OF_PAYMENT、PAYMENT_METHODS、INVESTABILITY、COMPANY、COMPANY_DATA、COMPANY_DOCUMENTS、COMPANY_BENEFICIARIES、ACCREDITED_INVESTOR、E_SIGN、QUESTIONNAIRE/2/3/4、E_KYC、OTHER_DOCS、TR_RECIPIENT_INFORMATION、DEVICE_CHECK。

タイプごとの簡潔なショートカット

type	ショートカットキー	ビルダーによる展開先
IDENTITY*	docTypes；videoRequired（disabled / docapture）；captureMode と uploaderMode（docapture の場合のみ送信）；nfcVerificationSettings: {mode}	docSet 上のフラットなフィールド — 設定したものだけが含まれます。下記のDashboard ↔ API のマッピングをご覧ください。
SELFIE*	videoRequired（デフォルトは passiveLiveness；指定可能な値：disabled / enabled / photoRequired / passiveLiveness / staticLiveness）、docTypes（デフォルトは ["SELFIE"]）；selfieProcessingSettings: {skipLivenessCheck, skipFaceMatchCheck}（決済方法の検証で使用 — 下記をご覧ください）	videoRequired ［+ selfieProcessingSettings］を含むベア docSet
PROOF_OF_RESIDENCE*	docTypes（デフォルトは ["UTILITY_BILL"]）；POA プリセットを ID で設定するための poaPresetId（または poaStepSettingsId）	docSet + poaStepSettingsId
QUESTIONNAIRE*	questionnaireDefId（またはエイリアスの questionnaireId）— 必須	ベア docSet
APPLICANT_DATA	fields — 文字列の配列、または {name, required, prefill, immutableIfPresent}	デフォルト値を含む fields[]
PAYMENT_METHODS	typeSettings（オブジェクト — キー：bankCard、bankAccount、cryptoWallet、eWallet — 下記の決済方法の検証をご覧ください）；skipOwnershipCheck（ブール値、デフォルトは false）；skipRiskScoreCheck（ブール値）；walletScreeningProvider（列挙型 — スキーマを参照）	検証済みの構造を持つ paymentSourceSettings。常に types: ["PAYMENT_SOURCE"] が出力されます
EMAIL_VERIFICATION / PHONE_VERIFICATION	—	ベア docSet
COMPANY	steps — {name, minDocsCnt?, idDocTypes?, idDocSubTypes?, fields?, applicantLevelName?} の配列	完全な KYB ステップ構造
E_SIGN	esignSettings（そのまま渡されます）	そのまま

docSet 内の不明なキーは、そのまま API に渡されるため、まれにしか使わないフィールドが必要な場合でも簡単に対応できます。

IDENTITY ステップのダッシュボード ↔ API マッピング

Sumsub ダッシュボードのサイドバーに表示されるラベルをそのまま記載し、設定する API 値と対応付けています。ユーザーの説明に一致するラベルを選び、その値を使用してください。

ダッシュボードのコントロール	ラベル（ユーザーに表示）	API 値	Spec のキー
キャプチャ方法	ファイルアップロード	disabled	videoRequired
キャプチャ方法	ライブキャプチャ	docapture	videoRequired
キャプチャモード¹	手動キャプチャと自動キャプチャの両方が同時に機能します	manualAndAuto	captureMode
キャプチャモード¹	手動キャプチャのみが有効です	manualOnly	captureMode
キャプチャモード¹	シームレスなライブキャプチャ	seamless	captureMode
ファイルアップロードへのフォールバック¹	常に利用可能	always	uploaderMode
ファイルアップロードへのフォールバック¹	カメラキャプチャに失敗した場合のみ利用可能	fallback	uploaderMode
ファイルアップロードへのフォールバック¹	利用不可	never	uploaderMode
NFC 認証²	無効	disabled	nfcVerificationSettings.mode
NFC 認証²	任意	optional	nfcVerificationSettings.mode
NFC 認証²	必須	required	nfcVerificationSettings.mode

¹ videoRequired: docapture の場合にのみ意味があります。それ以外ではペイロードから暗黙的に削除されます（ラジオボタンを「ファイルアップロード」に切り替えると両方のキーを削除する、ダッシュボード独自の動作と一致します）。 ² required は Web SDK の申請者を自動的に却下します。Mobile SDK のみ対応しています。

ビルダーが出力するデフォルト値（ダッシュボードで表示するために必要です。コントロールは暗黙的な UI デフォルト値ではなく、実際に保存された値に紐付いています。空のフィールドはデフォルトの選択肢ではなく、「選択」プレースホルダーとして表示されます）：

• videoRequired: docapture → captureMode: manualAndAuto、uploaderMode: always（呼び出し側が上書きしない場合）。
• IDENTITY には常に nfcVerificationSettings: {mode: disabled} が設定されます（呼び出し側が上書きしない場合）。

これらは、ユーザーが初めてライブキャプチャを切り替えたときに、ダッシュボード独自の Vue ウォッチャーが書き込む値と一致します。PATCH に関する注意点： requiredIdDocs.docSets は全体が置き換えられます（最上位の Level フィールドのみマージされます）。そのため、PATCH の spec に含める各 docSet には、意図する状態をすべて指定する必要があります。省略したサブフィールドは消去されます。まずレベルを GET し、保持したい値をコピーしてください。

AML／ウォッチリストスクリーニング：独立した 2 つのゲート

1. テナントゲート — WATCHLISTS エンタイトルメント（ステップ 0 で確認）。WATCHLISTS が allowedChecks に含まれている場合、AML スクリーニングを利用でき、すべてのレベルでデフォルトで実行されます。含まれていない場合、テナント全体でスクリーニングが無効になっており、どのレベル設定でも有効にはできません。有効化に必要なエンタイトルメントがないことを示し（CSM に連絡）、レベル設定で有効になるかのように扱わないでください。
2. レベルゲート — disableWatchlists（テナントに WATCHLISTS がある場合のみ有効）。このレベルでスクリーニングを無効にするには、最上位に "disableWatchlists": true を指定します。有効のままにするには、省略するか false を指定します。watchListCheckSettings.amlCaseType はプロバイダーを選択するだけ（テナントのエンタイトルメントによって制御）であり、useCustomWatchListCheckSettings はカスタム設定と継承設定のどちらを使うかを選択するだけです。どちらも有効／無効を切り替えるスイッチではありません。

したがって、AML スクリーニングを必須とするポリシーでは、ステップ 0 で WATCHLISTS を確認した後、レベルには何も追加せず、GET して disableWatchlists が true でないことを確認してください。AML をスキップする必要があるレベルでは、disableWatchlists: true を設定してください。詳細：references/level-schema.md。

支払い方法の確認（ステップまたはアクション）

銀行カード、銀行口座、暗号資産ウォレット、または電子ウォレットを確認するための PAYMENT_METHODS docSet による支払い方法の確認は、2つのモードで実行できます。

• 通常の確認レベル内のステップとして：IDENTITY／SELFIE／PROOF_OF_RESIDENCE などと並べて PAYMENT_METHODS docSet を追加します。レベルは actionType を指定しない通常の standalone レベルのままです。支払い確認を、より広範なオンボーディングフローの一部にする場合に使用します。
• アクションタイプのレベル上のアクションとして：type: "actions" と actionType: "paymentMethod" を設定します。オンボーディングから切り離した、単独で再実行可能な支払い方法の確認に使用します。

ユーザーの意図に応じてモードを選択します。「KYC レベルにカード／ウォレットの確認を追加したい」ならステップ、「単独の支払い方法確認／アクションを作成したい」ならアクションです。

ステップモード — 標準的なレベル内（本人確認と支払い確認を併用）：

{
  "name": "KYC + payment method",
  "type": "standalone",
  "applicantType": "individual",
  "docSets": [
    {"type": "IDENTITY"},
    {"type": "SELFIE", "videoRequired": "passiveLiveness"},
    {"type": "PAYMENT_METHODS",
     "typeSettings": {"bankCard": {"allowed": true, "countImages": "one"}}}
  ]
}

アクションモード — アクションレベル内：

{
  "name": "Payment method check",
  "type": "actions",
  "actionType": "paymentMethod",
  "websdkNext": true,
  "docSets": [
    {"type": "PAYMENT_METHODS", "skipOwnershipCheck": false,
     "typeSettings": {"bankCard": {"allowed": true, "countImages": "one"}}}
  ]
}

ビルダーが適用する制約：

• actionType: "paymentMethod" を指定するには、type: "actions" が必要であり、レベルには PAYMENT_METHODS docSet を含める必要があります。
• skipOwnershipCheck: true と skipRiskScoreCheck: true は同時に設定できません。
• walletScreeningProvider は typeSettings.cryptoWallet の内部ではなく、paymentSourceSettings のレベルに指定します（ビルダーが適切な場所に配置します）。
• bankAccount には具体的な確認方法が必要です。 bankCard とは異なり、allowed: true だけで銀行口座を有効にするとAPI に拒否されます。allowBankStatementUpload（追加のエンタイトルメント不要の明細アップロード）または allowExternalSourcesCheck（E_KYC エンタイトルメントを使用する外部データソース確認）の少なくとも一方を有効にする必要があります。どの方法を希望するかユーザーに確認してください。「標準」の銀行口座オプションだけを提示してはいけません。

PAYMENT_METHODS docSet（両方のモード）： ビルダーは常に types: ["PAYMENT_SOURCE"] と、コンパクトな仕様から組み立てた paymentSourceSettings オブジェクトを出力します。API は paymentSourceSettings のない docSet を拒否するため、ビルダーがこれを省略することはありません。

支払いソースの種類ごとの typeSettings：

キー	フィールド
bankCard	allowed（bool）；countImages（"one"／"two"／"some"）；extractIban（bool）；extractNationalBankAccountNumbers（bool）；requireBankAccountNumber（bool）
bankAccount	allowed（bool）；allowBankStatementUpload（bool）；allowExternalSourcesCheck（bool — E_KYC_TARGET エンタイトルメントが必要）。allowed の場合、上記の制約にある2つの方法のうち、少なくとも一方を true にする必要があります。
cryptoWallet	allowed（bool）；satoshiTestAllowed（bool）；unhostedWalletFormType（"DEFAULT"／"SIMPLE"／"KAZ"／"TUR"／"SGP"／"POL"／"ITA"）
eWallet	allowed（bool）

walletScreeningProvider 列挙値： crystal／merkle／trmLabs／chainalysis／elliptic／cyvers

エンタイトルメント： PAYMENT_SOURCE または KYT_UNHOSTED_WALLET_VERIFICATION が必要です（テナントのエンタイトルメントを参照）。

ダッシュボードリンク： どちらのモードも sdkIntegrations/levels/individualLevel/<id> にあり、標準の standalone レベルの URL パターンに従います。

アクションモードの仕様全体については、examples/payment-methods.json を参照してください。

データベース／非書類による確認（KYC）

対象：個人のKYCのみです。 企業のデータベース確認／KYBは、この方法では対象外です。

リクエストが書類の確認ではなく、または書類の確認に加えて、申請者データをデータベース／登録簿と照合することを示している場合（「非書類」「eKYC」「書類なし」「データベース／登録簿との照合」「ID／SSN／DNI番号の検証」など）、ペイロードを作成する前に、sumsub-check-databases を使ってソースを特定し、配置してください。

1. sumsub-check-databases <country> を実行します。status == "ENABLED" のソースは使用できます。SANDBOX_ONLY はサンドボックスでは動作しますが、本番環境では実行されません（ユーザーが本番運用を予定しているレベルを作成する前に、その旨を伝えてください）。DISABLED は使用できません。ユーザーが必要とするソースが利用できない場合は、そのスキルの代替策と有効化のガイダンスに従ってください（黙って除外せず、Databases → Available products を案内してください。ほとんどのソースはセルフサービスで利用できます）。
2. 各ソースの validationReady／stepsReady によって配置場所が決まります。この2つのシグナルは独立しているため、両方を確認してください。

シグナル	docSet	備考
validationReady: true	書類の docSet を維持します（例：IDENTITY。types はそのままです）	ソースはアップロードされた書類のデータをデータベースと照合します。レベルのトップレベルにある checkSourceSettings（requiredIdDocs と同階層に置き、requiredIdDocs 内や docSet 内には入れません）に設定します。
stepsReady に単独のタイプ（例：E_KYC）が含まれる	そのタイプの独立した docSet を使用し、types フィールドは設定しません	データベースのみを使用し、アップロードは不要です。E_KYC には E_KYC_TARGET が必要です。checkSourceSettings はこの docSet の内部にネストします。
stepsReady に既に必須となっている書類ステップと並んでタイプ（例：IDENTITY）が含まれる	その docSet の types を維持します	申請者は同じステップで、書類のアップロードまたはデータベース確認を選択できます。ここでも E_KYC_TARGET が必要です。checkSourceSettings はトップレベルではなく、同じ docSet の内部にネストします。

ソースの stepsReady に複数のステップタイプが記載されている場合、それらは有効な配置先の候補であり、すべてを使う必要はありません。ユーザーの意図に合ったものを選んでください。

3. 選択したソースを checkSourceSettings.countrySettings[] から追加します。配置場所は、レベルのトップレベル（validationReady の配置では、requiredIdDocs と同階層の checkSourceSettings キー）または該当する docSet 内（stepsReady の配置）です。

"checkSourceSettings": {
  "countrySettings": [
    {
      "country": "ARG",
      "checkType": "E_KYC_CHECK",
      "groupType": "INPUT_COUNTRY",
      "executionConfigurations": [
        {"sourceId": "arg_gov_dni", "fallbackReasons": []}
      ]
    }
  ]
}

• country、checkType、sourceId は、チェックデータベースのレスポンスからそのまま取得します。
• groupType には INPUT_COUNTRY（申請者の国）を使用します。これがデフォルトです。TARGET_COUNTRY は、ビザ確認など、国境をまたぐまれなソースでのみ使用します。
• executionConfigurations の順序には意味があります。複数の sourceId を指定すると、順番にフォールバックします。fallbackReasons（例：NAME_MISMATCH、DATA_NOT_FOUND）によって次のソースへのフォールバックが実行されます。[] はフォールバックなしを意味します。

3つの配置例を最初から最後まで確認するには、examples/identity-selfie-with-database-validation.json（トップレベル、validationReady）、examples/identity-with-non-doc-selfie.json（IDENTITY 内にネスト）、および examples/non-doc.json（独立した E_KYC）を参照してください。

フィールドの意味、列挙値、利用できないソースの取り扱いについては、sumsub-check-databases とそのスキーマリファレンスを参照してください。

ほかの Sumsub-* スキルとの連携

このスキルの QUESTIONNAIRE および PROOF_OF_RESIDENCE のドキュメントセットでは、関連スキルで生成した ID を受け付けるため、3 ステップで一からすべてを構築するフローが自然です。

最初に実行するもの …	返された id を指定する場所 …
sumsub-create-questionnaire	QUESTIONNAIRE ドキュメントセットの docSets[].questionnaireDefId
sumsub-create-poa-preset	PROOF_OF_RESIDENCE ドキュメントセットの docSets[].poaPresetId

両方を参照するエンドツーエンドのレベルについては、examples/with-presets.json を参照してください。

データベース／ドキュメント以外による検証では、sumsub-check-databases を実行してソースを特定し、checkSourceSettings を使って追加してください。詳しくは上記のデータベース／ドキュメント以外による検証を参照してください。

出力

成功した場合は、人が読みやすい情報を先頭に記載します。

• name、applicantType、docSets[].idDocSetType の順序付きリスト。
• ダッシュボードへのリンク：https://cockpit.sumsub.com/checkus/sdkIntegrations/levels/<applicantType>Level/<id>?clientId=<clientId>&sbx=true。クリック可能な Markdown リンクとして表示してください。<applicantType>Level の部分は、個人の場合は individualLevel（確認済み）、企業の場合は companyLevel（想定されるパターン）です。3 つのフィールド（id、applicantType、clientId）はすべて POST レスポンス本文から取得します。sbx=true は Sandbox ワークスペースを指定します。
• 最後に、単独の行として次を記載します：Level ID (for SDK access tokens / future PATCH): <id>。

失敗した場合：HTTP ステータスと、Sumsub のエラーエンベロープに含まれる description／errorName。

実例

• examples/identity-selfie.json — 最も一般的なパターンです。
• examples/identity-live-capture.json — Live capture とすべての docapture サブオプション、NFC を含む IDENTITY のみの例です。
• examples/questionnaire-only.json — 純粋なデータ収集レベルの例です（このリポジトリの SOF レベルのようなものです）。
• examples/full-kyc.json — APPLICANT_DATA + IDENTITY + SELFIE + PROOF_OF_RESIDENCE + QUESTIONNAIRE。
• examples/kyb-company.json — 企業、UBO、代表者の各ステップを含む KYB レベルです。
• examples/with-presets.json — 関連スキルから返されたアンケート（questionnaireDefId）と POA プリセット（poaPresetId）の両方を参照します。
• examples/payment-methods.json — 銀行カード、銀行口座、暗号資産ウォレット、電子ウォレットを含む支払い方法アクションレベルです。
• examples/identity-selfie-with-database-validation.json — データベース検証（validationReady）の例です。書類のアップロードはそのまま利用し、トップレベルの checkSourceSettings を使ってソースが照合します。
• examples/identity-with-non-doc-selfie.json — 既存のステップ内でドキュメント以外を扱う例（stepsReady）です。checkSourceSettings は IDENTITY 内にネストされ、申請者はアップロードまたはデータベースチェックを利用できます。
• examples/non-doc.json — 独立したドキュメント以外の例（stepsReady）です。専用の E_KYC docSet を使い、書類のアップロードはありません。

関連項目

• references/level-schema.md — ApplicantLevel の全スキーマ、すべての列挙値、注意点。