sumsub-create-poa-preset

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sumsub — Create POA Preset

Sumsub — 创建POA预设

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

id

so it can be attached to one or more levels via

level.requiredIdDocs.docSets[].poaStepSettingsId

Prerequisite — level must have a PROOF_OF_RESIDENCE step. A POA preset has no effect unless it is attached to a
PROOF_OF_RESIDENCE
(or
PROOF_OF_RESIDENCE2
/
3
/
4
) docset in at least one level. If the user hasn't created (or described) a level that includes a POA step, surface this before building the preset — there is no point creating it in isolation.

根据精简规范构建POA预设JSON负载，将其POST至Sumsub API，并返回生成的预设

id

，以便通过

level.requiredIdDocs.docSets[].poaStepSettingsId

关联到一个或多个等级。

前提条件 — 等级必须包含PROOF_OF_RESIDENCE步骤。POA预设只有关联到至少一个等级中的
PROOF_OF_RESIDENCE
（或
PROOF_OF_RESIDENCE2
/
3
/
4
）文档集时才会生效。如果用户尚未创建（或描述）包含POA步骤的等级，请在构建预设前告知用户——单独创建预设没有意义。

Endpoints

端点

Method	Path	When
`POST`	`/resources/api/agent/poaStepSettings`	Create a new preset. Body MUST NOT include `id` — server assigns it.
`PATCH`	`/resources/api/agent/poaStepSettings`	Update an existing preset. Body MUST include `id` (the field, not in the URL).
`GET`	`/resources/api/agent/poaStepSettings/{id}`	Read one preset back — used to verify what landed and to resolve `name` from a known `id` .

All three require permission

manageClientSettings

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

clientId

createdAt

createdBy

modifiedAt

, audit trail are server-managed and echoed back on the response).

After creation, attach by editing a level:

requiredIdDocs.docSets[].poaStepSettingsId = "<the new id>"

on any

PROOF_OF_RESIDENCE

doc-set.

方法	路径	使用场景
`POST`	`/resources/api/agent/poaStepSettings`	创建新预设。请求体不得包含 `id` ——由服务器分配。
`PATCH`	`/resources/api/agent/poaStepSettings`	更新现有预设。请求体必须包含 `id` （在请求体字段中，而非URL中）。
`GET`	`/resources/api/agent/poaStepSettings/{id}`	读取单个预设——用于验证配置结果，以及通过已知 `id` 获取 `name` 。

所有请求均需

manageClientSettings

权限。请求体格式遵循 POA预设 schema——仅包含客户端可设置的字段（

clientId

、

createdAt

、

createdBy

、

modifiedAt

及审计跟踪由服务器管理，并在响应中返回）。

创建完成后，可通过编辑等级进行关联：在任意

PROOF_OF_RESIDENCE

文档集上设置

requiredIdDocs.docSets[].poaStepSettingsId = "<新生成的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

租户权限

POA preset creation has historically been gated behind the

POA

entitlement, but in practice the API accepts the write for most tenants regardless — the entitlement is often baseline, covered by other keys, or simply not surfaced in

allowedChecks

. Don't treat its absence as a blocker.

Invoke
```
sumsub-check-permissions
```
and inspect
```
allowedChecks
```
— informational, for diagnostics.
If
POA
is present — proceed.
If
POA
is missing — proceed anyway, with a one-line user-visible note that the documented entitlement isn't listed (so they know what to mention to support if the POST eventually fails). Do NOT pause for confirmation — Sumsub will reject the write itself if the tenant truly lacks the right, and the 4xx from that will be more informative than a pre-emptive halt.
If the POST returns a 4xx that mentions an entitlement — surface the error body verbatim and suggest contacting CSM / Sumsub support.

POA预设创建历史上受

POA

权限限制，但实际上大多数租户的API都会接受写入请求——该权限通常是基础权限，由其他密钥覆盖，或者未在

allowedChecks

中显示。请勿将权限缺失视为阻塞因素。

调用
```
sumsub-check-permissions
```
并检查
```
allowedChecks
```
——仅用于信息诊断。
如果存在
POA
权限——继续执行。
如果缺少
POA
权限——仍继续执行，并向用户显示一行提示，说明文档中提到的权限未列出（以便如果POST最终失败，用户知道需要向支持人员提及什么）。请勿暂停等待确认——如果租户确实缺少权限，Sumsub会自行拒绝写入请求，返回的4xx错误会比预先停止操作更具参考价值。
如果POST返回提及权限的4xx错误——直接显示错误体内容，并建议联系客户成功经理/Sumsub支持人员。

Procedure

操作流程

Fetch tenant entitlements — see section above.
Translate the user's intent into the compact spec (below). Most users describe presets in terms of "what we accept" (bank statements, utility bills) and "for how long" (validity in months) — map that into
```
providers
```
keys,
```
subTypes
```
, and
```
validMonths
```
.
Validate: name non-empty;
```
includedCountries
```
and
```
excludedCountries
```
aren't both set; every provider key is a
```
PoaCompanyContactType
```
; every
```
subTypes
```
entry is a
```
PoaSubType
```
; every country code is ISO-3166-1 alpha-3 uppercase;
```
crossValidator.fuzzyThreshold
```
in
```
[0, 1]
```
.
Generate payload via
```
${CLAUDE_SKILL_DIR}/scripts/build_poa_preset.py
```
(compact spec on stdin → full payload on stdout).
Create vs. update:
- New preset — POST via
```
${CLAUDE_SKILL_DIR}/scripts/post_poa_preset.sh
```
  . The payload must not carry
```
id
```
  .
- Update existing — first GET the current state via
```
${CLAUDE_SKILL_DIR}/scripts/get_poa_preset.sh
```
  so the user sees the diff, then PATCH via
```
${CLAUDE_SKILL_DIR}/scripts/patch_poa_preset.sh
```
  . The payload must include the preset's
```
id
```
  .
Build the dashboard link. Read
```
id
```
and
```
clientId
```
from the response body and format:
```
https://cockpit.sumsub.com/checkus/sdkIntegrations/globalSettings/userVerification/proofOfAddress/<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 name; surface the id only at the end as the value to pass into the next API call:
- Name and country scope (incl/excl) + per-country override countries.
- A brief summary of what's accepted (provider types covered, default validity).
- Dashboard link as a clickable markdown link.
- Final line:
```
Preset ID for level wiring: <id>
```
  .

获取租户权限——参见上文章节。
将用户意图转换为精简规范（如下）。大多数用户会用“我们接受的文档类型”（银行对账单、水电费账单）和“有效期”（以月为单位）来描述预设——将其映射为
```
providers
```
键、
```
subTypes
```
和
```
validMonths
```
。
验证：名称非空；
```
includedCountries
```
和
```
excludedCountries
```
不能同时设置；每个provider键都是
```
PoaCompanyContactType
```
；每个
```
subTypes
```
条目都是
```
PoaSubType
```
；每个国家代码都是ISO-3166-1 alpha-3大写格式；
```
crossValidator.fuzzyThreshold
```
在
```
[0, 1]
```
范围内。
生成负载：通过
```
${CLAUDE_SKILL_DIR}/scripts/build_poa_preset.py
```
（标准输入传入精简规范 → 标准输出输出完整负载）。
创建 vs 更新:
- 新预设——通过
```
${CLAUDE_SKILL_DIR}/scripts/post_poa_preset.sh
```
  发送POST请求。负载不得包含
```
id
```
  。
- 更新现有预设——首先通过
```
${CLAUDE_SKILL_DIR}/scripts/get_poa_preset.sh
```
  获取当前状态，以便用户查看差异，然后通过
```
${CLAUDE_SKILL_DIR}/scripts/patch_poa_preset.sh
```
  发送PATCH请求。负载必须包含预设的
```
id
```
  。
构建控制台链接：从响应体中读取
```
id
```
和
```
clientId
```
，并格式化为：
```
https://cockpit.sumsub.com/checkus/sdkIntegrations/globalSettings/userVerification/proofOfAddress/<id>?clientId=<clientId>&xSNSEnv=sbx
```
```
xSNSEnv=sbx
```
查询参数指向Sandbox工作区——这是所有技能通用的标准沙箱链接参数。
结果报告——以人类可读的名称开头；仅在最后一行显示id，作为下一步API调用的参数：
- 名称和国家范围（包含/排除）+ 各国覆盖规则的国家列表。
- 简要总结接受的内容（涵盖的提供商类型、默认有效期）。
- 控制台链接：以可点击的markdown链接形式呈现。
- 最后一行：
```
用于等级关联的预设ID: <id>
```
  。

Compact spec format (JSON or YAML on stdin)

精简规范格式（标准输入传入JSON或YAML）

yaml

name: "Standard POA (6 months)"
desc: "Default Proof of Address rules with 6-month validity"

yaml

name: "Standard POA (6 months)"
desc: "Default Proof of Address rules with 6-month validity"

Country scope — choose AT MOST ONE

国家范围 — 最多选择一项

includedCountries: [GBR, DEU, FRA] # allow-list

includedCountries: [GBR, DEU, FRA] # 允许列表

excludedCountries: [PRK, IRN] # block-list

excludedCountries: [PRK, IRN] # 阻止列表

Global defaults

全局默认设置

settings: acceptMultiplePages: true acceptDocScreenshot: true requireCountryMatch: false # require POI country == POA country useIssueDateForExpiry: false # use only issueDate (ignore expiry) for "fresh enough" check validMonths: 6 # shortcut: applied to every provider that omits its own validMonths addressTypes: [dwelling, poBox] # allowed PoA address types acceptableLanguages: [en, de, fr]

Document providers and the doc sub-types each may produce

Keys (PoaCompanyContactType): bank | utilityProvider | governmentOrganization | mobileOperator | other

providers: bank: validMonths: 6 acceptUnconventional: true # accept non-mainstream banks (with allowedOrgNames below) subTypes: [bankStatement, bankLetter, other] allowedOrgs: # only used when acceptUnconventional=true names: ["Some Local Co-op Bank"] websites: ["coopbank.example"] forbiddenDocumentNames: [] forbiddenOrgNames: [] forbiddenOrgWebsites: [] utilityProvider: subTypes: [telecom, utilityBill, other] governmentOrganization: subTypes: [statement, voterRegistration, taxBill, other] mobileOperator: {} # accept defaults other: subTypes: [lease, other, universityLetter]

Accept identity document as proof of address

poiAsPoa: enabled: true # acceptPoiAsPoa sameDoc: true # acceptSamePoiAsPoa (same doc for POI + POA) validMonths: 3 allowedTypes: [PASSPORT, ID_CARD, RESIDENCE_PERMIT, DRIVERS]

Name/address comparison between POI and POA

settings: acceptMultiplePages: true acceptDocScreenshot: true requireCountryMatch: false # 要求POI国家 == POA国家 useIssueDateForExpiry: false # 仅使用签发日期（忽略过期日期）进行“足够新”检查 validMonths: 6 # 快捷方式：应用于所有未单独设置validMonths的提供商 addressTypes: [dwelling, poBox] # 允许的POA地址类型 acceptableLanguages: [en, de, fr]

文档提供商及每个提供商可生成的文档子类型

键（PoaCompanyContactType）: bank | utilityProvider | governmentOrganization | mobileOperator | other

providers: bank: validMonths: 6 acceptUnconventional: true # 接受非主流银行（需配置下方allowedOrgNames） subTypes: [bankStatement, bankLetter, other] allowedOrgs: # 仅在acceptUnconventional=true时生效 names: ["Some Local Co-op Bank"] websites: ["coopbank.example"] forbiddenDocumentNames: [] forbiddenOrgNames: [] forbiddenOrgWebsites: [] utilityProvider: subTypes: [telecom, utilityBill, other] governmentOrganization: subTypes: [statement, voterRegistration, taxBill, other] mobileOperator: {} # 接受默认设置 other: subTypes: [lease, other, universityLetter]

接受身份文档作为地址证明

poiAsPoa: enabled: true # acceptPoiAsPoa sameDoc: true # acceptSamePoiAsPoa（同一文档同时作为POI和POA） validMonths: 3 allowedTypes: [PASSPORT, ID_CARD, RESIDENCE_PERMIT, DRIVERS]

POI与POA之间的姓名/地址比较

Per-country overrides — same shape as

settings

. Only the keys you set are overridden;

各国覆盖规则 — 格式与

settings

相同。仅覆盖设置的键；

others fall through to the global

settings

其他键继承全局

settings

的设置。

byCountry: BRA: validMonths: 3 # tighter validity for Brazil providers: bank: validMonths: 3

undefined

byCountry: BRA: validMonths: 3 # 巴西的有效期更严格 providers: bank: validMonths: 3

undefined

Provider-type values (

providers.<key>

)

提供商类型值（

providers.<key>

）

bank

utilityProvider

governmentOrganization

mobileOperator

other

bank

utilityProvider

governmentOrganization

mobileOperator

other

Sub-types (

providers.<key>.subTypes[]

)

子类型（

providers.<key>.subTypes[]

）

statement

voterRegistration

taxBill

telecom

utilityBill

bankStatement

bankLetter

lease

universityLetter

employmentLetter

other

statement

voterRegistration

taxBill

telecom

utilityBill

bankStatement

bankLetter

lease

universityLetter

employmentLetter

other

Address types (

addressTypes[]

)

地址类型（

addressTypes[]

）

dwelling

poBox

poBoxSpecialCountries

dwelling

poBox

poBoxSpecialCountries

POI-as-POA

allowedTypes[]

POI-as-POA允许类型（

allowedTypes[]

）

Standard

IdDocType

values:

PASSPORT

ID_CARD

RESIDENCE_PERMIT

DRIVERS

(others rare).

标准

IdDocType

值：

PASSPORT

ID_CARD

RESIDENCE_PERMIT

DRIVERS

（其他类型罕见）。

Name comparison modes (

crossValidator.nameMode

)

姓名比较模式（

crossValidator.nameMode

）

strict

weakContainment

def

ai

fuzzy

containment

fuzzyContainment

strict

weakContainment

def

ai

fuzzy

containment

fuzzyContainment

Address comparison modes (

crossValidator.addressMode

)

地址比较模式（

crossValidator.addressMode

）

strict

fuzzy

strict

fuzzy

Outputs

输出

On success, lead with the human-readable info:

```
name
```
, country scope, list of per-country override countries.
A brief summary (provider types covered, default validity).

Dashboard link:

https://cockpit.sumsub.com/checkus/sdkIntegrations/globalSettings/userVerification/proofOfAddress/<id>?clientId=<clientId>&xSNSEnv=sbx

. Render as a clickable markdown link. Both

id

and

clientId

come from the POST response body;

xSNSEnv=sbx

targets the Sandbox workspace.

Finally, on its own line:

Preset ID (for level wiring / future PATCH): <id>

On failure: HTTP status + Sumsub's

description

errorName

. The builder rejects invalid enums / impossible combinations upfront with precise messages.

成功时，优先显示人类可读信息：

```
name
```
、国家范围、各国覆盖规则的国家列表。
简要总结（涵盖的提供商类型、默认有效期）。

控制台链接：

https://cockpit.sumsub.com/checkus/sdkIntegrations/globalSettings/userVerification/proofOfAddress/<id>?clientId=<clientId>&xSNSEnv=sbx

。以可点击的markdown链接形式呈现。

id

和

clientId

来自POST响应体；

xSNSEnv=sbx

指向沙箱工作区。

最后单独一行：

预设ID（用于等级关联/后续PATCH）: <id>

。

失败时：返回HTTP状态码 + Sumsub的

description

errorName

。构建器会提前拒绝无效枚举/不可能的组合，并返回精确的错误信息。

Names, not ids, in user-facing messages

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

This applies to every message about the preset — pre-POST summary, mid-flow status updates, hand-off lines — not only the final report:

Refer to the preset by
```
name
```
("POA — 60 days"), not by its
```
id
```
, in prose.
The
```
id
```
belongs only on the final dedicated line (
```
Preset ID for level wiring: <id>
```
) — that line is the one place a raw id is correct, because the user needs to copy it into a level's
```
poaPresetId
```
.
When the caller is the level skill chaining this preset into a
```
PROOF_OF_RESIDENCE
```
step, the level skill should ALSO refer to this preset by name in its pre-POST summary — see
```
sumsub-create-level
```
.

此规则适用于所有关于预设的消息——POST前的摘要、流程中的状态更新、交接说明——不仅限于最终报告：

在文本中使用预设的
```
name
```
（如“POA — 60天”）而非
```
id
```
。
```
id
```
仅应出现在最后一行专用行中（
```
用于等级关联的预设ID: <id>
```
）——这是唯一适合显示原始ID的地方，因为用户需要将其复制到等级的
```
poaPresetId
```
中。
当调用者是将此预设关联到
```
PROOF_OF_RESIDENCE
```
步骤的等级技能时，等级技能在POST前的摘要中也应使用预设名称——参见
```
sumsub-create-level
```
。

Hand-off to

sumsub-create-level

交接至

sumsub-create-level

The returned

id

is what you pass to a level's

PROOF_OF_RESIDENCE

doc-set. The level skill exposes it as a friendly

poaPresetId

shortcut (or the canonical

poaStepSettingsId

json

{
  "type": "PROOF_OF_RESIDENCE",
  "docTypes": ["UTILITY_BILL", "BANK_STATEMENT"],
  "poaPresetId": "<id from this skill>"
}

See

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

返回的

id

用于关联到等级的

PROOF_OF_RESIDENCE

文档集。等级技能将其作为友好的

poaPresetId

快捷方式（或标准的

poaStepSettingsId

）：

json

{
  "type": "PROOF_OF_RESIDENCE",
  "docTypes": ["UTILITY_BILL", "BANK_STATEMENT"],
  "poaPresetId": "<此技能返回的id>"
}

参见

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

。

Worked examples

示例

```
examples/minimal.json
```
— bare-minimum preset: 6-month bank/utility/gov defaults, POI-as-POA off.
```
examples/eu-bank-friendly.json
```
— EU-only preset, generous bank-statement validity, POI-as-POA allowed for 3 months.
```
examples/per-country-tight.json
```
— global defaults plus a tighter Brazil override.

```
examples/minimal.json
```
— 最简预设：6个月有效期的银行/公共事业/政府默认设置，禁用POI-as-POA。
```
examples/eu-bank-friendly.json
```
— 仅欧盟预设，宽松的银行对账单有效期，允许POI-as-POA有效期3个月。
```
examples/per-country-tight.json
```
— 全局默认设置加上更严格的巴西覆盖规则。

另请参阅

references/poa-preset-schema.md — full
```
PoaStepSettings
```
schema, every enum, and gotchas.

references/poa-preset-schema.md — 完整的
```
PoaStepSettings
```
schema、所有枚举及注意事项。

sumsub-create-poa-preset

Original

Translation

Sumsub — Create POA Preset

Sumsub — 创建POA预设

Endpoints

端点

Auth — App Token + secret (sandbox only)

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

Tenant entitlements

租户权限

Procedure

操作流程

Compact spec format (JSON or YAML on stdin)

精简规范格式（标准输入传入JSON或YAML）

Country scope — choose AT MOST ONE

国家范围 — 最多选择一项

includedCountries: [GBR, DEU, FRA] # allow-list

includedCountries: [GBR, DEU, FRA] # 允许列表

Global defaults

全局默认设置

Document providers and the doc sub-types each may produce

Keys (PoaCompanyContactType): bank | utilityProvider | governmentOrganization | mobileOperator | other

Accept identity document as proof of address

Name/address comparison between POI and POA

文档提供商及每个提供商可生成的文档子类型

键（PoaCompanyContactType）: bank | utilityProvider | governmentOrganization | mobileOperator | other

接受身份文档作为地址证明

POI与POA之间的姓名/地址比较

Per-country overrides — same shape as settings. Only the keys you set are overridden;

各国覆盖规则 — 格式与settings相同。仅覆盖设置的键；

others fall through to the global settings.

其他键继承全局settings的设置。

Provider-type values (providers.<key>)

提供商类型值（providers.<key>）

Sub-types (providers.<key>.subTypes[])

子类型（providers.<key>.subTypes[]）

Address types (addressTypes[])

地址类型（addressTypes[]）

POI-as-POA allowedTypes[]

POI-as-POA允许类型（allowedTypes[]）

Name comparison modes (crossValidator.nameMode)

姓名比较模式（crossValidator.nameMode）

Address comparison modes (crossValidator.addressMode)

地址比较模式（crossValidator.addressMode）

Outputs

输出

Names, not ids, in user-facing messages

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

Hand-off to sumsub-create-level

交接至sumsub-create-level

Worked examples

示例

See also

另请参阅

Per-country overrides — same shape as
`settings`
. Only the keys you set are overridden;

各国覆盖规则 — 格式与
`settings`
相同。仅覆盖设置的键；

others fall through to the global
`settings`
.

其他键继承全局
`settings`
的设置。

Provider-type values (
`providers.<key>`
)

提供商类型值（
`providers.<key>`
）

Sub-types (
`providers.<key>.subTypes[]`
)

子类型（
`providers.<key>.subTypes[]`
）

Address types (
`addressTypes[]`
)

地址类型（
`addressTypes[]`
）

POI-as-POA
`allowedTypes[]`

POI-as-POA允许类型（
`allowedTypes[]`
）

Name comparison modes (
`crossValidator.nameMode`
)

姓名比较模式（
`crossValidator.nameMode`
）

Address comparison modes (
`crossValidator.addressMode`
)

地址比较模式（
`crossValidator.addressMode`
）

Hand-off to
`sumsub-create-level`

交接至
`sumsub-create-level`