Sumsub — Supported Documents Reference

documentsByCountries

Endpoints

GET

/resources/api/agent/supportedDocs/documentsByCountries

GET

/resources/api/agent/globalSettings

idDocSettings.countryMappings

GET

/resources/api/agent/globalSettings/extensionRules

PUT

/resources/api/agent/globalSettings/idDocSettings/countryMappings

manageClientSettings

{ "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.

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

idDocSettings.countryMappings

poiCheckSettings.expirationCheckMode

poiCheckSettings.minimumResidualValidityInMonths

0

ongoingMonitoringSettings

enabled

idDocExpireInDays

minAge

maxAge

idDocSettings.ekycSourceMappings

countryMappings

countryMappings

enableAutoCompleteShortDates

imageConstraints

minFileSize

maxFileSize

poaCheckSettings

validMonths

acceptIdAsPoa

acceptSameDocAsPoa

crossValidatorSettings

nameComparisonMode

fuzzyThreshold

watchListCheckSettings

cryptoCheckSettings

bankCardCheckSettings

kybIntegrationSettings

uiSettings

duplicateSettings

sourceKeysSettings

applicantTags

supportEmail

disableSumsubId

idDocServiceSettings

Auth — App Token + secret (sandbox only)

sumsub-api-auth

SUMSUB_APP_TOKEN

sbx:...

SUMSUB_SECRET_KEY

SUMSUB_BASE

https://api.sumsub.com

expirationCheckMode

(country, docType)

⚠️ 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

.

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

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"

B. Catalogue query (what's possible)

1. Fetch the catalogue once:

   get_supported_docs.sh > /tmp/catalogue.json

   (reuse it for follow-ups — large and static within a session).
2. Translate the question into a compact filter spec (see below).
3. 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

4. Report the slice. If it's a

   summary

   (see decision rules), explain the coverage/distribution rather than inventing a list.

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

1. 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.
2. 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.
3. 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).

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

(country, docType)

$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
# Pull the entry the client actually has (override), e.g. BRA/ID_CARD:
# NOTE: in GET globalSettings the map is nested under 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))"

supported

sidesSelectionMode

doubleSided

shouldBeSigned

acceptDigitalDoc

acceptScreenshots

expirationCheckMode

ocrSettings

defaultFields

availableFields

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

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

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

2. Translate the request into a compact change spec (see below) — only the fields you want to change, per

   (country, docType)

   .
3. 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.
4. 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.

acceptScreenshots: true

acceptDigitalDoc: true

warning:

1. 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".
2. PUT the confirmed payload:
   bash

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

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

Procedure (remove / restore default) — PUT

(country, docType)

${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
# show the diff (the removal shows as REMOVED), confirm, then 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)

Change spec

(country, docType)

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)

• 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

  .

• 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").

extraFields

availableFields

acceptDigitalDoc

true

acceptScreenshots

true

ocrSettings: {ocrRuleMode: MRZ_DOC}

ocrSettings: {preferNonLatinFromOcr: true}

expirationCheckMode

allowExpired

strict

generallyAcceptedRegulations

localRegulations

allowedOcrDocumentTypes

forbiddenOcrDocumentTypes

disableDocumentReferences

true

sidesSelectionMode

disabled

sidesSelectionMode

smartMode

oneSide

twoSides

disabled

expirationCheckMode

ocrRuleMode

shouldBeMaskedSettings

documentReferences

supported

doubleSided

doubleSidedCanBeChanged

acceptedAsPoa

acceptSameDocAsPoa

build_country_mappings.py

sidesSelectionMode

GET /supportedDocs/documentsByCountries

shouldBeSigned

showRejectByMissingSignatureSetting

shouldBeMasked

build_country_mappings.py

defaultFields

availableFields

field

{country, docType}

Filter spec

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

Examples

{"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)

mode: "list"

mode: "summary"

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

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