sumsub-manage-applicant-tags

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sumsub — Manage Applicant Tags

Sumsub — 管理申请人标签

Adds, replaces, and removes tags on an applicant profile, always followed by a read-back. Tags are free-form labels used for filtering and classification in the applicant list; they are also readable as

applicant.tags

in workflow routing and TM rule expressions.

对申请人资料进行标签的添加、替换和移除操作，操作后均会执行标签读取验证。标签是用于申请人列表筛选和分类的自由格式标签；在工作流路由和TM规则表达式中，标签也可通过

applicant.tags

字段读取。

Endpoints

接口端点

Verb	Path	Purpose
`POST`	`/resources/applicants/{applicantId}/tags/add`	Add tags on top of the existing set. Additive; repeat adds of an existing tag are deduped server-side. Body: bare JSON array of strings.
`POST`	`/resources/applicants/{applicantId}/tags`	Overwrite — replaces the entire tag set with the body. `[]` clears all tags. Destructive: requires the confirm step below.
`DELETE`	`/resources/applicants/{applicantId}/tags`	Remove only the tags listed in the body; the rest stay.
`GET`	`/resources/applicants/{applicantId}/one`	Read-back. Tags come back in the `tags` field of the applicant — there is no dedicated tags GET.

All writes return

{"ok": 1}

on success. Tag names not seen before are auto-created on both the add and the overwrite endpoint (sandbox-verified; the docs' claim that overwrite requires pre-existing tags is outdated).

Tag definitions — renaming a tag, picking its color, or the "include tag in applicant summary report" flag — are Sumsub dashboard UI only (Applicant tags page); there is no public-API surface for them.

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（申请人标签页面）操作；公开API不支持此类操作。

Auth — App Token + secret (sandbox only)

身份验证 — App Token + 密钥（仅沙箱环境）

This skill talks to the public Sumsub API and signs each request per the authentication reference. The full how-it-works writeup lives in the

sumsub-api-auth

skill — read it if you hit

401 Invalid signature

⚠️ Sandbox tokens only. Do not accept or use a production App Token here. If the user offers one, refuse and ask them to generate a sandbox pair at https://cockpit.sumsub.com/checkus/devSpace/appTokens (toggle the workspace to Sandbox first, then Create). Token + secret are shown once — copy both before closing the dialog. The helper script enforces this — it rejects tokens that don't start with
sbx:
.

Var	Example
`SUMSUB_APP_TOKEN`	`sbx:...` — sandbox App Token from the dashboard.
`SUMSUB_SECRET_KEY`	The paired secret shown once at token creation.
`SUMSUB_BASE`	Optional. Defaults to `https://api.sumsub.com` .

If the user has already supplied credentials in conversation, reuse them; otherwise ask once before running. Never echo the secret back.

本技能调用Sumsub公开API，并按照身份验证参考文档对每个请求进行签名。完整的工作原理说明请查看

sumsub-api-auth

技能——若遇到

401 Invalid signature

错误，请阅读该文档。

⚠️ 仅支持沙箱令牌。请勿接受或使用生产环境的App Token。若用户提供生产环境令牌，请拒绝并要求其在https://cockpit.sumsub.com/checkus/devSpace/appTokens生成沙箱环境令牌对（先将工作区切换至Sandbox，再点击Create）。令牌和密钥仅会显示一次——关闭对话框前请复制两者。辅助脚本会强制执行此规则——拒绝所有不以
sbx:
开头的令牌。

变量	示例
`SUMSUB_APP_TOKEN`	`sbx:...` — 来自控制台的沙箱环境App Token。
`SUMSUB_SECRET_KEY`	创建令牌时一次性显示的配对密钥。
`SUMSUB_BASE`	可选参数。默认值为 `https://api.sumsub.com` 。

若用户已在对话中提供过凭证，请复用；否则在执行操作前询问一次。切勿回显密钥。

Procedure

操作流程

Pick the operation. Default to the additive
```
add
```
— it is safe and deduped. Use
```
overwrite
```
only when the user explicitly wants to replace the whole set (or clear it); use
```
remove
```
to take specific tags off. Do not pre-GET before
```
add
```
or
```
remove
```
— the endpoints are targeted and idempotent, the read-back in step 3 is the verification.
Overwrite only — confirm first. GET the applicant, show the user the current tags that will be lost, and get explicit confirmation before POSTing the replacement set. Same gate applies to clearing all tags (overwrite with
```
[]
```
).

Run the write via the orchestrator (it appends the read-back automatically):

bash

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"

Compare the read-back to what was requested. An empty set comes back with the
```
tags
```
field absent from
```
GET /one
```
— that is the normal "no tags" state, not an error. On a mismatch, report it — do not retry automatically. Surface 4xx errors verbatim.
Report, names first. Lead with the applicant's name and the resulting tag list, then the dashboard link (
```
https://cockpit.sumsub.com/checkus/applicant/<applicantId>
```
— render as a clickable markdown link), and put the applicant
```
id
```
on its own last line.

选择操作类型。默认使用增量式
```
add
```
操作——该操作安全且支持自动去重。仅当用户明确要求替换整个标签集（或清空标签）时使用
```
overwrite
```
操作；使用
```
remove
```
操作移除特定标签。在执行
```
add
```
或
```
remove
```
操作前无需预先调用GET接口——这些端点是针对性的且具有幂等性，步骤3中的读取验证即可完成校验。
仅覆盖操作需先确认。调用GET接口获取申请人信息，向用户展示即将被覆盖的当前标签，并在发送替换标签集的POST请求前获得明确确认。清空所有标签（用
```
[]
```
覆盖）时同样需要此确认步骤。

通过编排器执行写入操作（会自动附加读取验证步骤）：