sumsub-manage-applicant-tags

Sumsub — 申請者タグの管理

申請者プロフィールのタグを追加、置換、削除し、必ず操作後に読み取り確認を行います。タグは、申請者リストでのフィルタリングや分類に使う自由形式のラベルです。また、ワークフローのルーティングや TM ルールの式では、applicant.tags として読み取ることもできます。

エンドポイント

Verb	Path	Purpose
POST	/resources/applicants/{applicantId}/tags/add	既存のタグセットにタグを追加します。追加のみを行います。同じタグを繰り返し追加しても、サーバー側で重複が除去されます。本文は文字列の JSON 配列のみです。
POST	/resources/applicants/{applicantId}/tags	上書き — 本文の内容でタグセット全体を置き換えます。[] を指定するとすべてのタグが消去されます。破壊的な操作のため、以下の確認手順が必要です。
DELETE	/resources/applicants/{applicantId}/tags	本文に記載されたタグのみを削除します。その他のタグはそのまま残ります。
GET	/resources/applicants/{applicantId}/one	読み取り確認。タグは申請者の tags フィールドに含まれます。タグ専用の GET はありません。

書き込みが成功すると、すべて {"ok": 1} が返されます。初めて使うタグ名は、追加と上書きのどちらのエンドポイントでも自動作成されます（サンドボックスで確認済みです。上書きには既存のタグが必要だというドキュメントの記述は古くなっています）。

タグの定義 — タグ名の変更、色の選択、「申請者サマリーレポートにタグを含める」フラグの設定 — は、Sumsub ダッシュボードの UI のみ（Applicant tags ページ）で行えます。これらを操作する公開 API はありません。

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

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

⚠️ サンドボックストークンのみ。 本番用アプリトークンを受け取ったり、使用したりしないでください。ユーザーから提示された場合は断り、https://cockpit.sumsub.com/checkus/home?sbx=true でサンドボックス用のペアを生成するよう依頼してください（Connect Sumsub to your AI agent -> Build & configure -> Generate token）。トークンとシークレットは一度しか表示されないため、ダイアログを閉じる前に両方をコピーしてください。ヘルパースクリプトはこのルールを強制し、sbx: で始まらないトークンを拒否します。

Var	Example
SUMSUB_APP_TOKEN	sbx:... — ダッシュボードで発行したサンドボックス用アプリトークン。
SUMSUB_SECRET_KEY	トークン作成時に一度だけ表示される、対になるシークレット。
SUMSUB_BASE	省略可能。デフォルトは https://api.sumsub.com です。

ユーザーが会話中にすでに認証情報を提示している場合は、それを再利用します。それ以外の場合は、実行前に一度だけ確認してください。シークレットをそのまま表示してはいけません。

手順

1. 操作を選びます。 デフォルトでは、追加のみを行う add を使います。安全で、重複も除去されるためです。タグセット全体の置換（または全消去）をユーザーが明示的に希望する場合にのみ overwrite を使います。特定のタグを削除する場合は remove を使います。add または remove の前に GET してはいけません。対象が指定された冪等なエンドポイントであり、ステップ 3 の読み取り確認で検証できるためです。

2. 上書きの場合のみ — 先に確認します。 申請者を GET し、失われる現在のタグをユーザーに示してから、置き換えセットを POST する前に明示的な確認を得ます。すべてのタグを消去する場合（[] で上書きする場合）も、同じ確認が必要です。

3. オーケストレーター経由で書き込みを実行します（読み取り確認は自動的に追加されます）。

   bash scripts/manage_applicant_tags.sh list      <applicantId>
   bash scripts/manage_applicant_tags.sh add       <applicantId> "High Risk" "VIP"
   bash scripts/manage_applicant_tags.sh overwrite <applicantId> "Compliance Reviewed"   # after the confirm step!
   bash scripts/manage_applicant_tags.sh remove    <applicantId> "Legacy KYC"
   

4. 読み取り確認の結果を、依頼された内容と比較します。タグが空の場合、GET /one では tags フィールドが含まれません。これはエラーではなく、通常の「タグなし」の状態です。一致しない場合はその旨を報告し、自動で再試行してはいけません。4xx エラーはそのまま提示してください。

5. 結果を報告します。名前を最初に示します。 申請者の名前と操作後のタグ一覧を先に示し、続けてダッシュボードのリンク（https://cockpit.sumsub.com/checkus/applicant/<applicantId> — クリック可能な Markdown リンクとして表示）を記載します。最後の行には申請者の id のみを記載してください。

注意点

• 申請者ごとにタグは最大30個です。 既存のタグと新しいタグの合計が上限を超えると、リクエスト全体が HTTP 400 "Too many applicant tags" で失敗し、変更は一切適用されません。30個の上限を伝え、そこで停止してください。リストを削って再試行したり、同じ実行中に既存のタグを削除または上書きして空きを作ったりしないでください。空きを作るかどうかは、ユーザーが新しいリクエストで明示的に判断する必要がある破壊的な操作です。
• タグ名では大文字と小文字が区別されます。"High Risk" と "high risk" は別のタグです。削除する際は、ユーザーが既に使っている大文字・小文字の表記に合わせてください。
• 上書きするとすべて置き換わります。 POST .../tags にどのような本文を送信しても、そこに記載されていないタグはすべて削除されます。ユーザーが「追加」と言った場合は、上書きエンドポイントを決して使用しないでください。
• 空の場合、フィールドはありません。 タグをすべてクリアすると、GET /one には tags フィールドがまったく含まれなくなります。読み戻し処理では、フィールドがない場合は空のセットとして扱う必要があります。
• 申請者が見つからない場合は HTTP 404 "Applicant with id ... not found (anf)" が返されます（400 ではありません）。ユーザーに ID を再確認してもらってください。
• タグの変更によって applicantTagsChanged webhook が発火します。テナントがこの webhook を購読している場合に関係します（sumsub-manage-webhooks を参照）。

関連項目

• sumsub-create-kyt-rules — 取引タグ、スコアリングウェイト（scoreWeight）を含むタグ定義、申請者のリスク評価。
• sumsub-create-workflow — ワークフローのアクションノードとしてタグの追加・削除を自動化し、applicant.tags に基づいてルーティングします。
• sumsub-manage-webhooks — applicantTagsChanged を購読します。
• Sumsub のドキュメント：申請者タグ、 申請者タグの追加と上書き、 申請者タグの追加、 申請者タグの削除。