sumsub-create-cross-check-preset

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sumsub — Create / Update Cross-Check Preset

Sumsub — 创建/更新交叉检查预设

⚠️ Read this before running this skill.

Sumsub's default cross-check preset is tuned for the best balance of conversion and approval rate. Most clients should not override it. If the user hasn't named a specific comparison they want to change, stop and say:

"Cross-check rules are already configured for the best approval rate. We strongly recommend keeping the defaults. Tell me a specific tweak you need (e.g. 'allow fuzzy address match', 'ignore middle name') and we'll create a minimal override."

Only proceed if the user has a concrete, named tweak.

⚠️ 运行此技能前请阅读以下内容。

Sumsub的默认交叉检查预设已针对转化率和审核通过率的最佳平衡进行优化。大多数客户不应修改它。 如果用户未明确说明想要更改的具体比对规则，请停止操作并告知：

“交叉检查规则已配置为最佳审核通过率，我们强烈建议保留默认设置。请告知您需要的具体调整（例如：‘允许模糊地址匹配’、‘忽略中间名’），我们将创建最小化的自定义覆盖规则。”

仅当用户提出具体明确的调整需求时，才可继续操作。

What is a cross-check preset

什么是交叉检查预设

A cross-check preset controls how Sumsub compares the name and address that appear on the proof-of-identity (POI) document with the same fields on the proof-of-address (POA) document. The preset decides whether small differences ("Jonathan" vs "Jon", "Apt 4" vs "Apartment 4") are accepted or flagged as mismatches.

Don't confuse with PoA preset's
crossValidator
. The
sumsub-create-poa-preset
skill has an internal block called
crossValidator
(
CrossValidatorSettings
on
PoaDocumentSettings
) with
nameMode
/
addressMode
/
fuzzyThreshold
— that's a per-PoA-preset override for the same comparison. A workspace-level CrossCheckPreset (this skill) supplies the default when no PoA-preset override applies. When a PoA preset's
crossValidator
is set, it wins for documents handled by that preset.

There are two preset modes:

basic
— what this skill creates. Picks
```
nameComparisonMode
```
and
```
addressComparisonMode
```
from a small enum, plus optional ignore-flags. Best for almost everyone.
advanced
— per-rule manual configuration. Not supported via the public API (
```
POST
```
returns
```
403 Forbidden — Advanced cross-check presets cannot be managed via API
```
). Has to be done in the dashboard.

交叉检查预设用于控制Sumsub如何比对**身份证明文件（POI）上的姓名和地址与地址证明文件（POA）**上的对应字段。该预设决定了细微差异（如“Jonathan”与“Jon”、“Apt 4”与“Apartment 4”）是被接受还是标记为不匹配。

请勿与PoA预设的
crossValidator
混淆。
sumsub-create-poa-preset
技能包含一个名为
crossValidator
的内部模块（对应
PoaDocumentSettings
中的
CrossValidatorSettings
），其中包含
nameMode
/
addressMode
/
fuzzyThreshold
参数——这是针对相同比对规则的单个PoA预设级覆盖。而本技能所涉及的工作区级CrossCheckPreset，会在未设置PoA预设级覆盖时提供默认规则。当PoA预设的
crossValidator
参数被设置后，该预设处理的文档将优先使用此规则。

预设分为两种模式：

basic
（基础模式）——本技能创建的模式。从有限的枚举值中选择
```
nameComparisonMode
```
和
```
addressComparisonMode
```
，还可添加可选的忽略标记。适合绝大多数用户。
advanced
（高级模式）——手动配置每条规则。公共API不支持此模式（调用
```
POST
```
接口会返回
```
403 Forbidden — Advanced cross-check presets cannot be managed via API
```
），必须通过控制台操作。

Endpoints

接口端点

Method	Path	When
`POST`	`/resources/api/agent/crossCheckPresets`	Create a new preset. Body must NOT include `id` .
`PATCH`	`/resources/api/agent/crossCheckPresets`	Update an existing preset. Body MUST include `id` .
`GET`	`/resources/api/agent/crossCheckPresets/{id}`	Read one preset back (verify what landed; resolve `title` from a known `id` ).

All require permission

manageClientSettings

. Body shape is the cross-check preset schema — client-settable fields only.

方法	路径	使用场景
`POST`	`/resources/api/agent/crossCheckPresets`	创建新预设。请求体不得包含 `id` 。
`PATCH`	`/resources/api/agent/crossCheckPresets`	更新现有预设。请求体必须包含 `id` 。
`GET`	`/resources/api/agent/crossCheckPresets/{id}`	读取单个预设信息（验证配置是否生效；通过已知 `id` 获取 `title` ）。

所有接口均需

manageClientSettings

权限。请求体需符合交叉检查预设 schema——仅包含客户端可设置的字段。

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 — cross-check rules affect every verification on the workspace. 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 scripts enforce this — they reject 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

操作流程

Confirm necessity — Restate the user's request in one sentence and re-state the recommendation to keep defaults. If they have a specific named tweak, proceed. Otherwise stop.
Translate the user's intent into the compact spec (below). Map their ask to
```
nameComparisonMode
```
/
```
addressComparisonMode
```
/ ignore-flags.
Validate —
```
title
```
non-empty (≤256 chars);
```
mode
```
is
```
basic
```
(advanced is forbidden via API); every comparison mode is a valid enum.
Generate payload — run
```
${CLAUDE_SKILL_DIR}/scripts/build_cross_check_preset.py
```
with the compact spec on stdin → full payload on stdout.

Create vs. update:

New preset — POST via

${CLAUDE_SKILL_DIR}/scripts/post_cross_check_preset.sh

. Payload must NOT include

id

Update existing — first GET via

${CLAUDE_SKILL_DIR}/scripts/get_cross_check_preset.sh

so the user sees the diff, then PATCH via

${CLAUDE_SKILL_DIR}/scripts/patch_cross_check_preset.sh

. Payload must include

id

GET the preset back and verify what landed.
Report — lead with the human-readable summary, end with the id:
- ```
title
```
  and a one-line summary of what was tweaked vs. the default.
- Reminder: "Default cross-check rules are recommended for the highest approval rate; you've now overridden them for these comparisons — monitor conversion before rolling to production."
- Final line:
```
Preset ID (for level wiring / future PATCH): <id>
```
  .

确认必要性——用一句话重述用户的请求，并再次强调保留默认设置的建议。如果用户有明确的调整需求，继续操作；否则停止。
将用户意图转换为简洁规范（如下所示）。将用户的需求映射为
```
nameComparisonMode
```
/
```
addressComparisonMode
```
/忽略标记。
验证——
```
title
```
不能为空（≤256字符）；
```
mode
```
必须为
```
basic
```
（API不支持高级模式）；所有比对模式必须是有效的枚举值。
生成请求体——在标准输入中传入简洁规范，运行
```
${CLAUDE_SKILL_DIR}/scripts/build_cross_check_preset.py
```
脚本，标准输出将返回完整的请求体。
创建与更新：
- 新预设——运行
```
${CLAUDE_SKILL_DIR}/scripts/post_cross_check_preset.sh
```
  脚本发送POST请求。请求体不得包含
```
id
```
  。
- 更新现有预设——先运行
```
${CLAUDE_SKILL_DIR}/scripts/get_cross_check_preset.sh
```
  脚本获取当前预设，让用户查看差异，再运行
```
${CLAUDE_SKILL_DIR}/scripts/patch_cross_check_preset.sh
```
  脚本发送PATCH请求。请求体必须包含
```
id
```
  。
重新获取预设信息并验证配置是否生效。
反馈结果——先展示易读的摘要信息，最后给出预设ID：
- ```
title
```
  以及与默认设置相比的调整内容摘要（一行描述）。
- 提醒：“默认交叉检查规则可实现最高审核通过率；您现已修改了这些比对规则——请在推广到生产环境前监控转化率。”
- 最后一行：
```
预设ID（用于等级关联/后续PATCH操作）：<id>
```
  。

Compact spec format (JSON or YAML on stdin)

简洁规范格式（标准输入支持JSON或YAML）

yaml

title: "Strict address, lenient name"
description: "Allow nickname variants but require exact address."

mode: basic                          # ONLY basic — advanced is forbidden via API
basicSettings:
  nameComparisonMode: weakContainment  # one of: strict | weakContainment | def | ai
  addressComparisonMode: strict        # one of: strict | fuzzy
  ignoreMiddleNameMismatch: true
  ignoreProvidedInfoMismatch: false    # if true, don't flag user-typed info that disagrees with the doc

yaml

title: "Strict address, lenient name"
description: "Allow nickname variants but require exact address."

mode: basic                          # 仅支持basic模式——API不支持advanced模式
basicSettings:
  nameComparisonMode: weakContainment  # 可选值：strict | weakContainment | def | ai
  addressComparisonMode: strict        # 可选值：strict | fuzzy
  ignoreMiddleNameMismatch: true
  ignoreProvidedInfoMismatch: false    # 如果设为true，将不会标记用户填写信息与文档信息的不一致

Comparison-mode meaning

比对模式说明

nameComparisonMode

```
strict
```
— exact match required.
```
weakContainment
```
— token-level containment (e.g. "Jon Smith" ⊆ "Jonathan Andrew Smith").
```
def
```
— Sumsub's recommended default; balances strictness and conversion.
```
ai
```
— ML-based comparison; tolerant of common variants and transliterations.

addressComparisonMode

```
strict
```
— character-level match (after normalisation).
```
fuzzy
```
— tolerant of abbreviations and word order.

The deprecated values (

fuzzy

containment

fuzzyContainment

on names) are NOT accepted via this skill.

nameComparisonMode

```
strict
```
— 要求完全匹配。
```
weakContainment
```
— 基于令牌的包含匹配（例如：“Jon Smith” ⊆ “Jonathan Andrew Smith”）。
```
def
```
— Sumsub推荐的默认模式；平衡严格性与转化率。
```
ai
```
— 基于机器学习的比对；兼容常见变体和音译。

addressComparisonMode

```
strict
```
— 标准化后的字符级匹配。
```
fuzzy
```
— 兼容缩写和语序差异。

本技能不接受已弃用的取值（姓名比对中的

fuzzy

containment

fuzzyContainment

）。

Outputs

输出结果

On success, lead with the human-readable info:

```
title
```
and a one-line summary of what was tweaked vs. the workspace default.
Reminder: "Default cross-check rules are recommended for the highest approval rate; you've now overridden them — monitor conversion before rolling to production."

Final line:

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

On failure: HTTP status + Sumsub's

description

errorName

. Common causes:

403 Advanced cross-check presets cannot be managed via API

—

mode: advanced

is dashboard-only. Switch to

basic

mode.

```
400
```
with a validation message — one of the comparison-mode enums is wrong (e.g. a deprecated
```
fuzzy
```
/
```
containment
```
/
```
fuzzyContainment
```
name mode).

成功时，优先展示易读的信息：

```
title
```
以及与工作区默认设置相比的调整内容摘要（一行描述）。
提醒：“默认交叉检查规则可实现最高审核通过率；您现已修改了这些规则——请在推广到生产环境前监控转化率。”

最后一行：

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

。

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

description

errorName

。常见原因：

403 Advanced cross-check presets cannot be managed via API

—

mode: advanced

仅支持控制台操作，请切换为

basic

模式。

```
400
```
及验证错误信息——比对模式枚举值错误（例如：使用了已弃用的姓名比对模式
```
fuzzy
```
/
```
containment
```
/
```
fuzzyContainment
```
）。

Worked examples

示例

```
examples/strict-name-only.json
```
— tighten name match, leave address on defaults.
```
examples/lenient-for-emerging-markets.json
```
— fuzzy address + ai name, ignore middle-name mismatch.

```
examples/strict-name-only.json
```
— 收紧姓名匹配规则，地址保留默认设置。
```
examples/lenient-for-emerging-markets.json
```
— 模糊地址匹配 + AI姓名比对，忽略中间名不匹配。

Hand-off — attaching the preset to a level

后续操作 — 将预设关联到等级

Cross-check presets are workspace-scoped. The default preset auto-applies to every level; if you've created a custom one, you have to attach it to specific levels by setting

crossCheckPresetId

on the level. That's done with

sumsub-create-level

(or a direct PATCH on the level via

sumsub-api-generic

交叉检查预设是工作区范围的。默认预设会自动应用于所有等级；如果创建了自定义预设，需要通过设置等级的

crossCheckPresetId

参数，将其关联到特定等级。此操作可通过

sumsub-create-level

技能（或通过

sumsub-api-generic

直接PATCH等级）完成。

参考链接

references/cross-check-preset-schema.md — full schema, every enum, gotchas.
Sumsub cross-check docs.

references/cross-check-preset-schema.md — 完整schema、所有枚举值及注意事项。
Sumsub交叉检查文档。",