sumsub-supported-id-documents

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sumsub — Supported Documents Reference

Sumsub — 支持的文档参考

Answers questions about Sumsub's built-in supported-documents catalogue (

documentsByCountries

): per country and document type, whether the type is supported, whether it's double-sided, and which OCR fields are extracted by default vs. optionally available.

The catalogue is large (~250 countries, ~1350 country/doc-type pairs). This skill never dumps it into the conversation — a local Python script keeps the full catalogue in-process and returns only the relevant slice, collapsing to an aggregate summary when a flat list would be too large to be useful.

解答关于Sumsub内置支持文档目录（

documentsByCountries

）的问题：按国家和文档类型，说明该类型是否受支持、是否为双面，以及默认提取和可选提取的OCR字段有哪些。

该目录规模较大（约250个国家，约1350个国家/文档类型组合）。本技能不会在对话中直接输出完整目录——本地Python脚本会在进程中保存完整目录，仅返回相关片段；当扁平列表过大时，会自动合并为汇总摘要。

Endpoints

接口

Method	Path	When
`GET`	`/resources/api/agent/supportedDocs/documentsByCountries`	Read the built-in supported-documents catalogue (defaults for every country).
`GET`	`/resources/api/agent/globalSettings`	Read the client's CURRENT settings, incl. their `idDocSettings.countryMappings` overrides.
`GET`	`/resources/api/agent/globalSettings/extensionRules`	Read Sumsub's built-in expiry-extension rules (read-only reference; backs the "officially extended documents" expiry modes).
`PUT`	`/resources/api/agent/globalSettings/idDocSettings/countryMappings`	Replace-all — the only write path. Always send the FULL map built by the scripts (read-modify-write for edits, minus-one-entry for removals).

All use App Token auth with

manageClientSettings

The catalogue GET returns

{ "countryMappings": { "<ISO3>": { "<DOC_TYPE>": { supported, doubleSided, doubleSidedCanBeChanged, shouldBeSigned, acceptDigitalDoc, acceptScreenshots, expirationCheckMode, sidesSelectionMode, defaultFields[], availableFields[] } } } }

⚠️ Two different shapes — mind the path. The catalogue GET puts
countryMappings
at the top level. GET globalSettings nests it one level deeper, under idDocSettings.countryMappings
(the root also has
minAge
,
poaCheckSettings
,
poiCheckSettings
— the key-wide expiry mode — etc.). When reading
/tmp/current.json
(globalSettings) in an inline
python3 -c
, use
['idDocSettings']['countryMappings']
— the top-level path raises
KeyError: 'countryMappings'
.

Fields are serialised
NON_NULL
: a flag that is absent from the JSON is at its default (not set). For acceptance flags, absent ⇒
false
(e.g. no
acceptScreenshots
key ⇒ screenshots are not accepted). Never report a flag as enabled just because it's missing; report the default and say it's the default.

PUT is replace-all: the backend swaps the whole
countryMappings
map for whatever you send — anything omitted is wiped (reverts to catalogue defaults). That's why every write goes through the scripts:
build_country_mappings.py
merges your changes into a FRESH copy of the current map, and
remove_country_mapping.py
builds the map minus one entry. Never hand-craft a partial payload, and never reuse a stale
/tmp/current.json
— re-fetch it right before building or a concurrent dashboard edit gets silently reverted.

方法	路径	适用场景
`GET`	`/resources/api/agent/supportedDocs/documentsByCountries`	读取内置支持文档目录（所有国家的默认配置）。
`GET`	`/resources/api/agent/globalSettings`	读取客户端当前设置，包括其 `idDocSettings.countryMappings` 覆盖配置。
`GET`	`/resources/api/agent/globalSettings/extensionRules`	读取Sumsub内置的有效期延长规则（只读参考，为“官方延长文档”有效期模式提供支持）。
`PUT`	`/resources/api/agent/globalSettings/idDocSettings/countryMappings`	全量替换——唯一写入路径。始终发送脚本生成的完整映射（编辑时采用读取-修改-写入流程，删除时移除对应条目）。

所有接口均使用带有

manageClientSettings

权限的App Token进行认证。

目录GET接口返回格式为：

{ "countryMappings": { "<ISO3>": { "<DOC_TYPE>": { supported, doubleSided, doubleSidedCanBeChanged, shouldBeSigned, acceptDigitalDoc, acceptScreenshots, expirationCheckMode, sidesSelectionMode, defaultFields[], availableFields[] } } } }

。

⚠️ 两种不同结构——注意路径区别。目录GET接口的
countryMappings
位于顶层。而GET globalSettings接口中，
countryMappings
嵌套在**
idDocSettings.countryMappings
**下（根节点还包含
minAge
、
poaCheckSettings
、
poiCheckSettings
——全局有效期模式等）。在嵌入式
python3 -c
中读取
/tmp/current.json
（globalSettings）时，需使用
['idDocSettings']['countryMappings']
——使用顶层路径会触发
KeyError: 'countryMappings'
。

字段采用
NON_NULL
序列化：JSON中缺失的标志位即为默认值（未设置）。对于接受类标志，缺失⇒
false
（例如无
acceptScreenshots
键⇒不接受截图）。切勿因标志位缺失就报告其已启用；需说明默认值并标注为默认配置。

PUT为全量替换：后端会将整个
countryMappings
映射替换为你发送的内容——任何被省略的条目都会被清除（恢复为目录默认值）。这就是所有写入操作都需通过脚本完成的原因：
build_country_mappings.py
会将你的更改合并到当前映射的全新副本中，
remove_country_mapping.py
会生成移除指定条目后的映射。切勿手动编写部分负载，也切勿复用过期的
/tmp/current.json
——在生成负载前务必重新获取，否则并发的仪表盘编辑会被静默覆盖。

Key-wide root blocks in GET globalSettings (read them, don't miss them)

GET globalSettings中的全局根节点配置（务必读取，不可遗漏）

Besides

idDocSettings.countryMappings

, the globalSettings root carries key-wide blocks that change document answers. They are read-only context for this skill (edits here go through PUT countryMappings only), but skipping them gives wrong answers — a per-country entry that looks "not configured" may be governed by a root block:

Root path	What it holds	When it changes the answer
`poiCheckSettings.expirationCheckMode`	key-wide expiry mode	fallback in the expiry cascade (C)
`poiCheckSettings.minimumResidualValidityInMonths`	doc must stay valid ≥ N more months; `0` = no requirement (see C)	part of any validity answer (C)
`ongoingMonitoringSettings` ( `enabled` , `idDocExpireInDays` )	expiry monitoring AFTER approval (licence-gated)	"what happens when the doc expires"
`minAge` / `maxAge`	key-wide age limits (checked against DOB); dashboard auto-fills on save (min 16 — 18 for RUS-licensed keys — max 110), so usually present	"why was the doc/applicant rejected by age"
`idDocSettings.ekycSourceMappings`	eKYC sources per country — sibling of `countryMappings` , edited on the SAME dashboard "Supported ID documents" screen but saved as a separate payload; PUT countryMappings preserves it server-side (the endpoint only replaces `countryMappings` )	eKYC questions; don't confuse with countryMappings
`enableAutoCompleteShortDates`	OCR auto-completes 2-digit years in dates (dashboard: "Birth date" checkbox)	recognised date values
`imageConstraints` ( `minFileSize` , `maxFileSize` )	upload size limits (dashboard: General → Applicant settings)	"why was the file not accepted"
`poaCheckSettings` (deprecated)	POA acceptance ( `validMonths` , `acceptIdAsPoa` , `acceptSameDocAsPoa` )	POA questions — report as read-only context
`crossValidatorSettings`	doc-vs-profile comparison ( `nameComparisonMode` , `fuzzyThreshold` , …); API-only, no dashboard UI	mismatch/cross-check rejections

Everything else on the root (

watchListCheckSettings

cryptoCheckSettings

bankCardCheckSettings

kybIntegrationSettings

uiSettings

duplicateSettings

sourceKeysSettings

applicantTags

supportEmail

disableSumsubId

idDocServiceSettings

) is outside this skill's domain — don't answer document questions from those blocks or offer to edit them here.

除

idDocSettings.countryMappings

外，globalSettings根节点还包含全局配置块，会影响文档相关问题的答案。这些配置是本技能的只读上下文（编辑需通过PUT countryMappings完成），但忽略它们会导致错误答案——某个国家的条目看似“未配置”，实则可能受全局块管控：

根路径	包含内容	影响答案的场景
`poiCheckSettings.expirationCheckMode`	全局有效期模式	有效期规则级联的 fallback（C）
`poiCheckSettings.minimumResidualValidityInMonths`	文档剩余有效期需≥N个月；`0` = 无要求（见C）	任何与有效期相关的答案（C）
`ongoingMonitoringSettings` （ `enabled` , `idDocExpireInDays` ）	审批后的有效期监控（需授权）	“文档过期后会发生什么”
`minAge` / `maxAge`	全局年龄限制（根据出生日期检查）；仪表盘保存时自动填充（最小16岁——俄罗斯授权密钥为18岁——最大110岁），通常已配置	“为何文档/申请人因年龄被拒绝”
`idDocSettings.ekycSourceMappings`	各国eKYC数据源——与 `countryMappings` 同级，在同一仪表盘“支持的身份证件”屏幕编辑，但保存为独立负载；PUT countryMappings会在服务器端保留该配置（该接口仅替换 `countryMappings` ）	eKYC相关问题；请勿与countryMappings混淆
`enableAutoCompleteShortDates`	OCR自动补全日期中的两位年份（仪表盘：“出生日期”复选框）	识别日期值的规则
`imageConstraints` （ `minFileSize` , `maxFileSize` ）	上传文件大小限制（仪表盘：通用→申请人设置）	“为何文件未被接受”
`poaCheckSettings` （已废弃）	POA接受规则（ `validMonths` , `acceptIdAsPoa` , `acceptSameDocAsPoa` ）	POA相关问题——作为只读上下文报告
`crossValidatorSettings`	文档与资料对比规则（ `nameComparisonMode` , `fuzzyThreshold` 等）；仅API可用，无仪表盘UI	不匹配/交叉检查拒绝原因

根节点上的其他配置（

watchListCheckSettings

cryptoCheckSettings

bankCardCheckSettings

kybIntegrationSettings

uiSettings

duplicateSettings

sourceKeysSettings

applicantTags

supportEmail

disableSumsubId

idDocServiceSettings

）不属于本技能范畴——请勿基于这些块回答文档问题，也不要在此处提供编辑功能。

Auth — App Token + secret (sandbox only)

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

Same model as the other write skills. See

sumsub-api-auth

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

DEFAULT to effective recognition status (A). Any question about what a country / doc type recognises, collects, or has available right now — including phrasings like "what fields are currently available / recognised / collected", "what fields are available for BRA", "what does the passport collect" — is about the CLIENT'S effective state, so use recognition status (A). The bare catalogue is defaults only and will give a misleading answer ("available" in the catalogue ≠ enabled for this client).

Only use the catalogue query (B) when the user explicitly asks what is possible in the abstract or across countries — "which countries support field X", "is gender ever extractable for passports", "what doc types exist for BRA".

A question about expiry / validity checks ("what validity checks apply", "is an expired doc accepted") → use (C) below: report the

expirationCheckMode

AND the concrete extension rule that applies (the 60+ / extension text), not just the mode.

A broad question about how a document is handled ("acceptance rules", "what settings apply", "what's configured for X") → use (D) below: read the whole effective

(country, docType)

entry from GET globalSettings and report every setting on it, on or off — don't curate or guess a subset, and don't omit flags left at their default.

If unsure which the user means, pick A (effective) — it's the honest answer and it also tells you what the catalogue allows.

⚠️ Always go through these scripts — never read the Paler source. If you happen to have the
paler
repo open, do NOT answer from its files (
documents-by-countries.json
, Java sources, etc.). Those contain only the built-in catalogue defaults — the client's effective state (
countryMappings
overrides +
ADVANCED_OCR
) is not in the code at all, only behind the API. Reading source can only give defaults and will silently answer the wrong question. The data must come from
get_global_settings.sh
/
get_supported_docs.sh
/
get_entitlements.sh
.

与其他写入技能的认证模式相同。详见

sumsub-api-auth

。

变量	示例
`SUMSUB_APP_TOKEN`	`sbx:...` — 仪表盘获取的沙箱App Token。
`SUMSUB_SECRET_KEY`	创建Token时显示的配对密钥（仅显示一次）。
`SUMSUB_BASE`	可选。默认值为 `https://api.sumsub.com` 。

默认使用有效识别状态（A）。任何关于当前国家/文档类型识别、收集或可用字段的问题——包括“当前可用/识别/收集的字段有哪些”“巴西可用哪些字段”“护照收集哪些信息”等表述——均指向客户端的有效状态，因此需使用识别状态（A）。纯目录仅为默认配置，会给出误导性答案（目录中的“可用”≠客户端已启用）。

仅当用户明确询问抽象层面或跨国家的可能性时，才使用目录查询（B）——例如“哪些国家支持字段X”“护照是否可提取性别信息”“巴西有哪些文档类型”。

关于有效期/有效性检查的问题（“适用哪些有效性检查”“过期文档是否可接受”）→ 使用下方的**(C)**：同时报告

expirationCheckMode

和适用的具体延长规则（60+岁/延长文本），不能仅报告模式。

关于文档处理方式的宽泛问题（“接受规则”“适用哪些设置”“X的配置是什么”）→ 使用下方的**(D)：从GET globalSettings读取完整的有效
(country, docType)
条目，并报告所有**设置（无论开启或关闭）——不要筛选或猜测子集，也不要遗漏默认状态的标志位。

若不确定用户意图，选择A（有效状态）——这是最准确的答案，同时也能告知用户目录允许的配置。

⚠️ 务必通过这些脚本获取数据——切勿读取Paler源码。若你恰好打开了
paler
仓库，请勿从其文件（
documents-by-countries.json
、Java源码等）中获取答案。这些文件仅包含内置目录默认值——客户端的有效状态（
countryMappings
覆盖配置 +
ADVANCED_OCR
）完全不在代码中，仅可通过API获取。读取源码只能得到默认值，会静默给出错误答案。数据必须来自
get_global_settings.sh
/
get_supported_docs.sh
/
get_entitlements.sh
。

A. Effective recognition status (what's really recognised)

A. 有效识别状态（实际可识别的内容）

bash

S=${CLAUDE_SKILL_DIR}/scripts
$S/get_supported_docs.sh  > /tmp/catalogue.json
$S/get_global_settings.sh > /tmp/current.json
ADV=$($S/get_entitlements.sh ADVANCED_OCR >/dev/null 2>&1 && echo true || echo false)

$S/recognition_status.py BRA PASSPORT \
    --current-file /tmp/current.json \
    --catalog-file /tmp/catalogue.json \
    --advanced-ocr "$ADV"

bash

S=${CLAUDE_SKILL_DIR}/scripts
$S/get_supported_docs.sh  > /tmp/catalogue.json
$S/get_global_settings.sh > /tmp/current.json
ADV=$($S/get_entitlements.sh ADVANCED_OCR >/dev/null 2>&1 && echo true || echo false)

$S/recognition_status.py BRA PASSPORT \
    --current-file /tmp/current.json \
    --catalog-file /tmp/catalogue.json \
    --advanced-ocr "$ADV"

Omit the doc type to report ALL doc types for the country in one go

省略文档类型可一次性报告该国所有文档类型

(e.g. "fields for documents from Brazil"):

—

$S/recognition_status.py BRA
--current-file /tmp/current.json --catalog-file /tmp/catalogue.json --advanced-ocr "$ADV"

Reports each field as ✅ recognised (free / PAID) or ⬜ not recognised (with the
reason: default turned off / extra not enabled / ADVANCED_OCR off). Present this
to the user — it's the honest "what's actually recognised" answer.

#（例如“巴西文档的字段”）： $S/recognition_status.py BRA
--current-file /tmp/current.json --catalog-file /tmp/catalogue.json --advanced-ocr "$ADV"

将每个字段标记为✅已识别（免费/付费）或⬜未识别（原因：默认关闭/额外字段未启用/ADVANCED_OCR未开启）。将此结果展示给用户——这是“实际可识别内容”的准确答案。

B. Catalogue query (what's possible)

B. 目录查询（可能的配置）

Fetch the catalogue once:
```
get_supported_docs.sh > /tmp/catalogue.json
```
(reuse it for follow-ups — large and static within a session).
Translate the question into a compact filter spec (see below).

Run the query — spec on stdin, catalogue via

--data-file

bash

echo '{"countries": ["DEU"]}' \
  | ${CLAUDE_SKILL_DIR}/scripts/query_supported_docs.py --data-file /tmp/catalogue.json

Report the slice. If it's a
```
summary
```
(see decision rules), explain the coverage/distribution rather than inventing a list.

获取目录一次：
```
get_supported_docs.sh > /tmp/catalogue.json
```
（会话内可复用——文件较大且静态）。
将问题转换为紧凑的过滤规则（见下文）。

执行查询——标准输入传入规则，通过

--data-file

指定目录：

bash

echo '{"countries": ["DEU"]}' \
  | ${CLAUDE_SKILL_DIR}/scripts/query_supported_docs.py --data-file /tmp/catalogue.json

报告结果片段。若结果为
```
summary
```
（见决策规则），说明覆盖范围/分布情况，而非生成列表。

C. Expiry / validity checks (mode + actual extension rule)

C. 有效期/有效性检查（模式 + 实际延长规则）

For any question about a document's expiry / validity checks ("what validity checks apply", "is an expired X accepted", "validity rules for BRA ID") give BOTH parts — don't stop at the mode:

The mode — resolve it through the full cascade, not just the per-country entry (see the four modes in references/fields-glossary.md):
```
idDocSettings.countryMappings.<country>.<docType>.expirationCheckMode
```
→ if absent, the key-wide
```
poiCheckSettings.expirationCheckMode
```
at the globalSettings root → if absent, the catalogue default for the pair. Both client values come from the same
```
get_global_settings.sh
```
response — don't stop at the
```
(country, docType)
```
entry: a missing per-country mode with
```
poiCheckSettings.expirationCheckMode
```
set means that key-wide mode IS active for the pair.

The actual extension rule — if the mode accepts extended documents (

generallyAcceptedRegulations

localRegulations

), pull the concrete rule that applies and show it. Don't just offer to — include it:

bash

$S/get_extension_rules.sh > /tmp/ext.json
# then filter to the country/doc type, e.g.:
python3 -c "import json;[print(r['docType']['idDocType'],'—',r.get('defaultDescription'))
  for r in json.load(open('/tmp/ext.json'))['rules']
  if r['docType']['country']=='BRA' and r['docType']['idDocType']=='ID_CARD']"

e.g. for BRA/ID_CARD this surfaces "owner 60+ ⇒ valid indefinitely". That rule is the real answer to "what expiry checks apply" — the mode alone is incomplete.

The other validity knobs — a complete validity answer also reports, when set on the globalSettings root:
- ```
poiCheckSettings.minimumResidualValidityInMonths
```
  — ⚠️ 0
  means "accept any validity period" (no requirement), it is what the dashboard writes for the default radio — never report it as "must be valid ≥ 0 months". A non-zero N = the doc must remain valid at least N more months at check time (stricter than "not expired"; the dashboard's custom option defaults to 3).
- ```
ongoingMonitoringSettings.idDocExpireInDays
```
  (with
```
enabled
```
  ) — expiry monitoring after approval: the doc is flagged N days before it expires (dashboard default 7). Absent/0 = no expiry alerting. The whole section is licence-gated (
```
ONGOING_MONITORING_EXPIRED_DOCS
```
  background-check target). Both are key-wide (no per-country variant) — read them from the same
```
get_global_settings.sh
```
  response.
Where the key-wide mode is edited: dashboard → Global Settings → User Verification → ID verification → "ID doc expiry settings". That screen only offers
```
strict
```
("respect validity period"),
```
generallyAcceptedRegulations
```
and, via its extra checkbox,
```
localRegulations
```
— key-wide
```
allowExpired
```
is not settable from the dashboard (per-country entries can still have it via the Supported Documents drawer or the API).

对于任何文档有效期/有效性检查的问题（“适用哪些有效性检查”“过期X是否可接受”“巴西身份证的有效期规则”），需给出两部分内容——不能仅报告模式：

模式——通过完整的级联规则解析，而非仅查看国家条目（见references/fields-glossary.md中的四种模式）：
```
idDocSettings.countryMappings.<country>.<docType>.expirationCheckMode
```
→ 若缺失，使用全局Settings根节点的全局
```
poiCheckSettings.expirationCheckMode
```
→ 若仍缺失，使用该组合的目录默认值。客户端的两个值均来自同一
```
get_global_settings.sh
```
响应——不要仅停留在
```
(country, docType)
```
条目：若国家条目缺失模式，但
```
poiCheckSettings.expirationCheckMode
```
已设置，则该全局模式对该组合生效。

实际延长规则——若模式接受延长文档（

generallyAcceptedRegulations

localRegulations

），提取适用的具体规则并展示。不要仅提及规则存在——需包含具体内容：

bash

$S/get_extension_rules.sh > /tmp/ext.json
# 然后筛选到对应国家/文档类型，例如：
python3 -c "import json;[print(r['docType']['idDocType'],'—',r.get('defaultDescription'))
  for r in json.load(open('/tmp/ext.json'))['rules']
  if r['docType']['country']=='BRA' and r['docType']['idDocType']=='ID_CARD']"

例如，巴西身份证的规则为“60岁以上持有者⇒永久有效”。该规则是“适用哪些有效期检查”的真实答案——仅模式是不完整的。

其他有效性配置——完整的有效性答案还需报告全局Settings根节点上已设置的以下内容：
- ```
poiCheckSettings.minimumResidualValidityInMonths
```
  — ⚠️ 0
  表示“接受任何有效期”（无要求），这是仪表盘默认单选按钮对应的取值——切勿报告为“需至少有效0个月”。非零值N = 检查时文档剩余有效期需至少N个月（比“未过期”更严格；仪表盘自定义选项默认值为3）。
- ```
ongoingMonitoringSettings.idDocExpireInDays
```
  （需
```
enabled
```
  ）——审批后的有效期监控：文档过期前N天会被标记（仪表盘默认值为7）。缺失/0 = 无过期提醒。整个功能需授权（
```
ONGOING_MONITORING_EXPIRED_DOCS
```
  背景检查目标）。两者均为全局配置（无国家级变体）——从同一
```
get_global_settings.sh
```
  响应中读取。
全局模式的编辑位置：仪表盘→全局设置→用户验证→身份证验证→“身份证有效期设置”。该屏幕仅提供
```
strict
```
（“遵循有效期”）、
```
generallyAcceptedRegulations
```
，以及通过额外复选框提供的
```
localRegulations
```
——全局
```
allowExpired
```
无法从仪表盘设置（但国家条目可通过支持文档抽屉或API设置）。

D. Full settings dump (everything that's on/off)

D. 完整设置导出（所有开启/关闭的配置）

For a broad "how is this document handled / what's configured" question, don't hand-pick a subset — read the whole effective

(country, docType)

entry and report every setting on it.

bash

$S/get_global_settings.sh > /tmp/current.json   # client's effective settings
$S/get_supported_docs.sh  > /tmp/catalogue.json  # catalogue, for the default baseline

对于宽泛的“文档如何处理/配置是什么”问题，不要筛选子集——读取完整的有效

(country, docType)

条目并报告所有设置。

bash

$S/get_global_settings.sh > /tmp/current.json   # 客户端有效设置
$S/get_supported_docs.sh  > /tmp/catalogue.json  # 目录，用于默认基准

Pull the entry the client actually has (override), e.g. BRA/ID_CARD:

提取客户端实际的条目（覆盖配置），例如巴西身份证：

NOTE: in GET globalSettings the map is nested under idDocSettings.countryMappings

注意：GET globalSettings中映射嵌套在idDocSettings.countryMappings下

(NOT top-level — that's only the catalogue GET). Using the wrong path → KeyError.

—

python3 -c "import json;print(json.dumps( json.load(open('/tmp/current.json'))['idDocSettings']['countryMappings'].get('BRA',{}).get('ID_CARD',{}), indent=2, ensure_ascii=False))"


Then present every key on that entry as a setting — `supported`,
`sidesSelectionMode` / `doubleSided`, `shouldBeSigned`, `acceptDigitalDoc`,
`acceptScreenshots`, `expirationCheckMode`, `ocrSettings`, sub-type flags,
`defaultFields` / `availableFields`, and anything else present — translating each to
its UI meaning via [references/fields-glossary.md](references/fields-glossary.md).

Rules for an honest dump:
- **Don't curate.** Walk the keys that are actually on the entry; don't decide some
  are "not relevant". A setting you skip reads as "not configured".
- **Defaults are absent (`NON_NULL`).** A missing key is at its default, not off-
  screen. If the client has no override for the pair at all, the whole entry is
  absent — fall back to the catalogue entry (`/tmp/catalogue.json`) for the baseline
  and say these are Sumsub defaults, not client settings.
- **Report independent flags independently.** In particular `acceptDigitalDoc`
  (uploaded files/scans/PDFs) and `acceptScreenshots` (screenshots) are separate
  checks — state each on its own; never merge them or say "only live camera photos".
- **Expiry:** `expirationCheckMode` missing on the entry does NOT mean catalogue
  default — check the key-wide `poiCheckSettings.expirationCheckMode` at the
  globalSettings root first (cascade in **C**). When the effective mode accepts
  extended docs, also surface the concrete extension rule (see **C**) — the mode
  alone is incomplete.

#（非顶层——顶层仅为目录GET接口）。使用错误路径会触发KeyError。 python3 -c "import json;print(json.dumps( json.load(open('/tmp/current.json'))['idDocSettings']['countryMappings'].get('BRA',{}).get('ID_CARD',{}), indent=2, ensure_ascii=False))"


然后将条目上的每个键作为设置展示——`supported`、`sidesSelectionMode`/`doubleSided`、`shouldBeSigned`、`acceptDigitalDoc`、`acceptScreenshots`、`expirationCheckMode`、`ocrSettings`、子类型标志、`defaultFields`/`availableFields`以及其他所有存在的键——通过[references/fields-glossary.md](references/fields-glossary.md)将每个键转换为对应的UI含义。

准确导出规则：
- **不要筛选**。遍历条目上实际存在的键；不要自行判断某些键“无关”。被跳过的设置会被解读为“未配置”。
- **默认值缺失（`NON_NULL`）**。缺失的键即为默认值，并非未显示。若客户端对该组合无任何覆盖配置，则整个条目缺失——需回退到目录条目（`/tmp/catalogue.json`）作为基准，并说明这些是Sumsub默认配置，而非客户端设置。
- **独立标志独立报告**。尤其是`acceptDigitalDoc`（上传文件/扫描件/PDF）和`acceptScreenshots`（截图）是独立检查——分别说明每个标志的状态；切勿合并或表述为“仅接受实时相机照片”。
- **有效期**：条目上缺失`expirationCheckMode`并不意味着使用目录默认值——需先检查全局Settings根节点的全局`poiCheckSettings.expirationCheckMode`（见**C**中的级联规则）。当有效模式接受延长文档时，还需展示具体的延长规则（见**C**）——仅模式是不完整的。

Procedure (edit a client's supported documents) — read-modify-write + PUT

流程（编辑客户端支持的文档）——读取-修改-写入 + PUT

The endpoint is replace-all, so edits are read-modify-write: fetch the current map, let the builder merge your changes into it locally, PUT the full result. Both input files are required by the builder.

Read the catalogue and the CURRENT settings (fetch

current.json

fresh — a stale snapshot would revert edits made in between):

bash

${CLAUDE_SKILL_DIR}/scripts/get_supported_docs.sh  > /tmp/catalogue.json
${CLAUDE_SKILL_DIR}/scripts/get_global_settings.sh > /tmp/current.json

Translate the request into a compact change spec (see below) — only the fields you want to change, per
```
(country, docType)
```
.
Build the full payload (current map + merged changes):
bash
```
echo '<change spec>' | ${CLAUDE_SKILL_DIR}/scripts/build_country_mappings.py \
    --current-file /tmp/current.json --catalog-file /tmp/catalogue.json > /tmp/payload.json
```
The script validates enums and that each field is in the right column, and prints a
```
Field changes:
```
summary. It refuses to auto-move a field to the other column (that would silently replace the other column's list) — fix the spec if it errors. A brand-new
```
(country, docType)
```
override is seeded with the catalogue defaults for
```
supported
```
,
```
doubleSided
```
,
```
doubleSidedCanBeChanged
```
and
```
shouldBeSigned
```
(spec values win; a null catalogue value stays absent), so the new entry keeps behaving like the default it shadows — e.g.
```
doubleSided
```
null would otherwise read as "any side", dropping the catalogue's two-sides requirement. And whenever the spec sets
```
sidesSelectionMode
```
, the deprecated
```
supported
```
/
```
doubleSided
```
pair is synced to the matching legacy values (same dual-write the dashboard does), so pre-
```
sidesSelectionMode
```
readers see the same behavior. Both are reported in the summary.
If the change sets any
extraFields
, verify the ADVANCED_OCR entitlement (billed add-on; without it the backend silently drops them):
bash
```
${CLAUDE_SKILL_DIR}/scripts/get_entitlements.sh ADVANCED_OCR
```
If not enabled, warn the user and don't proceed with extra fields. Default Fields are not gated.

4b. Critical fraud settings need an explicit warning. If the change sets

acceptScreenshots: true

(disables screenshot protection) or

acceptDigitalDoc: true

(accepts easily-modified uploaded files), the build script prints a

warning:

— relay it to the user verbatim and get a clear "yes" before applying. Enabling screenshots especially may approve fake applications and expose the client to penalties/chargebacks. (Turning these OFF is safe and needs no special warning.)

Show the diff and WAIT for explicit confirmation. Diff the payload against the same
```
current.json
```
it was built from (don't hand-write an inline
```
python3 -c
```
diff):
bash
```
${CLAUDE_SKILL_DIR}/scripts/diff_country_mappings.py \
    --current-file /tmp/current.json --payload-file /tmp/payload.json
```
Entries the builder carried over unchanged are silent, so the diff shows only your changes. Anything showing as REMOVED that you didn't intend means the payload was built from the wrong/stale snapshot — rebuild, don't PUT. This is a workspace-wide change — never apply without an explicit "yes".

PUT the confirmed payload:

bash

${CLAUDE_SKILL_DIR}/scripts/put_country_mappings.sh /tmp/payload.json

Report the HTTP status and what changed. On a 4xx, surface the body verbatim. If you set
```
extraFields
```
without ADVANCED_OCR, re-read the settings and note the extra fields were dropped server-side.

Changing one field in a column without losing the others: a column list in the spec replaces that column wholesale. To turn ON one more extra field while keeping the existing ones, first read the current enabled set (
recognition_status.py
) and pass the FULL intended
extraFields
list.

该接口为全量替换，因此编辑需采用读取-修改-写入流程：获取当前映射，让构建器在本地合并你的更改，PUT完整结果。构建器需要两个输入文件。

读取目录和当前设置（重新获取

current.json

——过期快照会覆盖中间的编辑）：

bash

${CLAUDE_SKILL_DIR}/scripts/get_supported_docs.sh  > /tmp/catalogue.json
${CLAUDE_SKILL_DIR}/scripts/get_global_settings.sh > /tmp/current.json

将请求转换为紧凑的更改规则（见下文）——仅列出每个
```
(country, docType)
```
需要更改的字段。
生成完整负载（当前映射 + 合并的更改）：
bash
```
echo '<change spec>' | ${CLAUDE_SKILL_DIR}/scripts/build_country_mappings.py \
    --current-file /tmp/current.json --catalog-file /tmp/catalogue.json > /tmp/payload.json
```
脚本会验证枚举值和每个字段是否属于正确列，并打印
```
Field changes:
```
摘要。它不会自动将字段移动到另一列（这会静默替换另一列的列表）——若报错需修正规则。全新的
```
(country, docType)
```
覆盖配置会使用目录默认值初始化
```
supported
```
、
```
doubleSided
```
、
```
doubleSidedCanBeChanged
```
和
```
shouldBeSigned
```
（规则值优先；目录中的空值保持缺失），因此新条目会保持与被覆盖的默认配置相同的行为——例如
```
doubleSided
```
为空会被解读为“任意面”，而忽略目录的双面要求。当规则设置
```
sidesSelectionMode
```
时，已废弃的
```
supported
```
/
```
doubleSided
```
对会同步为匹配的旧值（与仪表盘的双写逻辑相同），因此支持
```
sidesSelectionMode
```
之前版本的读取器会看到相同行为。这两点都会在摘要中报告。
若更改设置了
extraFields
，验证ADVANCED_OCR授权（付费附加功能；无授权时后端会静默丢弃这些字段）：
bash
```
${CLAUDE_SKILL_DIR}/scripts/get_entitlements.sh ADVANCED_OCR
```
若未启用，需警告用户且不要继续添加额外字段。默认字段无需授权。

4b. 关键防欺诈设置需明确警告。若更改设置

acceptScreenshots: true

（禁用截图保护）或

acceptDigitalDoc: true

（接受易修改的上传文件），构建器会打印

warning:

——需将警告原封不动传达给用户，并在应用前获得明确的“同意”。尤其是启用截图可能会批准虚假申请，使客户面临处罚/退款风险。（关闭这些设置是安全的，无需特殊警告。）

展示差异并等待明确确认。将负载与生成它的
```
current.json
```
进行对比（不要手动编写嵌入式
```
python3 -c
```
对比）：
bash
```
${CLAUDE_SKILL_DIR}/scripts/diff_country_mappings.py \
    --current-file /tmp/current.json --payload-file /tmp/payload.json
```
构建器未更改的条目会被静默处理，因此差异仅显示你的更改。若出现未预期的REMOVED条目，说明负载是基于错误/过期快照生成的——需重新生成，不要PUT。这是全局范围的更改——未获得明确“同意”切勿应用。

PUT已确认的负载：

bash

${CLAUDE_SKILL_DIR}/scripts/put_country_mappings.sh /tmp/payload.json

报告HTTP状态和更改内容。若为4xx错误，原封不动展示响应体。若未启用ADVANCED_OCR却设置了
```
extraFields
```
，需重新读取设置并说明额外字段已被后端丢弃。

更改某列中的一个字段而不丢失其他字段：规则中的列列表会完全替换该列。若要在保留现有字段的基础上启用一个额外字段，需先读取当前启用的字段集（
recognition_status.py
），并传入完整的预期
extraFields
列表。

Procedure (remove / restore default) — PUT

流程（删除/恢复默认）—— PUT

To restore a

(country, docType)

to the catalogue default, remove its override from the full map and PUT the result:

bash

${CLAUDE_SKILL_DIR}/scripts/get_global_settings.sh > /tmp/current.json
${CLAUDE_SKILL_DIR}/scripts/remove_country_mapping.py \
    --current-file /tmp/current.json BRA:ID_CARD > /tmp/payload.json   # full map MINUS the entry

要将

(country, docType)

恢复为目录默认值，需从完整映射中移除其覆盖配置并PUT结果：

bash

${CLAUDE_SKILL_DIR}/scripts/get_global_settings.sh > /tmp/current.json
${CLAUDE_SKILL_DIR}/scripts/remove_country_mapping.py \
    --current-file /tmp/current.json BRA:ID_CARD > /tmp/payload.json   # 完整映射移除指定条目

show the diff (the removal shows as REMOVED), confirm, then PUT:

展示差异（删除会显示为REMOVED），确认后PUT：

${CLAUDE_SKILL_DIR}/scripts/diff_country_mappings.py
--current-file /tmp/current.json --payload-file /tmp/payload.json ${CLAUDE_SKILL_DIR}/scripts/put_country_mappings.sh /tmp/payload.json # PUT (replace-all)

undefined

undefined

Change spec

更改规则

A sparse spec — list only the fields you want to change per

(country, docType)

. Field keys mirror the dashboard "Fields management" screen (two checkbox columns: Default Fields / Extra Fields).

yaml

changes:
  - country: DEU                   # ISO-3
    docType: ID_CARD               # IdDocType
    expirationCheckMode: strict    # scalar settings — merged locally, others preserved
    ocrSettings: {ocrRuleMode: MRZ_DOC}
  - country: BRA
    docType: PASSPORT
    extraFields: [placeOfBirth, gender]   # REPLACES the Extra Fields column (PAID)

This covers the main "Supported ID Documents" screen buttons:

Manage documents — set fields / modes / subtypes (keys below)
Change documents sides — set
```
sidesSelectionMode
```
(
```
oneSide
```
/
```
twoSides
```
/
```
smartMode
```
;
```
disabled
```
= the "Don't accept" option)
Restore default settings — NOT done here; it's a removal → use the separate removal procedure (
```
remove_country_mapping.py
```
) above; the builder refuses
```
remove
```
.

How it maps to recognition and cost (the script reports this):

Default Fields — free; checked fields are recognised. Omit a field to uncheck it (stop recognising). Default fields are checked by default.
Extra Fields — recognised only when checked, and that requires the
```
ADVANCED_OCR
```
entitlement (step 4). These are the paid fields.
A field's column is fixed by the catalogue — you can't list a field under the wrong column. If you do, the script errors out (it will not auto-move the field, because that would silently replace the other column's list) and tells you the correct column — fix the spec. Read the catalogue (
```
{country, docType}
```
query) to see which fields live in which column.
The script prints a
```
Field recognition result:
```
summary per doc listing what's recognised free vs. PAID. Show it to the user on the confirmation step — it speaks the same language as the UI ("Default Fields" / "Extra Fields").

On the wire

extraFields

becomes the API's

availableFields

— the script maps it for you; you only deal in UI terms.

Every other control on the "Fields management" screen is settable too — set the matching key in the change spec. The full UI-control → spec-key table (with enum values and mappings) is in references/fields-glossary.md. Highlights:

User asks	Spec key	Value
accept docs sent as images/files (scans, PDFs) — not just live camera photos	`acceptDigitalDoc`	`true`
accept screenshots specifically	`acceptScreenshots`	`true`
MRZ mode	`ocrSettings: {ocrRuleMode: MRZ_DOC}`
prefer non-latin recognition	`ocrSettings: {preferNonLatinFromOcr: true}`
expiry policy	`expirationCheckMode`	`allowExpired` / `strict` / `generallyAcceptedRegulations` / `localRegulations`
accept only/reject some subtypes	`allowedOcrDocumentTypes` / `forbiddenOcrDocumentTypes`	subtype id list
hide subtypes in WebSDK	`disableDocumentReferences`	`true`
accept this doc type at all	`sidesSelectionMode`	a positive mode to accept; `disabled` to stop accepting
how many sides required	`sidesSelectionMode`	`smartMode` / `oneSide` / `twoSides` / `disabled`

The script validates enum values (

expirationCheckMode

ocrRuleMode

) and fails on typos. Truly internal keys not in the glossary (

shouldBeMaskedSettings

documentReferences

, …) are passed through from the baseline untouched — don't invent values for them.

Deprecated keys are NOT settable —

supported

doubleSided

doubleSidedCanBeChanged

acceptedAsPoa

acceptSameDocAsPoa

are deprecated on the backend;

build_country_mappings.py

rejects them with the replacement to use (sides/acceptance →

sidesSelectionMode

; the POA flags have none — decline the edit). You'll still see them in GET responses — read them for context, never put them in a change spec. The ONE place they're still written is the builder's own seeding of a brand-new override, which copies their defaults from

GET /supportedDocs/documentsByCountries

so the new entry keeps behaving like the catalogue default for legacy readers — that happens automatically, not via the spec.

Gated keys are NOT settable either —

shouldBeSigned

(dashboard-editable only behind the

showRejectByMissingSignatureSetting

feature flag; turns on auto-rejection of unsigned documents) and

shouldBeMasked

(masking of legally protected national IDs — JPN/KOR/NLD/NGA/SGP; for NGA ID_CARD even the dashboard allows only Sumsub staff).

build_country_mappings.py

rejects both. If asked to change them, explain the gate and direct the user to the dashboard (with the flag enabled) or Sumsub support. Reading/reporting them is fine.

The valid entries for

defaultFields

availableFields

are per country and doc type — not a fixed global list. Read the catalogue first (a

field

-level or

{country, docType}

query) to learn the valid field names before building a change spec.

稀疏规则——仅列出每个

(country, docType)

需要更改的字段。字段键与仪表盘“字段管理”屏幕对应（两个复选框列：默认字段 / 额外字段）。

yaml

changes:
  - country: DEU                   # ISO-3代码
    docType: ID_CARD               # IdDocType
    expirationCheckMode: strict    # 标量设置——本地合并，其他配置保留
    ocrSettings: {ocrRuleMode: MRZ_DOC}
  - country: BRA
    docType: PASSPORT
    extraFields: [placeOfBirth, gender]   # 替换额外字段列（付费）

这涵盖了“支持的身份证件”屏幕的主要按钮：

管理文档——设置字段/模式/子类型（见下方键）
更改文档面数——设置
```
sidesSelectionMode
```
（
```
oneSide
```
/
```
twoSides
```
/
```
smartMode
```
；
```
disabled
```
= “不接受”选项）
恢复默认设置——不在此操作；需通过删除流程完成（使用上方的
```
remove_country_mapping.py
```
）；构建器拒绝
```
remove
```
操作。

规则与识别状态和成本的对应关系（脚本会报告）：

默认字段——免费；勾选的字段会被识别。省略字段即为取消勾选（停止识别）。默认字段默认已勾选。
额外字段——仅勾选时会被识别，且需要
```
ADVANCED_OCR
```
授权（步骤4）。这些是付费字段。
字段的列由目录固定——不能将字段列在错误的列下。若错误，脚本会报错（不会自动移动字段，因为这会静默替换另一列的列表）并告知正确列——需修正规则。读取目录（
```
{country, docType}
```
查询）可查看字段所属列。
脚本会打印每个文档的
```
Field recognition result:
```
摘要，列出免费和付费的已识别字段。确认步骤需展示给用户——这与UI语言一致（“默认字段” / “额外字段”）。

在传输时

extraFields

会转换为API的

availableFields

——脚本会自动映射；你只需使用UI术语。

“字段管理”屏幕上的所有其他控件也可设置——在更改规则中设置对应的键。完整的UI控件→规则键对照表（包含枚举值和映射）见references/fields-glossary.md。重点如下：

用户需求	规则键	值
接受以图像/文件形式发送的文档（扫描件、PDF）——而非仅实时相机照片	`acceptDigitalDoc`	`true`
专门接受截图	`acceptScreenshots`	`true`
MRZ模式	`ocrSettings: {ocrRuleMode: MRZ_DOC}`
优先识别非拉丁文字	`ocrSettings: {preferNonLatinFromOcr: true}`
有效期策略	`expirationCheckMode`	`allowExpired` / `strict` / `generallyAcceptedRegulations` / `localRegulations`
仅接受/拒绝某些子类型	`allowedOcrDocumentTypes` / `forbiddenOcrDocumentTypes`	子类型ID列表
在WebSDK中隐藏子类型	`disableDocumentReferences`	`true`
是否接受该文档类型	`sidesSelectionMode`	正值模式表示接受； `disabled` 表示停止接受
需要的面数	`sidesSelectionMode`	`smartMode` / `oneSide` / `twoSides` / `disabled`

脚本会验证枚举值（

expirationCheckMode

ocrRuleMode

），输入错误会报错。术语表中未列出的真正内部键（

shouldBeMaskedSettings

documentReferences

等）会从基准配置中直接传递——不要为这些键自定义值。

已废弃键不可设置——

supported

doubleSided

doubleSidedCanBeChanged

acceptedAsPoa

acceptSameDocAsPoa

在后端已废弃；

build_country_mappings.py

会拒绝这些键并告知替代方案（面数/接受规则→

sidesSelectionMode

；POA标志无替代方案——拒绝编辑）。你仍会在GET响应中看到这些键——可读取作为上下文，但切勿放入更改规则。唯一仍会写入已废弃键的场景是构建器初始化全新覆盖配置时，会从

GET /supportedDocs/documentsByCountries

复制默认值，使新条目对旧读取器保持与目录默认值相同的行为——这会自动完成，无需在规则中设置。

受管控键也不可设置——

shouldBeSigned

（仅在启用

showRejectByMissingSignatureSetting

功能标志后可在仪表盘编辑；开启后会自动拒绝未签名文档）和

shouldBeMasked

（受法律保护的国家ID的掩码——日本/韩国/荷兰/尼日利亚/新加坡；尼日利亚身份证甚至仅允许Sumsub员工在仪表盘编辑）。

build_country_mappings.py

会拒绝这两个键。若用户要求更改这些设置，需说明管控限制并引导用户到仪表盘（启用标志后）或联系Sumsub支持。读取/报告这些键是允许的。

defaultFields

availableFields

的有效条目因国家和文档类型而异——并非固定的全局列表。在生成更改规则前，需先读取目录（字段级或

{country, docType}

查询）了解有效字段名称。

Filter spec

过滤规则

All keys optional. Different keys combine with AND; lists within a key are OR.

yaml

countries: [DEU, FRA]            # ISO-3 codes
docTypes:  [ID_CARD, DRIVERS]    # document types
field:     placeOfBirth          # find where this OCR field exists (inverse query)
fieldKind: available | default | any   # which list to search field in (default: any)
flags:                           # match per-doc boolean flags
  supported: true                # IMPLICIT DEFAULT — unsupported docs are excluded
  doubleSided: false             #   unless you set supported:false explicitly
output:    auto | list | summary # default: auto
limit:     100                   # max items in a list before truncation

所有键均为可选。不同键之间为AND关系；同一键内的列表为OR关系。

yaml

countries: [DEU, FRA]            # ISO-3代码
docTypes:  [ID_CARD, DRIVERS]    # 文档类型
field:     placeOfBirth          # 查询该OCR字段存在的位置（反向查询）
fieldKind: available | default | any   # 搜索字段所在的列表（默认：any）
flags:                           # 匹配文档级布尔标志
  supported: true                # 隐式默认——不支持的文档会被排除
  doubleSided: false             #   除非显式设置supported:false
output:    auto | list | summary # 默认：auto
limit:     100                   # 列表截断前的最大条目数

Examples

示例

Question	Spec
What can I collect for a German ID card?	`{"countries":["DEU"],"docTypes":["ID_CARD"]}`
Which countries/types expose the `category` field?	`{"field":"category","fieldKind":"available"}`
Where is `parentName1` collectable at all?	`{"field":"parentName1"}`
Which docs are double-sided in France?	`{"countries":["FRA"],"flags":{"doubleSided":true}}`
Include unsupported docs too	`{"countries":["DEU"],"flags":{"supported":false}}`

问题	规则
德国身份证可收集哪些信息？	`{"countries":["DEU"],"docTypes":["ID_CARD"]}`
哪些国家/类型支持 `category` 字段？	`{"field":"category","fieldKind":"available"}`
哪些地方可收集 `parentName1` ？	`{"field":"parentName1"}`
法国哪些文档是双面的？	`{"countries":["FRA"],"flags":{"doubleSided":true}}`
同时包含不支持的文档	`{"countries":["DEU"],"flags":{"supported":false}}`

List vs. summary (auto mode)

列表 vs 摘要（自动模式）

The script returns

mode: "list"

for compact results and

mode: "summary"

when a flat list would be useless:

Near-universal field (present in ≥ 80% of matched pairs, e.g.
```
dob
```
,
```
firstName
```
): returns coverage +
```
byDocType
```
; if the field is absent from only a short list, that complement is returned as
```
absentIn
```
.
Too many matches (a field-presence result over 200 pairs): returns coverage +
```
byDocType
```
+
```
topCountries
```
distribution instead of a truncated list.

To force a flat list anyway, set

output: list

and raise

limit

脚本会为紧凑结果返回

mode: "list"

，当扁平列表无意义时返回

mode: "summary"

：

近乎通用的字段（存在于≥80%的匹配组合中，例如
```
dob
```
,
```
firstName
```
）：返回覆盖范围 +
```
byDocType
```
；若字段仅在少量组合中缺失，会将这些组合作为
```
absentIn
```
返回。
匹配结果过多（字段存在性结果超过200个组合）：返回覆盖范围 +
```
byDocType
```
+
```
topCountries
```
分布，而非截断列表。

若需强制返回扁平列表，设置

output: list

并提高

limit

值。

Gotchas

注意事项

Unsupported documents are hidden by default. A doc with
```
supported: false
```
can't be configured, so it's excluded unless you pass
```
flags.supported: false
```
. This keeps coverage math honest (otherwise empty-field unsupported pairs dilute every percentage).
This is the built-in catalogue, not the client's overrides. What a specific client actually has enabled lives in their global settings (
```
idDocSettings.countryMappings
```
) — a different endpoint. Use this skill to learn what's possible, not what a given account has configured.
PROFILE_SCREENSHOT
and a long tail of non-POI types (
```
OTHER
```
,
```
VISA
```
,
```
UTILITY_BILL
```
, …) live in this catalogue too. Filter by
```
docTypes
```
if the user only cares about passports / ID cards / driver's licences.
Verification Level settings override Global Settings. This skill edits the client's global supported-documents config. A specific Verification Level can carry its own supported-documents overrides that take higher priority for applicants on that level. The level opts into this with
```
useCustomIdDocSettings: true
```
— when set, the level's own
```
idDocSettings.countryMappings
```
fully replaces global for that level (a flag absent there is at its default, ignoring global). So a global change may not take effect for a level that overrides it — if a user reports "my change didn't apply", read the level and check
```
useCustomIdDocSettings
```
and its
```
idDocSettings
```
. To actually edit a level's document settings, use the
```
sumsub-create-level
```
skill (GET the level, change the flag in its
```
idDocSettings
```
, PATCH the full level back).

不支持的文档默认隐藏。
```
supported: false
```
的文档无法配置，因此会被排除，除非显式传递
```
flags.supported: false
```
。这能保证覆盖范围计算准确（否则不支持的组合会稀释所有百分比）。
这是内置目录，并非客户端覆盖配置。特定客户端实际启用的配置位于其全局设置（
```
idDocSettings.countryMappings
```
）中——这是另一个接口。使用本技能了解可能的配置，而非特定账户的已配置内容。
PROFILE_SCREENSHOT
和大量非POI类型（
```
OTHER
```
,
```
VISA
```
,
```
UTILITY_BILL
```
等）也在该目录中。若用户仅关心护照/身份证/驾照，需通过
```
docTypes
```
过滤。
验证等级设置优先于全局设置。本技能编辑客户端的全局支持文档配置。特定验证等级可携带自己的支持文档覆盖配置，对该等级的申请人优先级更高。等级需通过
```
useCustomIdDocSettings: true
```
启用此功能——启用后，等级自身的
```
idDocSettings.countryMappings
```
会完全替代全局配置（该配置中缺失的标志位为默认值，忽略全局配置）。因此全局更改可能对启用覆盖的等级无效——若用户报告“我的更改未生效”，需读取该等级并检查
```
useCustomIdDocSettings
```
及其
```
idDocSettings
```
。若要编辑等级的文档设置，需使用
```
sumsub-create-level
```
技能（GET等级，更改其
```
idDocSettings
```
中的标志位，PATCH完整等级）。