sumsub-check-databases

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Check Databases

检查 Databases

Lists the database check-sources Sumsub offers for a country, each source's enablement status for the current tenant, and how it plugs into a verification level. Callers use it to gate database / non-document verification before building a level.

Scope: KYC (individual) only — for now. The endpoint returns only individual/person check-sources. Company (KYB) database verification is not exposed here yet; don't use this skill to place company/business sources.

列出 Sumsub 为某个国家提供的 database check-source、每个 source 针对当前 tenant 的启用状态，以及它如何接入 verification level。调用方会在构建 level 前，使用它来控制 database / non-document verification 是否可用。

范围：仅限 KYC（个人）——目前如此。 该 endpoint 仅返回 individual/person check-source。目前尚未在这里提供 Company（KYB）database verification；不要使用此 skill 放置 company/business source。

Endpoint

GET https://api.sumsub.com/resources/api/agent/settings/checkSources?country=<country>

country

is an ISO alpha-3 code (e.g.

DEU

). If the user names a country, convert it to alpha-3 before calling. Omit

country

to return the full catalog. An unrecognized or unsupported code is not an error — it returns HTTP 200 with an empty

checkSources

list.

Pass
country
whenever you can. The unfiltered response is the entire catalog — hundreds of entries across every country, large enough to bloat or truncate your context. If the user named a country, filter by it. If they didn't, prefer asking which country they need before calling unfiltered; only omit
country
when you deliberately want the whole catalog and can handle a large response.

GET https://api.sumsub.com/resources/api/agent/settings/checkSources?country=<country>

country

是 ISO alpha-3 code（例如

DEU

）。如果用户提供国家名称，请在调用前将其转换为 alpha-3 code。省略

country

可返回完整目录。无法识别或不受支持的 code 不算错误——接口会返回 HTTP 200 和空的

checkSources

列表。

尽可能始终传入
country
。未过滤的响应是完整目录——包含所有国家的数百个条目，足以导致 context 膨胀或被截断。如果用户指定了国家，请按国家过滤。如果没有指定，优先询问用户需要哪个国家，再决定是否调用未过滤接口；只有在明确需要完整目录且能够处理大型响应时，才应省略
country
。

Auth — App Token + secret (sandbox only)

身份验证——App Token + secret（仅限 sandbox）

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

此 skill 会调用公开的 Sumsub API，并按照身份验证参考文档对每个请求进行签名。完整原理说明位于

sumsub-api-auth

skill 中——如果遇到

401 Invalid signature

，请阅读该文档。

⚠️ 仅限 Sandbox token。 不要在这里接受或使用 production App Token。如果用户提供了一个，请拒绝并要求其在 https://cockpit.sumsub.com/checkus/devSpace/appTokens 生成 sandbox token 对（先将 workspace 切换到 Sandbox，再点击 Create）。Token + secret 只显示一次——关闭对话框前请同时复制两者。辅助脚本会强制执行此限制——拒绝不以
sbx:
开头的 token。

变量	示例
`SUMSUB_APP_TOKEN`	`sbx:...` ——从 dashboard 获取的 sandbox App Token。
`SUMSUB_SECRET_KEY`	创建 token 时一次性显示的配对 secret。
`SUMSUB_BASE`	可选。默认为 `https://api.sumsub.com` 。

Usage

用法

bash

bash ${CLAUDE_SKILL_DIR}/scripts/check_databases.sh <country>

Output: raw Sumsub response body followed by

HTTP <code>

Success (HTTP 200):

json

{"checkSources": [
  {
    "sourceId": "arg_gov_dni",
    "name": "Argentina DNI Verification",
    "description": "Verifying user's personal, biometric, and residency data against official government sources.",
    "dataSources": [
      "National Registry of Persons (Registro Nacional de las Personas - RENAPER)",
      "Agency of Public Revenues and Control (Agencia de Recaudación y Control Aduanero – ARCA)"
    ],
    "country": "ARG",
    "checkType": "E_KYC_CHECK",
    "confirmationType": "otp",
    "status": "ENABLED",
    "validationReady": false,
    "stepsReady": ["E_KYC", "IDENTITY"],
    "supportedDocuments": ["ID_CARD"],
    "requiredInputFields": ["gender", "number"],
    "optionalInputFields": ["address.postCode"],
    "selfieRequirement": "ADDITIONAL",
    "outputFields": ["firstName", "lastName", "addresses", "gender", "nationality", "dob", "tin"],
    "violations": ["GENDER_MISMATCH", "DEAD", "PERSON_IS_MINOR", "SELFIE_MISMATCH"]
  }
]}
HTTP 200

Input-field values are machine field names on the background-check input data —

number

dob

address.postCode

bankAccount.bankName

— not display labels. Dotted names are nested objects (

address.*

bankAccount.*

). Translate them into something readable when you show them to a user.

A selfie is never listed in the input fields — it has its own

selfieRequirement

field. Read that, not

optionalInputFields

, to decide whether the flow needs a selfie step.

bash

bash ${CLAUDE_SKILL_DIR}/scripts/check_databases.sh <country>

输出：原始 Sumsub response body，后跟

HTTP <code>

。

成功（HTTP 200）：

json

{"checkSources": [
  {
    "sourceId": "arg_gov_dni",
    "name": "Argentina DNI Verification",
    "description": "Verifying user's personal, biometric, and residency data against official government sources.",
    "dataSources": [
      "National Registry of Persons (Registro Nacional de las Personas - RENAPER)",
      "Agency of Public Revenues and Control (Agencia de Recaudación y Control Aduanero – ARCA)"
    ],
    "country": "ARG",
    "checkType": "E_KYC_CHECK",
    "confirmationType": "otp",
    "status": "ENABLED",
    "validationReady": false,
    "stepsReady": ["E_KYC", "IDENTITY"],
    "supportedDocuments": ["ID_CARD"],
    "requiredInputFields": ["gender", "number"],
    "optionalInputFields": ["address.postCode"],
    "selfieRequirement": "ADDITIONAL",
    "outputFields": ["firstName", "lastName", "addresses", "gender", "nationality", "dob", "tin"],
    "violations": ["GENDER_MISMATCH", "DEAD", "PERSON_IS_MINOR", "SELFIE_MISMATCH"]
  }
]}
HTTP 200

输入字段值是 background-check input data 上的机器字段名——例如

number

、

dob

、

address.postCode

、

bankAccount.bankName

——而不是显示标签。带点号的名称表示嵌套对象（

address.*

、

bankAccount.*

）。向用户展示时，应将其转换为易读形式。

输入字段中绝不会列出 selfie——它有独立的

selfieRequirement

字段。判断流程是否需要 selfie 步骤时，应读取该字段，而不是

optionalInputFields

。

Field reference

字段参考

Field	Meaning
`sourceId`	Stable id of the check-source ( `{country}_{provider}_{subject}` ).
`name`	Human-readable source name (English), e.g. "Argentina DNI Verification".
`description`	One-line English description of what the source verifies. May be absent.
`dataSources`	Underlying registries / providers the source draws on (English names). May be absent.
`country`	Canonical ISO alpha-3 the source covers.
`checkType`	Internal category ( `E_KYC_CHECK` , `PERSON` , `TIN` ) — informational, not a filter. Company (KYB) types are not returned.
`confirmationType`	How the applicant confirms a non-document check: `otp` , `oAuth` (log in to a bank / national eID service), or `eID` (NFC scan of an eID card). Absent when the source needs no confirmation step.
`status`	Per-tenant enablement, the usability gate: `ENABLED` (licensed in production, and so in sandbox too) / `SANDBOX_ONLY` (licensed in sandbox only — works for testing, will not run in production) / `DISABLED` (not licensed anywhere). See below.
`validationReady`	`true` if the source can cross-validate a document already being collected (database validation).
`stepsReady`	Level step type(s) ( `IdDocSetType` , e.g. `E_KYC` , `IDENTITY` ) the source is ready to be used as a non-document check for. Empty if none.
`supportedDocuments`	`IdDocType` s the source can validate.
`requiredInputFields` / `optionalInputFields`	Machine field names the applicant must / may supply (e.g. `number` , `dob` , `address.postCode` ) — background-check input data keys, not display labels. Never includes the selfie.
`selfieRequirement`	`REQUIRED` (the source can't run without a selfie) / `ADDITIONAL` (optional, improves the match) / absent (no selfie needed).
`outputFields`	Fields the source returns on a match.
`violations`	Possible violation reasons the source can raise (e.g. `GENDER_MISMATCH` , `DEAD` ).

Full types, enum values, and meanings:

references/checksources-schema.md

字段	含义
`sourceId`	check-source 的稳定 id（ `{country}_{provider}_{subject}` ）。
`name`	便于阅读的 source 名称（英文），例如“Argentina DNI Verification”。
`description`	一行英文说明，描述该 source 验证的内容。可能不存在。
`dataSources`	该 source 使用的底层 registry / provider（英文名称）。可能不存在。
`country`	该 source 覆盖的标准 ISO alpha-3 code。
`checkType`	内部 category（ `E_KYC_CHECK` 、 `PERSON` 、 `TIN` ）——仅供参考，不是过滤条件。不会返回 Company（KYB）type。
`confirmationType`	申请人确认 non-document check 的方式： `otp` 、 `oAuth` （登录银行 / national eID service）或 `eID` （通过 NFC 扫描 eID card）。如果 source 不需要确认步骤，则不会返回此字段。
`status`	tenant 级别的启用状态，也是可用性判断门槛： `ENABLED` （已获得 production 授权，因此 sandbox 中也可用）/ `SANDBOX_ONLY` （仅在 sandbox 中获得授权——可用于测试，但无法在 production 中运行）/ `DISABLED` （任何环境中都未获得授权）。详见下文。
`validationReady`	如果为 `true` ，表示该 source 可以对正在采集的 document 进行交叉验证（database validation）。
`stepsReady`	该 source 可作为 non-document check 使用的 level step type（ `IdDocSetType` ，例如 `E_KYC` 、 `IDENTITY` ）。如果不存在可用类型，则为空。
`supportedDocuments`	该 source 可以验证的 `IdDocType` 。
`requiredInputFields` / `optionalInputFields`	申请人必须 / 可以提供的机器字段名，例如 `number` 、 `dob` 、 `address.postCode` ——它们是 background-check input data 的 key，而不是显示标签。绝不会包含 selfie。
`selfieRequirement`	`REQUIRED` （没有 selfie 就无法运行该 source）/ `ADDITIONAL` （可选，有助于提升匹配度）/ 不存在（不需要 selfie）。
`outputFields`	匹配成功时，该 source 返回的字段。
`violations`	该 source 可能触发的 violation 原因，例如 `GENDER_MISMATCH` 、 `DEAD` 。

完整类型、enum value 及其含义请参阅

references/checksources-schema.md

。

How callers should use this

调用方应如何使用

If the HTTP status is not 200, stop immediately — show the error body to the user and do not proceed.
An empty
checkSources
list is not an error. It means Sumsub offers no KYC database sources for that country — or the
```
country
```
value wasn't a recognized ISO alpha-3 code. Tell the user no database check-sources are available for that country; if they gave a country name, double-check it mapped to the right alpha-3 code (e.g.
```
Germany
```
→
```
DEU
```
) and offer to retry. Never fabricate sources. A database layer is optional, so fall back to document-based verification (see the placement branches below).
Check status
— per-tenant and environment-independent (the same value comes back whether you query from sandbox or prod).
```
ENABLED
```
: licensed in production and therefore in sandbox too — usable, proceed.
```
SANDBOX_ONLY
```
: licensed in sandbox only — usable for sandbox testing, but the level will not run this source in production, so say that explicitly and point the user at enablement before they go live.
```
DISABLED
```
: not licensed anywhere — not usable. For anything other than
```
ENABLED
```
, see Enabling a source below.
If the source the user needs is unavailable, don't silently drop it and don't blanket hard-stop. A missing check-source (unlike a missing entitlement) still leaves a valid document-based level — so surface the gap, don't block it. Then branch by what the source was for:

What the user wanted	Source unavailable → do this
Database validation (document + DB cross-check)	Soft: the document verification still stands. Confirm, then continue without the DB layer.
Non-doc in identity step (source nested inside `IDENTITY` )	Offer the fallback: switch that identity step back to document upload. Continue after the user picks.
Non-doc, standalone (a database-only step was the whole point)	Closest to a stop: the step can't exist without a source. Present the document-based alternative; proceed only on explicit confirmation.

Never silently downgrade and never unilaterally hard-stop — surface the gap + impact and let the user (via the caller) decide. The one hard stop that still applies: non-doc identity also needs the

E_KYC_TARGET

entitlement, which

sumsub-check-permissions

gates independently.

如果 HTTP status 不是 200，立即停止——向用户展示 error body，不要继续执行。
空的
checkSources
列表不算错误。这意味着 Sumsub 没有为该国家提供 KYC database source，或者
```
country
```
不是受支持的 ISO alpha-3 code。告知用户该国家没有可用的 database check-source；如果用户提供的是国家名称，请再次确认是否正确映射到了相应的 alpha-3 code（例如
```
Germany
```
→
```
DEU
```
），并提出重试。不要伪造 source。Database layer 是可选的，因此可以回退到基于 document 的 verification（见下方的配置分支）。
检查 status
——它按 tenant 划分，且与环境无关（无论从 sandbox 还是 prod 查询，返回的值都相同）。
```
ENABLED
```
：已获得 production 授权，因此 sandbox 中也可用——可以继续使用。
```
SANDBOX_ONLY
```
：仅在 sandbox 中获得授权——可用于 sandbox 测试，但 level 在 production 中无法运行该 source，因此必须明确告知用户，并提示其在正式上线前完成启用。
```
DISABLED
```
：任何环境中都未获得授权——不可用。对于
```
ENABLED
```
以外的状态，请参阅下方的启用 source。
如果用户需要的 source 不可用，不要静默移除它，也不要笼统地 hard-stop。 缺少 check-source（不同于缺少 entitlement）时，仍然可以创建有效的基于 document 的 level——因此应明确告知这一缺口，而不要阻止流程。然后根据该 source 的用途进行分支处理：

用户需要的用途	Source 不可用时的处理方式
Database validation（document + DB cross-check）	柔性处理：document verification 仍然有效。确认后，不带 DB layer 继续执行。
Identity step 中的 non-doc（嵌套在 `IDENTITY` 内的 source）	提供 fallback：将该 identity step 改回 document upload。用户作出选择后继续。
独立的 non-doc（整个流程仅依赖 database step）	这是最接近必须中止的情况：没有 source，该 step 就无法存在。提供基于 document 的替代方案；只有在用户明确确认后才继续。

绝不能静默降级，也绝不能单方面 hard-stop——应说明缺口及其影响，再由用户（通过调用方）作出决定。唯一仍然适用的 hard stop 是：non-doc identity 还需要

E_KYC_TARGET

entitlement，该权限由

sumsub-check-permissions

单独控制。

Enabling a source

启用 source

Enabling isn't something the agent can do: there is no public API to enable a check-source. This covers both

DISABLED

(nothing works) and

SANDBOX_ONLY

(sandbox works, production doesn't). Tell the user which database check is missing and in which environment — name the specific source by its
name
, and note its
sourceId
— and what verification is lost. Then point them to:

Databases → Available products in the Sumsub dashboard — self-serve enablement for most sources.
If the source isn't self-serve-enablable there, the user contacts their Customer Success Manager / Sumsub Support to request it.

Agent 无法完成启用操作：目前没有用于启用 check-source 的公开 API。这同时适用于

DISABLED

（完全无法使用）和

SANDBOX_ONLY

（sandbox 可用，production 不可用）的情况。告知用户缺少哪个 database check、缺少的是哪个环境——使用其
name
指明具体 source，并同时注明
sourceId
——以及会损失哪项验证能力。然后指引用户前往：

Sumsub dashboard 中的 Databases → Available products——大多数 source 可在此自助启用。
如果该 source 无法在此自助启用，用户需要联系其 Customer Success Manager / Sumsub Support 提出申请。

Where each source goes in a level

每个 source 在 level 中的位置

A chosen source is wired into the level's

checkSourceSettings.countrySettings[]

— one entry per

country

checkType

when placed at the level's top level), listing the

sourceId

under

executionConfigurations

validationReady

and

stepsReady

tell you which placement(s) apply.

sumsub-create-level

builds the full payload — this skill decides the placement.

A source can be

validationReady

and/or have entries in

stepsReady

at once — check both, they're independent signals. If

stepsReady

lists more than one step type, that's a menu of valid homes for the same source, not a mandate to use all of them at once — pick the one placement that matches the user's intent.

Placement (ticket)	Signalled by	What it means in the level
Database validation	`validationReady: true`	Keep the document docSet (e.g. `IDENTITY` ) — the applicant still submits a document. Attach the source at the level's top-level `checkSourceSettings` (a sibling of `requiredIdDocs` , not nested inside it).
Non-doc, standalone	`stepsReady` contains the step type on its own (e.g. `E_KYC` )	A dedicated non-document docSet, no upload — `E_KYC` for identity (needs `E_KYC_TARGET` , verify via `sumsub-check-permissions` ). The applicant supplies `requiredInputFields` , checked against the database. Attach the source nested inside that docSet's own `checkSourceSettings` .
Non-doc in an existing step	`stepsReady` contains the step type (e.g. `IDENTITY` ) alongside an already-required document step	Keep the document docSet's `types` (document upload stays optional) and nest the source's `checkSourceSettings` inside that same docSet — the applicant chooses upload or the database check in one step. Also needs `E_KYC_TARGET` .

In every case the source is referenced via

country

checkType

(top-level placement only), and

executionConfigurations[].sourceId

. Optional

fallbackReasons

(

NO_DATA

NAME_MISMATCH

DOB_MISMATCH

INVALID_DOC_NUMBER

FAILED

DEAD

) let the flow fall back to another source or a document when the check can't confirm. See the worked examples in

sumsub-create-level/examples/

identity-selfie-with-database-validation.json

(top-level,

validationReady

identity-with-non-doc-selfie.json

(nested in

IDENTITY

non-doc.json

(standalone

E_KYC

Concept references: no-document verification, database validation.

选定的 source 会接入 level 的

checkSourceSettings.countrySettings[]

——每个

country

对应一个条目（在 level 顶层放置时还需加上

checkType

），并在

executionConfigurations

下列出

sourceId

。

validationReady

和

stepsReady

会告诉你适用的配置位置。

sumsub-create-level

用于构建完整 payload——此 skill 负责决定放置位置。

一个 source 可以同时是

validationReady

，并且在

stepsReady

中包含条目——必须同时检查两者，因为它们是相互独立的信号。如果

stepsReady

列出多个 step type，这表示同一个 source 有多个有效放置位置，并不要求全部同时使用——应选择与用户意图相符的位置。

配置位置（ticket）	判定信号	在 level 中的含义
Database validation	`validationReady: true`	保留 document docSet（例如 `IDENTITY` ）——申请人仍需提交 document。将 source 附加到 level 顶层的 `checkSourceSettings` （它是 `requiredIdDocs` 的同级项，而不是嵌套在其中）。
独立的 non-doc	`stepsReady` 单独包含该 step type（例如 `E_KYC` ）	使用专用的 non-document docSet，不上传文件——身份验证使用 `E_KYC` （需要 `E_KYC_TARGET` ，请通过 `sumsub-check-permissions` 验证）。申请人提供 `requiredInputFields` ，系统会将这些字段与 database 进行核对。将 source 的 `checkSourceSettings` 嵌套在该 docSet 自身的 `checkSourceSettings` 内。
现有 step 中的 non-doc	`stepsReady` 包含该 step type（例如 `IDENTITY` ），且同一 level 中已有必需的 document step	保留 document docSet 的 `types` （document upload 仍为可选），并将 source 的 `checkSourceSettings` 嵌套在同一个 docSet 内——申请人可在同一步骤中选择 upload 或 database check。还需要 `E_KYC_TARGET` 。

在所有情况下，source 都通过

country

、

checkType

（仅顶层放置需要）和

executionConfigurations[].sourceId

引用。可选的

fallbackReasons

（

NO_DATA

、

NAME_MISMATCH

、

DOB_MISMATCH

、

INVALID_DOC_NUMBER

、

FAILED

、

DEAD

）允许在 check 无法确认时回退到另一个 source 或 document。实际示例请参阅

sumsub-create-level/examples/

：顶层放置的

identity-selfie-with-database-validation.json

（

validationReady

）、嵌套在

IDENTITY

中的

identity-with-non-doc-selfie.json

，以及独立的

non-doc.json

（

E_KYC

）。

概念参考：no-document verification、database validation。

另请参阅

```
sumsub-create-level
```
— builds the level these sources plug into.
```
sumsub-check-permissions
```
— gate the
```
E_KYC_TARGET
```
entitlement for non-doc identity.
```
sumsub-api-auth
```
— request signing details.
```
references/checksources-schema.md
```
— full response schema, field types, and enum values.

```
sumsub-create-level
```
——构建这些 source 所接入的 level。
```
sumsub-check-permissions
```
——控制 non-doc identity 所需的
```
E_KYC_TARGET
```
entitlement。
```
sumsub-api-auth
```
——请求签名详情。
```
references/checksources-schema.md
```
——完整 response schema、字段类型和 enum value。

sumsub-check-databases

Original

Translation

Check Databases

检查 Databases

Endpoint

Endpoint

Auth — App Token + secret (sandbox only)

身份验证——App Token + secret（仅限 sandbox）

Usage

用法

Field reference

字段参考

How callers should use this

调用方应如何使用

Enabling a source

启用 source

Where each source goes in a level

每个 source 在 level 中的位置

See also

另请参阅