sumsub-create-level

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sumsub — Create Level

Sumsub — 创建等级

Builds an

ApplicantLevel

JSON payload from a compact spec, POSTs (or PATCHes) it to the Sumsub API, and reports the resulting

name

id

根据紧凑规范生成

ApplicantLevel

JSON负载，通过POST（或PATCH）请求发送至Sumsub API，并返回生成的

name

id

。

Endpoints

接口端点

Method	Path	When
`POST`	`/resources/applicants/-/levels`	Create a new level. Body must NOT include `id` or `key` — server assigns them.
`PATCH`	`/resources/applicants/-/levels`	Update an existing level (by `id` in body).
`GET`	`/resources/applicants/-/levels/{id}`	Read one level. Use this to verify what landed (tenant gates may silently drop fields) or to resolve `name` from a known `id` .
`GET`	`/resources/applicants/-/levels`	List all levels (use to reuse existing levels before creating duplicates).

Body:

ApplicantLevel

. Returns the persisted level with

id

createdAt

, audit trails.

方法	路径	适用场景
`POST`	`/resources/applicants/-/levels`	创建新等级。请求体不得包含 `id` 或 `key` ——由服务器分配。
`PATCH`	`/resources/applicants/-/levels`	更新现有等级（需在请求体中传入 `id` ）。
`GET`	`/resources/applicants/-/levels/{id}`	读取单个等级信息。用于验证提交内容是否生效（租户权限可能会静默丢弃字段），或通过已知 `id` 查询对应的 `name` 。
`GET`	`/resources/applicants/-/levels`	列出所有等级（用于创建重复等级前复用已有等级）。

请求体：

ApplicantLevel

。返回包含

id

、

createdAt

和审计追踪信息的已持久化等级。

Auth — App Token + secret (sandbox only)

认证——应用令牌+密钥（仅沙箱环境）

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 — creating a level is a workspace-visible write. If the user offers a prod token, 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

错误，请查阅该文档。

⚠️ 仅支持沙箱令牌。 请勿接受或使用生产环境的应用令牌 ——创建等级是对共享工作区的写入操作。如果用户提供生产环境令牌，请拒绝并要求他们在https://cockpit.sumsub.com/checkus/devSpace/appTokens生成沙箱环境的令牌密钥对（先将工作区切换为Sandbox，再点击Create）。令牌和密钥仅显示一次——请在关闭对话框前复制两者。辅助脚本会强制验证这一点——拒绝所有不以
sbx:
开头的令牌。

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

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

Procedure

操作流程

Fetch tenant entitlements. Invoke the
```
sumsub-check-permissions
```
skill and parse the JSON result. Store the
```
allowed
```
array; use it for all feature-gate checks in step 2 and the entitlements section below. Do this before anything else.
Check existing entities. Before building anything, list existing levels, POA presets, and questionnaires (GET the respective list endpoints). If a matching entity already exists, offer to reuse its
```
id
```
and skip the POST — the server creates a duplicate on every POST with no name deduplication.
Translate the user's request to the compact spec below — name, applicant type, and a list of doc-set steps in the order they should appear in the WebSDK flow.
Validate — confirm every
```
type
```
is a real
```
IdDocSetType
```
, every
```
QUESTIONNAIRE
```
step has a
```
questionnaireDefId
```
that points to an existing questionnaire, every
```
PROOF_OF_RESIDENCE*
```
step has a
```
poaPresetId
```
/
```
poaStepSettingsId
```
(the server rejects the level if it's missing — run
```
sumsub-create-poa-preset
```
first if no preset exists), every
```
COMPANY
```
step has at least one named sub-step. Use the
```
allowed
```
array from step 0 to reject any entitlement-gated feature not present in it.
Generate payload — run
```
${CLAUDE_SKILL_DIR}/scripts/build_level.py
```
with the spec on stdin → full payload on stdout.
Show the resolved payload to the user and ask for explicit confirmation before the first POST.
Create vs. update:
- New level — POST via
```
${CLAUDE_SKILL_DIR}/scripts/post_level.sh
```
  . Returns response body + HTTP status.
- Update existing — GET the current state via
```
${CLAUDE_SKILL_DIR}/scripts/get_level.sh
```
  so the user sees the diff, then PATCH via
```
${CLAUDE_SKILL_DIR}/scripts/patch_level.sh
```
  . The spec passed to
  build_level.py
  must include
  id: <level-id>
  — the builder preserves it into the payload, and PATCH refuses bodies without it. PATCH replaces
  requiredIdDocs.docSets
  as a single array — every docSet you send must carry the full intended state, since fields omitted from a docSet are wiped on the server. Copy preserved values from the GET response into your PATCH spec.
GET the level back via
```
${CLAUDE_SKILL_DIR}/scripts/get_level.sh
```
and compare to what was sent — several fields land differently from what was sent (see gotchas in references/level-schema.md). Report any discrepancy to the user.
Build the dashboard link. Read
```
id
```
,
```
applicantType
```
, and
```
clientId
```
from the response body and format:
```
https://cockpit.sumsub.com/checkus/sdkIntegrations/levels/<applicantType>Level/<id>?clientId=<clientId>&xSNSEnv=sbx
```
The
```
<applicantType>Level
```
segment is literally
```
individualLevel
```
for
```
applicantType: individual
```
(confirmed) and
```
companyLevel
```
for
```
applicantType: company
```
(assumed by analogy — surface as the best guess and flag if it 404s). 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 name:
- ```
name
```
  ,
```
applicantType
```
  , ordered list of docSets created.
- Dashboard link as a clickable markdown link.
- Final line:
```
Level ID (for SDK access tokens / future PATCH): <id>
```
  .
Surface 4xx errors verbatim — they usually point to a missing
```
questionnaireDefId
```
or an unknown enum value.

获取租户权限。调用
```
sumsub-check-permissions
```
技能并解析JSON结果。存储
```
allowed
```
数组；在步骤2和下文权限章节的所有功能权限检查中使用该数组。这一步需优先执行。
检查现有实体。在构建任何内容之前，列出所有现有等级、居住证明预设和问卷（调用对应的列表接口）。如果存在匹配的实体，建议复用其
```
id
```
并跳过POST请求——服务器每次POST都会创建重复项，不会对名称进行去重。
将用户请求转换为下文的紧凑规范——包括名称、申请人类型，以及在WebSDK流程中应显示的文档集步骤列表。
验证——确认每个
```
type
```
都是有效的
```
IdDocSetType
```
，每个
```
QUESTIONNAIRE
```
步骤都包含指向现有问卷的
```
questionnaireDefId
```
，每个
```
PROOF_OF_RESIDENCE*
```
步骤都包含
```
poaPresetId
```
/
```
poaStepSettingsId
```
（如果缺少该参数，服务器会拒绝创建等级——如果没有预设，请先运行
```
sumsub-create-poa-preset
```
），每个
```
COMPANY
```
步骤至少包含一个命名子步骤。使用步骤0中获取的
```
allowed
```
数组拒绝任何租户未拥有权限的功能。
生成负载——通过标准输入将规范传入
```
${CLAUDE_SKILL_DIR}/scripts/build_level.py
```
，标准输出即为完整负载。
向用户展示解析后的负载并请求明确确认，然后执行首次POST请求。
创建 vs 更新:
- 新等级——通过
```
${CLAUDE_SKILL_DIR}/scripts/post_level.sh
```
  执行POST请求。返回响应体和HTTP状态码。
- 更新现有等级——通过
```
${CLAUDE_SKILL_DIR}/scripts/get_level.sh
```
  获取当前状态以便用户查看差异，然后通过
```
${CLAUDE_SKILL_DIR}/scripts/patch_level.sh
```
  执行PATCH请求。传入
  build_level.py
  的规范必须包含
  id: <level-id>
  ——构建器会将其保留在负载中，且PATCH请求拒绝不包含该参数的请求体。PATCH请求会完全替换
  requiredIdDocs.docSets
  数组——发送的每个文档集必须包含完整的预期状态，因为文档集中省略的字段会被服务器清空。请从GET响应中复制需要保留的值到PATCH规范中。
重新获取等级信息——通过
```
${CLAUDE_SKILL_DIR}/scripts/get_level.sh
```
获取等级，并与发送的内容进行比较——部分字段的实际存储结果可能与发送内容不同（详见references/level-schema.md中的注意事项）。向用户报告任何差异。
生成控制台链接。从响应体中读取
```
id
```
、
```
applicantType
```
和
```
clientId
```
，并格式化为：
```
https://cockpit.sumsub.com/checkus/sdkIntegrations/levels/<applicantType>Level/<id>?clientId=<clientId>&xSNSEnv=sbx
```
```
<applicantType>Level
```
部分对于
```
applicantType: individual
```
为
```
individualLevel
```
（已确认），对于
```
applicantType: company
```
为
```
companyLevel
```
（类推得出——作为最佳猜测展示，如果返回404请标记）。
```
xSNSEnv=sbx
```
查询参数指向Sandbox工作区——这是所有技能通用的标准沙箱链接参数。
结果报告——以易读的名称开头：
- ```
name
```
  、
```
applicantType
```
  、已创建的文档集有序列表。
- 控制台链接：以可点击的markdown链接形式展示。
- 最后一行：
```
等级ID（用于SDK访问令牌/后续PATCH请求）: <id>
```
  。
直接展示4xx错误信息——这些错误通常指向缺失的
```
questionnaireDefId
```
或未知的枚举值。

Tenant entitlements

租户权限

Many level settings are gated behind tenant entitlements (

allowedChecks

). Before enabling a feature, check that the required

BackgroundCheckTarget

is present in the

allowed

array returned by

sumsub-check-permissions

(fetched in step 0).

DocSet type → required permission (OR — any one suffices):

DocSet type	Required (any one of)
`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` (often missing from `allowedChecks` even when the API actually allows it — proceed with a one-line warning; see below)
`E_KYC`	`E_KYC_TARGET`
`E_SIGN`	`E_SIGN_TARGET`
`TR_RECIPIENT_INFORMATION`	`TRAVEL_RULE`
`DEVICE_CHECK`	`DEVICE_INTELLIGENCE`

Types not in this table (

IDENTITY

SELFIE

APPLICANT_DATA

EMAIL_VERIFICATION

PHONE_VERIFICATION

, etc.) are available to all tenants — no entitlement required.

If a requested feature requires an entitlement the tenant doesn't have — stop immediately. Do not build or POST the level. Tell the user which entitlement is missing, that the feature is unavailable on their account, and that they need to contact their CSM or Sumsub support to get it enabled. Resume only after the user confirms the entitlement has been added or explicitly decides to drop the feature.

Exception — POA. The

POA

ADVANCED_POA_TYPE_DETECTION

keys are often absent from

allowedChecks

even on tenants where the API actually accepts

PROOF_OF_RESIDENCE

levels (the entitlement seems to be baseline or covered by other keys; the documented mapping is stale on some tenants). When only

POA

is missing, proceed with a one-line warning to the user so they have context if support is later needed. Do NOT pause for explicit confirmation — Sumsub itself will reject the write if the tenant truly lacks the right, and that 4xx will be more informative than a pre-emptive halt. Surface any entitlement-related error verbatim if it comes back.

许多等级设置受租户权限（

allowedChecks

）限制。启用某项功能前，请检查

sumsub-check-permissions

技能返回的

allowed

数组（步骤0中获取）中是否包含所需的

BackgroundCheckTarget

。

文档集类型 → 所需权限（满足任意一项即可）：

文档集类型	所需权限（任意一项）
`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` ——请继续执行并向用户显示一行警告；详见下文）
`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

等）对所有租户可用——无需权限。

如果用户请求的功能需要租户未拥有的权限——立即停止操作。 请勿构建或POST等级。告知用户缺少的权限名称、该功能在其账户中不可用，以及他们需要联系客户成功经理或Sumsub支持团队启用该功能。仅在用户确认权限已添加或明确决定放弃该功能后再继续。

例外情况——居住证明（POA）。 即使租户的API实际接受

PROOF_OF_RESIDENCE

等级，

POA

ADVANCED_POA_TYPE_DETECTION

密钥也常缺失于

allowedChecks

（该权限似乎是基础权限或由其他密钥覆盖；部分租户的文档映射已过时）。当仅缺少

POA

权限时，继续执行并向用户显示一行警告，以便后续需要支持时用户了解背景情况。无需等待用户明确确认——如果租户确实缺少权限，Sumsub会自行拒绝写入操作，且返回的4xx错误比预先停止操作更具参考价值。如果返回与权限相关的错误，请直接展示给用户。

Safety

安全注意事项

Creating a level is a write to a shared workspace. Always:

Show the resolved payload to the user before the first POST (step 4 above).
After each successful POST, GET the entity back and compare to what was sent — silent overrides are common.
Do not re-POST a dependency (PoA preset, questionnaire) if it already succeeded mid-session — reuse the returned
```
id
```
.
Do not delete or modify levels you didn't create in this session unless the user explicitly names them.

创建等级是对共享工作区的写入操作。请始终遵守以下规则：

在首次POST前向用户展示解析后的负载（上文步骤4）。
每次POST成功后，重新获取实体并与发送内容进行比较——静默覆盖是常见情况。
如果依赖项（居住证明预设、问卷）已在会话中创建成功，请勿重新POST——复用返回的
```
id
```
。
除非用户明确指定，否则请勿删除或修改本次会话中未创建的等级。

Names, not ids, in user-facing messages

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

This applies to every message you send the user about this level — not just the final report:

Pre-POST summary: when you list which questionnaire and which POA preset will be attached, refer to each by
```
name
```
/
```
title
```
(e.g. "POA preset «POA — 60 days»", "questionnaire «Applicant basics»"). Do not paste the raw
```
id
```
("
```
6a16bfd4ded0fe13aa48165d
```
") into prose — the user can't read it and it does not let them judge whether you picked the right entity.
Final report: still ends with
```
Level ID (for SDK access tokens / future PATCH): <id>
```
on its own line — that line is the one place a raw id is correct, because the user needs to copy it for the next API call.
Diagnostic messages: when a 4xx response references a dependency id (POA preset not found, etc.), translate it to the name before showing the user.

If you don't yet know an entity's name (e.g. user supplied only an id from outside this session), GET the entity first and surface its name; do not fall back to the id.

此规则适用于所有发送给用户的关于本等级的消息——不仅限于最终报告：

POST前摘要：当列出要关联的问卷和居住证明预设时，请使用
```
name
```
/
```
title
```
指代（例如：“居住证明预设«POA — 60天»”、“问卷«申请人基础信息»”）。请勿在文本中粘贴原始
```
id
```
（如“
```
6a16bfd4ded0fe13aa48165d
```
”）——用户无法识别该ID，也无法判断是否选择了正确的实体。
最终报告：仍需在单独一行显示
```
等级ID（用于SDK访问令牌/后续PATCH请求）: <id>
```
——这是唯一适合显示原始ID的位置，因为用户需要复制该ID用于后续API调用。
诊断消息：当4xx响应引用依赖项ID（如居住证明预设未找到等）时，请先将其转换为名称再展示给用户。

如果尚未知晓实体的名称（例如用户仅提供了会话外的ID），请先获取实体信息并展示其名称；切勿直接使用ID。

Compact spec format

紧凑规范格式

Accepts JSON or YAML on stdin. The builder fills in sensible defaults for each doc-set type (see references/level-schema.md).

json

{
  "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"}
  ]
}

接受标准输入的JSON或YAML格式。构建器会为每种文档集类型填充合理的默认值（详见references/level-schema.md）。

json

{
  "name": "基础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"}
  ]
}

Supported

docSets[].type

values

支持的

docSets[].type

值

APPLICANT_DATA

EMAIL_VERIFICATION

PHONE_VERIFICATION

IDENTITY

IDENTITY2

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

E_KYC

OTHER_DOCS

TR_RECIPIENT_INFORMATION

DEVICE_CHECK

APPLICANT_DATA

EMAIL_VERIFICATION

PHONE_VERIFICATION

IDENTITY

IDENTITY2

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

E_KYC

OTHER_DOCS

TR_RECIPIENT_INFORMATION

DEVICE_CHECK

。

Per-type compact shortcuts

按类型划分的紧凑快捷方式

`type`	Shortcut keys	Builder expands to
`IDENTITY*`	`docTypes` ; `videoRequired` ( `disabled` / `docapture` ); `captureMode` & `uploaderMode` (sent only when docapture); `nfcVerificationSettings: {mode}`	flat fields on the docSet — only what you set. See Dashboard ↔ API mapping below.
`SELFIE*`	`videoRequired` (default `passiveLiveness` ; full set: `disabled` / `enabled` / `photoRequired` / `passiveLiveness` / `staticLiveness` ), `docTypes` (default `["SELFIE"]` ); `selfieProcessingSettings: {skipLivenessCheck, skipFaceMatchCheck}` (used with payment-method verification — see below)	bare docSet with `videoRequired` [+ `selfieProcessingSettings` ]
`PROOF_OF_RESIDENCE*`	`docTypes` (default `["UTILITY_BILL"]` ); `poaPresetId` (or `poaStepSettingsId` ) to attach a POA preset by id	docSet + `poaStepSettingsId`
`QUESTIONNAIRE*`	`questionnaireDefId` (or `questionnaireId` alias) — required	bare docSet
`APPLICANT_DATA`	`fields` — array of strings or `{name, required, prefill, immutableIfPresent}`	`fields[]` with defaults
`PAYMENT_METHODS`	`typeSettings` (object — keys: `bankCard` , `bankAccount` , `cryptoWallet` , `eWallet` — see Payment method verification below); `skipOwnershipCheck` (bool, default `false` ); `skipRiskScoreCheck` (bool); `walletScreeningProvider` (enum — see schema)	`paymentSourceSettings` with validated structure; always emits `types: ["PAYMENT_SOURCE"]`
`EMAIL_VERIFICATION` / `PHONE_VERIFICATION`	—	bare docSet
`COMPANY`	`steps` — array of `{name, minDocsCnt?, idDocTypes?, idDocSubTypes?, fields?, applicantLevelName?}`	full KYB step structure
`E_SIGN`	`esignSettings` (pass-through)	as-is

Unknown keys in a docSet are passed through to the API verbatim, so escape hatches are easy when you need an obscure field.

`type`	快捷参数	构建器展开结果
`IDENTITY*`	`docTypes` ； `videoRequired` （ `disabled` / `docapture` ）； `captureMode` 和 `uploaderMode` （仅当使用docapture时发送）； `nfcVerificationSettings: {mode}`	文档集的扁平字段——仅包含您设置的内容。详见下文控制台↔API映射。
`SELFIE*`	`videoRequired` （默认 `passiveLiveness` ；可选值： `disabled` / `enabled` / `photoRequired` / `passiveLiveness` / `staticLiveness` ）， `docTypes` （默认 `["SELFIE"]` ）； `selfieProcessingSettings: {skipLivenessCheck, skipFaceMatchCheck}` （用于支付方式验证——详见下文）	包含 `videoRequired` [+ `selfieProcessingSettings` ]的基础文档集
`PROOF_OF_RESIDENCE*`	`docTypes` （默认 `["UTILITY_BILL"]` ）；`poaPresetId` （或 `poaStepSettingsId` ）——通过ID关联居住证明预设	文档集 + `poaStepSettingsId`
`QUESTIONNAIRE*`	`questionnaireDefId` （或别名 `questionnaireId` ）——必填	基础文档集
`APPLICANT_DATA`	`fields` ——字符串数组或 `{name, required, prefill, immutableIfPresent}` 对象数组	包含默认值的 `fields[]`
`PAYMENT_METHODS`	`typeSettings` （对象——键值： `bankCard` , `bankAccount` , `cryptoWallet` , `eWallet` ——详见下文支付方式验证步骤或操作）； `skipOwnershipCheck` （布尔值，默认 `false` ）； `skipRiskScoreCheck` （布尔值）； `walletScreeningProvider` （枚举值——详见 schema）	经过结构验证的 `paymentSourceSettings` ；始终生成 `types: ["PAYMENT_SOURCE"]`
`EMAIL_VERIFICATION` / `PHONE_VERIFICATION`	——	基础文档集
`COMPANY`	`steps` —— `{name, minDocsCnt?, idDocTypes?, idDocSubTypes?, fields?, applicantLevelName?}` 对象数组	完整的KYB步骤结构
`E_SIGN`	`esignSettings` （直接传递）	原样保留

文档集中的未知参数会直接传递给API，因此当您需要使用冷门字段时可以轻松实现。

Dashboard ↔ API mapping for IDENTITY step

身份验证步骤的控制台↔API映射

Verbatim labels from the Sumsub dashboard sidebar, paired with the API value to write. Match the user's description to a label, then use the value.

Dashboard control	Label (user-visible)	API value	Spec key
Capture method	File upload	`disabled`	`videoRequired`
Capture method	Live capture	`docapture`	`videoRequired`
Capture mode¹	Both manual and auto capture work at the same time	`manualAndAuto`	`captureMode`
Capture mode¹	Only manual capture is active	`manualOnly`	`captureMode`
Capture mode¹	Seamless live capture	`seamless`	`captureMode`
Fallback to file upload¹	Always available	`always`	`uploaderMode`
Fallback to file upload¹	Available only if camera capture failed	`fallback`	`uploaderMode`
Fallback to file upload¹	Not available	`never`	`uploaderMode`
NFC verification²	Disabled	`disabled`	`nfcVerificationSettings.mode`
NFC verification²	Optional	`optional`	`nfcVerificationSettings.mode`
NFC verification²	Required	`required`	`nfcVerificationSettings.mode`

¹ Only meaningful with

videoRequired: docapture

. Silently dropped from the payload otherwise (matches the dashboard's own behavior — it deletes both keys when the radio is toggled to File upload). ²

required

auto-rejects Web SDK applicants; Mobile SDK only.

Defaults emitted by the builder (necessary for the dashboard to render — the controls bind to actual stored values, not implicit UI defaults; empty fields render as "Select" placeholder, not as the default option):

videoRequired: docapture

→

captureMode: manualAndAuto

uploaderMode: always

(unless caller overrides).

IDENTITY always gets
```
nfcVerificationSettings: {mode: disabled}
```
unless caller overrides.

These match what the dashboard's own Vue watcher writes when the user first toggles Live capture. Caveat on PATCH:

requiredIdDocs.docSets

is replaced wholesale (only top-level Level fields merge) — every docSet in the PATCH spec must carry the full intended state, since omitted sub-fields are wiped. GET the level first and copy values you want to preserve.

Sumsub控制台侧边栏的原始标签，与对应的API值配对。将用户描述与标签匹配，然后使用对应的API值。

控制台控件	用户可见标签	API值	规范参数
采集方式	文件上传	`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

会被完全替换（仅顶级等级字段会合并）——PATCH规范中的每个文档集必须包含完整的预期状态，因为省略的子字段会被清空。请先获取等级信息，然后复制需要保留的值。

Payment method verification (step or action)

支付方式验证（步骤或操作）

Payment method verification — the

PAYMENT_METHODS

docSet, for verifying a bank card, bank account, crypto wallet, or e-wallet — runs in two modes:

As a step in a normal verification level: add a
```
PAYMENT_METHODS
```
docSet alongside
```
IDENTITY
```
/
```
SELFIE
```
/
```
PROOF_OF_RESIDENCE
```
/ etc. The level stays a regular
```
standalone
```
level with no
```
actionType
```
. Use this when payment verification is one part of a broader onboarding flow.
As an action on an actions-type level: set
```
type: "actions"
```
and
```
actionType: "paymentMethod"
```
. Use this for a standalone, re-runnable payment-method check decoupled from onboarding.

Pick the mode from how the user frames it — "add card/wallet verification to my KYC level" → step; "create a standalone payment-method check / action" → action.

Step mode — inside a standard level (identity and payment coexist):

json

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

Action mode — inside an actions level:

json

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

Constraints the builder enforces:

actionType: "paymentMethod"

requires

type: "actions"

, and the level must include a

PAYMENT_METHODS

docSet.

Cannot set both

skipOwnershipCheck: true

and

skipRiskScoreCheck: true

simultaneously.

walletScreeningProvider

goes at the

paymentSourceSettings

level, not inside

typeSettings.cryptoWallet

(the builder places it correctly).

bankAccount
needs a concrete verification method. Unlike
```
bankCard
```
, enabling a bank account with
```
allowed: true
```
alone is rejected by the API — it must enable at least one of
```
allowBankStatementUpload
```
(statement upload, no extra entitlement) or
```
allowExternalSourcesCheck
```
(external data-source check, uses the
```
E_KYC
```
entitlement). Ask the user which method(s) they want; don't offer a bare "standard" bank-account option.

The
PAYMENT_METHODS
docSet (both modes): the builder always emits

types: ["PAYMENT_SOURCE"]

plus a

paymentSourceSettings

object assembled from your compact spec — the API rejects the docSet without

paymentSourceSettings

, so the builder never omits it.

typeSettings
per payment source type:

Key	Fields
`bankCard`	`allowed` (bool); `countImages` ( `"one"` / `"two"` / `"some"` ); `extractIban` (bool); `extractNationalBankAccountNumbers` (bool); `requireBankAccountNumber` (bool)
`bankAccount`	`allowed` (bool); `allowBankStatementUpload` (bool); `allowExternalSourcesCheck` (bool — requires `E_KYC_TARGET` entitlement). When `allowed` , at least one of these two methods must be `true` — see constraints above.
`cryptoWallet`	`allowed` (bool); `satoshiTestAllowed` (bool); `unhostedWalletFormType` ( `"DEFAULT"` / `"SIMPLE"` / `"KAZ"` / `"TUR"` / `"SGP"` / `"POL"` / `"ITA"` )
`eWallet`	`allowed` (bool)

walletScreeningProvider
enum:

crystal

merkle

trmLabs

chainalysis

elliptic

cyvers

Entitlement: requires

PAYMENT_SOURCE

KYT_UNHOSTED_WALLET_VERIFICATION

(see Tenant entitlements).

Dashboard link: both modes live under

sdkIntegrations/levels/individualLevel/<id>

— the standard standalone-level URL pattern.

See

examples/payment-methods.json

for a complete action-mode spec.

支付方式验证——即

PAYMENT_METHODS

文档集，用于验证银行卡、银行账户、加密钱包或电子钱包——支持两种模式：

作为普通验证等级中的步骤：在
```
IDENTITY
```
/
```
SELFIE
```
/
```
PROOF_OF_RESIDENCE
```
等文档集之外添加
```
PAYMENT_METHODS
```
文档集。等级保持为常规的
```
standalone
```
等级，不设置
```
actionType
```
。当支付验证是 broader 入职流程的一部分时使用此模式。
作为操作类型等级中的操作：设置
```
type: "actions"
```
和
```
actionType: "paymentMethod"
```
。用于独立于入职流程的可重复执行的支付方式检查。

根据用户的描述选择模式——“在我的KYC等级中添加卡片/钱包验证”→步骤模式；“创建独立的支付方式检查/操作”→操作模式。

步骤模式——在标准等级中（身份验证和支付验证共存）：

json

{
  "name": "KYC + 支付方式验证",
  "type": "standalone",
  "applicantType": "individual",
  "docSets": [
    {"type": "IDENTITY"},
    {"type": "SELFIE", "videoRequired": "passiveLiveness"},
    {"type": "PAYMENT_METHODS",
     "typeSettings": {"bankCard": {"allowed": true, "countImages": "one"}}}
  ]
}

操作模式——在操作类型等级中：

json

{
  "name": "支付方式检查",
  "type": "actions",
  "actionType": "paymentMethod",
  "websdkNext": true,
  "docSets": [
    {"type": "PAYMENT_METHODS", "skipOwnershipCheck": false,
     "typeSettings": {"bankCard": {"allowed": true, "countImages": "one"}}}
  ]
}

构建器强制执行的约束：

actionType: "paymentMethod"

要求

type: "actions"

，且等级必须包含

PAYMENT_METHODS

文档集。

不能同时设置

skipOwnershipCheck: true

和

skipRiskScoreCheck: true

。

```
walletScreeningProvider
```
应设置在
```
paymentSourceSettings
```
层级，而非
```
typeSettings.cryptoWallet
```
内部（构建器会将其放置在正确位置）。
bankAccount
需要具体的验证方式。与
```
bankCard
```
不同，仅设置
```
allowed: true
```
启用银行账户会被API拒绝——必须至少启用
```
allowBankStatementUpload
```
（账单上传，无需额外权限）或
```
allowExternalSourcesCheck
```
（外部数据源检查，需要
```
E_KYC
```
权限）中的一项。请询问用户想要使用哪种方式；不要提供单纯的“标准”银行账户选项。

PAYMENT_METHODS
文档集（两种模式）：构建器始终会生成

types: ["PAYMENT_SOURCE"]

以及根据紧凑规范组装的

paymentSourceSettings

对象——API会拒绝不包含

paymentSourceSettings

的文档集，因此构建器不会省略该参数。

各支付来源类型的
typeSettings
：

键	字段
`bankCard`	`allowed` （布尔值）； `countImages` （ `"one"` / `"two"` / `"some"` ）； `extractIban` （布尔值）； `extractNationalBankAccountNumbers` （布尔值）； `requireBankAccountNumber` （布尔值）
`bankAccount`	`allowed` （布尔值）； `allowBankStatementUpload` （布尔值）； `allowExternalSourcesCheck` （布尔值——需要 `E_KYC_TARGET` 权限）。当 `allowed` 为true时，至少需要将这两种方式中的一种设置为true——详见上文约束。
`cryptoWallet`	`allowed` （布尔值）； `satoshiTestAllowed` （布尔值）； `unhostedWalletFormType` （ `"DEFAULT"` / `"SIMPLE"` / `"KAZ"` / `"TUR"` / `"SGP"` / `"POL"` / `"ITA"` ）
`eWallet`	`allowed` （布尔值）

walletScreeningProvider
枚举值：

crystal

merkle

trmLabs

chainalysis

elliptic

cyvers

权限要求：需要

PAYMENT_SOURCE

或

KYT_UNHOSTED_WALLET_VERIFICATION

权限（详见租户权限）。

控制台链接：两种模式的链接均为

sdkIntegrations/levels/individualLevel/<id>

——标准独立等级URL格式。

完整的操作模式规范示例请见

examples/payment-methods.json

。

Chaining with other Sumsub-* skills

与其他Sumsub-*技能联动

This skill's

QUESTIONNAIRE

and

PROOF_OF_RESIDENCE

doc-sets accept ids produced by sibling skills, so a 3-step build-everything-from-scratch flow is natural:

First run …	Pass the returned `id` as …
`sumsub-create-questionnaire`	`docSets[].questionnaireDefId` on a `QUESTIONNAIRE` doc-set
`sumsub-create-poa-preset`	`docSets[].poaPresetId` on a `PROOF_OF_RESIDENCE` doc-set

See

examples/with-presets.json

for an end-to-end level that references both.

本技能的

QUESTIONNAIRE

和

PROOF_OF_RESIDENCE

文档集接受同级技能生成的ID，因此可以自然实现从无到有构建所有内容的三步流程：

先运行…	将返回的 `id` 作为…传入
`sumsub-create-questionnaire`	`QUESTIONNAIRE` 文档集的 `docSets[].questionnaireDefId`
`sumsub-create-poa-preset`	`PROOF_OF_RESIDENCE` 文档集的 `docSets[].poaPresetId`

同时引用问卷和居住证明预设的完整等级示例请见

examples/with-presets.json

。

Outputs

输出结果

On success, lead with the human-readable info:

```
name
```
,
```
applicantType
```
, ordered list of
```
docSets[].idDocSetType
```
.
Dashboard link:
```
https://cockpit.sumsub.com/checkus/sdkIntegrations/levels/<applicantType>Level/<id>?clientId=<clientId>&xSNSEnv=sbx
```
. Render as a clickable markdown link. The
```
<applicantType>Level
```
segment is
```
individualLevel
```
for individuals (confirmed) or
```
companyLevel
```
for companies (assumed pattern). All three fields (
```
id
```
,
```
applicantType
```
,
```
clientId
```
) come from the POST response body;
```
xSNSEnv=sbx
```
targets the Sandbox workspace.

Finally, on its own line:

Level ID (for SDK access tokens / future PATCH): <id>

On failure: HTTP status + the

description

errorName

from Sumsub's error envelope.

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

```
name
```
、
```
applicantType
```
、
```
docSets[].idDocSetType
```
的有序列表。
控制台链接：
```
https://cockpit.sumsub.com/checkus/sdkIntegrations/levels/<applicantType>Level/<id>?clientId=<clientId>&xSNSEnv=sbx
```
。以可点击的markdown链接形式展示。
```
<applicantType>Level
```
部分对于个人为
```
individualLevel
```
（已确认），对于企业为
```
companyLevel
```
（类推模式）。三个字段（
```
id
```
、
```
applicantType
```
、
```
clientId
```
）均来自POST响应体；
```
xSNSEnv=sbx
```
指向沙箱工作区。

最后，单独一行显示：

等级ID（用于SDK访问令牌/后续PATCH请求）: <id>

。

失败时：显示HTTP状态码 + Sumsub错误包中的

description

errorName

。

Worked examples

示例

```
examples/identity-selfie.json
```
— the most common pattern.
```
examples/identity-live-capture.json
```
— IDENTITY-only with Live capture + all docapture sub-options + NFC.
```
examples/questionnaire-only.json
```
— pure data-collection level (like the SOF level in this repo).

examples/full-kyc.json

—

APPLICANT_DATA + IDENTITY + SELFIE + PROOF_OF_RESIDENCE + QUESTIONNAIRE

```
examples/kyb-company.json
```
— KYB level with company + UBOs + representatives steps.
```
examples/with-presets.json
```
— references both a questionnaire (
```
questionnaireDefId
```
) and a POA preset (
```
poaPresetId
```
) returned by sibling skills.
```
examples/payment-methods.json
```
— payment method action level with bank card, bank account, crypto wallet, and e-wallet.

```
examples/identity-selfie.json
```
——最常见的模式。
```
examples/identity-live-capture.json
```
——仅包含身份验证，启用实时采集+所有docapture子选项+NFC。
```
examples/questionnaire-only.json
```
——纯数据收集等级（如本仓库中的SOF等级）。

examples/full-kyc.json

——

APPLICANT_DATA + IDENTITY + SELFIE + PROOF_OF_RESIDENCE + QUESTIONNAIRE

。

```
examples/kyb-company.json
```
——包含企业+最终受益人+代表步骤的KYB等级。
```
examples/with-presets.json
```
——同时引用同级技能返回的问卷（
```
questionnaireDefId
```
）和居住证明预设（
```
poaPresetId
```
）。
```
examples/payment-methods.json
```
——包含银行卡、银行账户、加密钱包和电子钱包的支付方式操作等级。

另请参阅

references/level-schema.md — full
```
ApplicantLevel
```
schema, all enum values, gotchas.

references/level-schema.md ——完整的
```
ApplicantLevel
```
schema、所有枚举值和注意事项。

sumsub-create-level

Original

Translation

Sumsub — Create Level

Sumsub — 创建等级

Endpoints

接口端点

Auth — App Token + secret (sandbox only)

认证——应用令牌+密钥（仅沙箱环境）

Procedure

操作流程

Tenant entitlements

租户权限

Safety

安全注意事项

Names, not ids, in user-facing messages

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

Compact spec format

紧凑规范格式

Supported
`docSets[].type`
values

支持的
`docSets[].type`
值

Per-type compact shortcuts

按类型划分的紧凑快捷方式

Dashboard ↔ API mapping for IDENTITY step

身份验证步骤的控制台↔API映射

Payment method verification (step or action)

支付方式验证（步骤或操作）

Chaining with other Sumsub-* skills

与其他Sumsub-*技能联动

Outputs

输出结果

Worked examples

示例

See also

另请参阅

sumsub-create-level

Original

Translation

Sumsub — Create Level

Sumsub — 创建等级

Endpoints

接口端点

Auth — App Token + secret (sandbox only)

认证——应用令牌+密钥（仅沙箱环境）

Procedure

操作流程

Tenant entitlements

租户权限

Safety

安全注意事项

Names, not ids, in user-facing messages

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

Compact spec format

紧凑规范格式

Supported docSets[].type values

支持的docSets[].type值

Per-type compact shortcuts

按类型划分的紧凑快捷方式

Dashboard ↔ API mapping for IDENTITY step

身份验证步骤的控制台↔API映射

Payment method verification (step or action)

支付方式验证（步骤或操作）

Chaining with other Sumsub-* skills

与其他Sumsub-*技能联动

Outputs

输出结果

Worked examples

示例

See also

另请参阅

Supported
`docSets[].type`
values

支持的
`docSets[].type`
值