sumsub-create-questionnaire

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sumsub — Create Questionnaire

Sumsub — 创建问卷

Builds a questionnaire definition JSON payload from a compact spec, POSTs it to the Sumsub API, and reports the resulting

id

(client-supplied slug) and

_id

(server-assigned identifier).

根据简洁规范构建问卷定义JSON负载，将其提交至Sumsub API，并返回生成的

id

（客户端提供的slug）和

_id

（服务器分配的标识符）。

Endpoints

接口端点

Method	Path	When
`POST`	`/resources/api/agent/questionnaires`	Create a new questionnaire. Fails with `409 CONFLICT` if `id` already exists.
`PATCH`	`/resources/api/agent/questionnaires`	Update an existing questionnaire (by `id` in body). Fails with `404 NOT_FOUND` if no such questionnaire.
`GET`	`/resources/api/agent/questionnaires/{id}`	Read one questionnaire (verify what landed; resolve `title` from a known `id` ).
`GET`	`/resources/api/questionnaires/list`	List all questionnaires. (Stays on the non-agent path.)
`GET`	`/resources/api/questionnaires/usedByLevels`	List questionnaires with the levels that reference them. (Stays on the non-agent path.)

All require permission

manageClientSettings

. Body shape is the questionnaire schema — client-settable fields only (

clientId

createdAt

, audit metadata are server-managed).

POST vs PATCH — these are now strict. POST refuses an existing
id
; PATCH refuses a missing one. The pre-INT-4893 "single POST upsert" behavior is gone — always pick the right verb up front (call GET /{id} first if unsure whether the questionnaire exists).

方法	路径	适用场景
`POST`	`/resources/api/agent/questionnaires`	创建新问卷。若 `id` 已存在则返回 `409 CONFLICT` 冲突错误。
`PATCH`	`/resources/api/agent/questionnaires`	更新现有问卷（通过请求体中的 `id` ）。若问卷不存在则返回 `404 NOT_FOUND` 未找到错误。
`GET`	`/resources/api/agent/questionnaires/{id}`	读取单个问卷（验证已提交内容；通过已知 `id` 获取 `title` ）。
`GET`	`/resources/api/questionnaires/list`	列出所有问卷。（使用非agent路径）
`GET`	`/resources/api/questionnaires/usedByLevels`	列出被各等级引用的问卷。（使用非agent路径）

所有接口均需

manageClientSettings

权限。请求体需符合问卷 schema — 仅包含客户端可设置字段（

clientId

、

createdAt

、审计元数据由服务器管理）。

POST与PATCH的区别 — 两者现在有严格区分。POST会拒绝已存在的
id
；PATCH会拒绝不存在的
id
。INT-4893之前的“单POST请求自动更新”行为已取消 — 请务必提前选择正确的请求方法（若不确定问卷是否存在，先调用GET /{id}接口）。

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` 。

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

Tenant entitlements

租户权限

Creating a questionnaire requires the

QUESTIONNAIRE

entitlement. Before doing anything else, invoke the

sumsub-check-permissions

skill and verify that

QUESTIONNAIRE

is present in the

allowed

array.

If
QUESTIONNAIRE
is not in
allowed
— stop immediately. Do not build or POST the questionnaire. Tell the user the entitlement is missing and that they need to contact their CSM or Sumsub support to get it enabled.

创建问卷需要

QUESTIONNAIRE

权限。在执行任何操作前，调用

sumsub-check-permissions

技能，确认

QUESTIONNAIRE

在

allowed

数组中。

若
QUESTIONNAIRE
不在
allowed
数组中 — 立即停止操作。请勿构建或提交问卷。告知用户缺少该权限，需要联系客户成功经理或Sumsub支持团队启用。

Procedure

操作流程

Fetch tenant entitlements — see section above.
Gather spec. Map the user's questions into the compact spec format below — never hand-write the full localized payload.
Validate — confirm
```
id
```
is a unique slug, every item has a supported
```
type
```
, every conditional reference points to a real
```
<sectionId>.<itemId>
```
.
Generate payload by running
```
${CLAUDE_SKILL_DIR}/scripts/build_questionnaire.py
```
with the spec on stdin. Inspect the output briefly.
Create vs. update — POST/PATCH scripts accept the payload as a path argument or on stdin (pipe it from
```
build_questionnaire.py
```
for a one-liner):
- New — POST via
```
${CLAUDE_SKILL_DIR}/scripts/post_questionnaire.sh <payload.json>
```
  (or
```
… | post_questionnaire.sh -
```
  ). If the user already supplied an
```
id
```
  they used before, GET it first via
```
${CLAUDE_SKILL_DIR}/scripts/get_questionnaire.sh
```
  to avoid a
```
409 CONFLICT
```
  .
- Update existing — GET via
```
${CLAUDE_SKILL_DIR}/scripts/get_questionnaire.sh
```
  first so the user sees what they're overwriting; then PATCH via
```
${CLAUDE_SKILL_DIR}/scripts/patch_questionnaire.sh <payload.json>
```
  .
Build the dashboard link. Read
```
id
```
and
```
clientId
```
from the response body (both fields are present on the persisted questionnaire) and format:
```
https://cockpit.sumsub.com/checkus/sdkIntegrations/questionnaireDetails/<id>?clientId=<clientId>&xSNSEnv=sbx
```
The
```
xSNSEnv=sbx
```
query param targets the Sandbox workspace — it is the canonical sandbox link param shared across all skills.
Report — lead with the human-readable title:
- ```
title
```
  , section/item count, country/lang coverage if relevant.
- Dashboard link as a clickable markdown link.
- Final line:
```
Questionnaire ID (for level wiring / future PATCH): <id>
```
  .
Surface any 4xx with the
```
description
```
field from the error body. For
```
409 CONFLICT
```
on POST — suggest PATCH instead.

获取租户权限 — 见上文章节。
收集规范。将用户提供的问题映射为下方的简洁规范格式 — 切勿手动编写完整的本地化负载。
验证 — 确认
```
id
```
是唯一的slug，每个条目都有支持的
```
type
```
，每个条件引用都指向有效的
```
<sectionId>.<itemId>
```
。
生成负载 — 通过标准输入传入规范，运行
```
${CLAUDE_SKILL_DIR}/scripts/build_questionnaire.py
```
。简要检查输出内容。
创建与更新 — POST/PATCH脚本接受路径参数形式的负载或标准输入形式的负载（可通过
```
build_questionnaire.py
```
管道输出实现一键操作）：
- 创建新问卷 — 通过
```
${CLAUDE_SKILL_DIR}/scripts/post_questionnaire.sh <payload.json>
```
  （或
```
… | post_questionnaire.sh -
```
  ）执行POST请求。若用户提供了之前使用过的
```
id
```
  ，请先通过
```
${CLAUDE_SKILL_DIR}/scripts/get_questionnaire.sh
```
  调用GET接口，避免返回
```
409 CONFLICT
```
  错误。
- 更新现有问卷 — 先通过
```
${CLAUDE_SKILL_DIR}/scripts/get_questionnaire.sh
```
  调用GET接口，让用户查看即将覆盖的内容；再通过
```
${CLAUDE_SKILL_DIR}/scripts/patch_questionnaire.sh <payload.json>
```
  执行PATCH请求。
构建控制台链接。从响应体中读取
```
id
```
和
```
clientId
```
（两者均存在于已保存的问卷中），并格式化为：
```
https://cockpit.sumsub.com/checkus/sdkIntegrations/questionnaireDetails/<id>?clientId=<clientId>&xSNSEnv=sbx
```
```
xSNSEnv=sbx
```
查询参数用于指向沙箱工作区 — 这是所有技能通用的标准沙箱链接参数。
结果反馈 — 以易读的标题开头：
- ```
title
```
  、章节/条目数量、相关国家/语言覆盖范围（若适用）。
- 控制台链接：以可点击的markdown链接形式展示。
- 最后一行：
```
问卷ID（用于等级关联/后续PATCH操作）: <id>
```
  。
若返回4xx错误，展示错误体中的
```
description
```
字段。若POST请求返回
```
409 CONFLICT
```
错误 — 建议用户改用PATCH请求进行更新。

Compact spec format

简洁规范格式

JSON or YAML accepted on stdin. English titles are auto-wrapped into

localizedTitle

localizedDesc

. Use

condition

strings for show/hide logic — see references/questionnaire-schema.md for syntax.

json

{
  "id": "source-of-funds",
  "title": "Source of Funds",
  "desc": "Optional one-liner shown to applicants.",
  "showTitleAsStepName": true,
  "sections": [
    {
      "id": "primary",
      "title": "Primary Source",
      "desc": "Optional section description.",
      "condition": null,
      "items": [
        {"id": "main", "title": "Main source?", "type": "select", "required": true,
         "options": [["salary","Salary"],["business","Business"],["other","Other"]]},
        {"id": "other", "title": "Specify", "type": "text",
         "condition": "primary.main = other"}
      ]
    }
  ]
}

支持通过标准输入传入JSON或YAML格式。英文标题会自动封装为

localizedTitle

localizedDesc

。使用

condition

字符串实现显示/隐藏逻辑 — 语法请参考references/questionnaire-schema.md。

json

{
  "id": "source-of-funds",
  "title": "Source of Funds",
  "desc": "Optional one-liner shown to applicants.",
  "showTitleAsStepName": true,
  "sections": [
    {
      "id": "primary",
      "title": "Primary Source",
      "desc": "Optional section description.",
      "condition": null,
      "items": [
        {"id": "main", "title": "Main source?", "type": "select", "required": true,
         "options": [["salary","Salary"],["business","Business"],["other","Other"]]},
        {"id": "other", "title": "Specify", "type": "text",
         "condition": "primary.main = other"}
      ]
    }
  ]
}

Supported item types

支持的条目类型

text

textArea

date

dateTime

bool

select

phone

selectDropdown

multiSelect

countrySelect

countryMultiSelect

fileAttachment

multiFileAttachments

select

selectDropdown

multiSelect

require

options: [[value, title], ...]

text

textArea

date

dateTime

bool

select

phone

selectDropdown

multiSelect

countrySelect

countryMultiSelect

fileAttachment

multiFileAttachments

。

select

selectDropdown

multiSelect

类型需要

options: [[value, title], ...]

参数。

Outputs

输出结果

On success, lead with the human-readable info:

```
title
```
, section/item count,
```
createdAt
```
.
Dashboard link:
```
https://cockpit.sumsub.com/checkus/sdkIntegrations/questionnaireDetails/<id>?clientId=<clientId>&xSNSEnv=sbx
```
. Render as a clickable markdown link so the user can jump to the entity. Both
```
id
```
and
```
clientId
```
are in the POST response body;
```
xSNSEnv=sbx
```
targets the Sandbox workspace.

Finally, on its own line:

Questionnaire ID (slug, for level wiring / future PATCH): <id>

On failure: print HTTP status +

description

type

from the error envelope; do not retry blindly. On

409 CONFLICT

from POST — suggest PATCH for an update.

成功时，以易读信息开头：

```
title
```
、章节/条目数量、
```
createdAt
```
。
控制台链接：
```
https://cockpit.sumsub.com/checkus/sdkIntegrations/questionnaireDetails/<id>?clientId=<clientId>&xSNSEnv=sbx
```
。以可点击的markdown链接形式展示，方便用户直接跳转至该实体。
```
id
```
和
```
clientId
```
均可在POST响应体中获取；
```
xSNSEnv=sbx
```
用于指向沙箱工作区。

最后单独一行：

问卷ID（slug，用于等级关联/后续PATCH操作）: <id>

。

失败时：输出HTTP状态码 + 错误包中的

description

type

字段；请勿盲目重试。若POST请求返回

409 CONFLICT

错误 — 建议用户改用PATCH请求进行更新。

Names, not ids, in user-facing messages

用户消息中使用名称而非ID

This applies to every message about the questionnaire — pre-POST summary, mid-flow status updates, diagnostics — not only the final report:

Refer to the questionnaire by
```
title
```
("Applicant basics"), not by its
```
id
```
slug, in prose.
The slug
```
id
```
belongs only on the final dedicated line (
```
Questionnaire ID (slug): <id>
```
) — that line is the one place a raw id is correct, because the user needs to copy it into a level's
```
questionnaireDefId
```
.
When mentioning sections or items, prefer their
```
title
```
over their
```
id
```
.

此规则适用于所有与问卷相关的消息 — POST前的摘要、流程中的状态更新、诊断信息 — 不仅仅是最终报告：

在文本描述中，使用问卷的
```
title
```
（如“申请人基础信息”）而非
```
id
```
slug。
slug格式的
```
id
```
仅应出现在最后单独的一行（
```
问卷ID（slug）: <id>
```
） — 这是唯一适合展示原始ID的位置，因为用户需要将其复制到等级的
```
questionnaireDefId
```
中。
提及章节或条目时，优先使用其
```
title
```
而非
```
id
```
。

Hand-off to

sumsub-create-level

移交至

sumsub-create-level

技能

The

id

returned here (the questionnaire slug) is what you pass on a level's

QUESTIONNAIRE

doc-set. The level skill accepts it as

questionnaireDefId

(canonical) or

questionnaireId

(alias):

json

{
  "type": "QUESTIONNAIRE",
  "questionnaireDefId": "<id from this skill>"
}

See

sumsub-create-level/examples/with-presets.json

本技能返回的

id

（问卷slug）需传入等级的

QUESTIONNAIRE

文档集中。等级技能接受

questionnaireDefId

（标准参数）或

questionnaireId

（别名参数）：

json

{
  "type": "QUESTIONNAIRE",
  "questionnaireDefId": "<本技能返回的id>"
}

示例请查看

sumsub-create-level/examples/with-presets.json

。

sumsub-create-questionnaire

Original

Translation

Sumsub — Create Questionnaire

Sumsub — 创建问卷

Endpoints

接口端点

Auth — App Token + secret (sandbox only)

认证 — App Token + 密钥（仅限沙箱环境）

Tenant entitlements

租户权限

Procedure

操作流程

Compact spec format

简洁规范格式

Supported item types

支持的条目类型

Outputs

输出结果

Names, not ids, in user-facing messages

用户消息中使用名称而非ID

Hand-off to
`sumsub-create-level`

移交至
`sumsub-create-level`
技能

See also

相关链接

sumsub-create-questionnaire

Original

Translation

Sumsub — Create Questionnaire

Sumsub — 创建问卷

Endpoints

接口端点

Auth — App Token + secret (sandbox only)

认证 — App Token + 密钥（仅限沙箱环境）

Tenant entitlements

租户权限

Procedure

操作流程

Compact spec format

简洁规范格式

Supported item types

支持的条目类型

Outputs

输出结果

Names, not ids, in user-facing messages

用户消息中使用名称而非ID

Hand-off to sumsub-create-level

移交至sumsub-create-level技能

See also

相关链接

Hand-off to
`sumsub-create-level`

移交至
`sumsub-create-level`
技能