Check 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.
Endpoint
GET https://api.sumsub.com/resources/api/agent/settings/checkSources?country=<country>
is an
ISO alpha-3 code (e.g.
). If the user names a country, convert it to alpha-3 before calling. Omit
to return the full catalog. An unrecognized or unsupported code is
not an error — it returns HTTP 200 with an empty
list.
Pass 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
when you deliberately want the whole catalog and can handle a large response.
Auth — App Token + secret (sandbox only)
This skill talks to the public Sumsub API and signs each request per
the authentication reference.
The full how-it-works writeup lives in the
skill — read it if you hit
.
⚠️ 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
.
| Var | Example |
|---|
| — sandbox App Token from the dashboard. |
| The paired secret shown once at token creation. |
| Optional. Defaults to . |
Usage
bash
bash ${CLAUDE_SKILL_DIR}/scripts/check_databases.sh <country>
Output: raw Sumsub response body followed by
.
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 —
,
,
,
— not display labels. Dotted names are nested objects (
,
). 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
field. Read that, not
, to decide whether the flow needs a selfie step.
Field reference
| Field | Meaning |
|---|
| Stable id of the check-source ({country}_{provider}_{subject}
|
| Human-readable source name (English), e.g. "Argentina DNI Verification". |
| One-line English description of what the source verifies. May be absent. |
| Underlying registries / providers the source draws on (English names). May be absent. |
| Canonical ISO alpha-3 the source covers. |
| Internal category (, , ) — informational, not a filter. Company (KYB) types are not returned. |
| How the applicant confirms a non-document check: , (log in to a bank / national eID service), or (NFC scan of an eID card). Absent when the source needs no confirmation step. |
| Per-tenant enablement, the usability gate: (licensed in production, and so in sandbox too) / (licensed in sandbox only — works for testing, will not run in production) / (not licensed anywhere). See below. |
| if the source can cross-validate a document already being collected (database validation). |
| Level step type(s) (, e.g. , ) the source is ready to be used as a non-document check for. Empty if none. |
| s the source can validate. |
| / | Machine field names the applicant must / may supply (e.g. , , ) — background-check input data keys, not display labels. Never includes the selfie. |
| (the source can't run without a selfie) / (optional, improves the match) / absent (no selfie needed). |
| Fields the source returns on a match. |
| Possible violation reasons the source can raise (e.g. , ). |
Full types, enum values, and meanings:
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 list is not an error. It means Sumsub offers no KYC database sources for that country — or the 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. → ) 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 — per-tenant and environment-independent (the same value comes back whether you query from sandbox or prod). : licensed in production and therefore in sandbox too — usable, proceed. : 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. : not licensed anywhere — not usable. For anything other than , 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 ) | 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
entitlement, which
gates independently.
Enabling a source
Enabling isn't something the agent can do: there is
no public API to enable a check-source. This covers both
(nothing works) and
(sandbox works, production doesn't). Tell the user which database check is missing and in which environment —
name the specific source by its , and note its — 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.
Where each source goes in a level
A chosen source is wired into the level's
checkSourceSettings.countrySettings[]
— one entry per
(+
when placed at the level's top level), listing the
under
.
and
tell you
which placement(s) apply.
builds the full payload — this skill decides the placement.
A source can be
and/or have entries in
at once — check both, they're independent signals. If
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 | | Keep the document docSet (e.g. ) — the applicant still submits a document. Attach the source at the level's top-level (a sibling of , not nested inside it). |
| Non-doc, standalone | contains the step type on its own (e.g. ) | A dedicated non-document docSet, no upload — for identity (needs , verify via ). The applicant supplies , checked against the database. Attach the source nested inside that docSet's own . |
| Non-doc in an existing step | contains the step type (e.g. ) alongside an already-required document step | Keep the document docSet's (document upload stays optional) and nest the source's inside that same docSet — the applicant chooses upload or the database check in one step. Also needs . |
In every case the source is referenced via
,
(top-level placement only), and
executionConfigurations[].sourceId
. Optional
(
,
,
,
,
,
) 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,
),
identity-with-non-doc-selfie.json
(nested in
),
(standalone
).
See also
- — builds the level these sources plug into.
- — gate the entitlement for non-doc identity.
- — request signing details.
references/checksources-schema.md