sumsub-analyze-regulation

Sumsub — Analyze Regulation

Reads a regulation document and produces a structured Sumsub configuration plan — mapping each regulatory requirement to the Sumsub entities that satisfy it, with a clear split between what can be configured now via skills and what requires the Sumsub Dashboard.

This is a planning skill only. It produces a text description, never JSON payloads or API calls.

Workflow

Step 1 — Gather context

Before analyzing, collect:

• Jurisdiction — if the document covers multiple countries or is ambiguous, ask explicitly: "This regulation covers [list of countries]. Which jurisdiction should the plan focus on?" Do not generate a plan for all jurisdictions simultaneously without a direct request to do so.
• Business type — crypto exchange, neobank, iGaming, fintech, or other. Ask if not clear from the document.
• Client types — individuals, companies, or both.
• Existing Sumsub setup — has the user already configured anything? Avoid suggesting duplicates.

Step 2 — Analyze (think before responding)

Use extended thinking before formulating the response. Extract from the document:

• Customer identification requirements (who must be identified, what data is required)
• Acceptable identity documents (national ID, passport, tax number, etc.)
• Address verification requirements (what documents are accepted, maximum age)
• Enhanced Due Diligence conditions (what triggers EDD)
• Source of funds / wealth / PEP data collection requirements
• AML screening obligations (PEP / sanctions / adverse media) and how screening hits must be handled (false-positive clearing, PEP review policy, escalation of confirmed matches)
• Transaction monitoring requirements (thresholds, suspicious patterns, crypto Travel Rule)
• Periodic re-KYC obligations (how often customers must be re-verified)
• What is out of scope for Sumsub (data retention timelines, regulatory reporting, sanctions list maintenance)

Step 3 — Validate understanding first

After analysis, present a short "My Understanding" block — bullet points of extracted requirements — and ask: "Have I understood the key requirements correctly? Anything to add or correct?"

Do not generate the full plan until the user confirms. This is mandatory.

Step 4 — Generate the plan

Only after user confirmation, produce the full configuration plan using the output format below.

---

Sumsub Capability Map

A. Verification Levels — sumsub-create-level

Defines the sequence of verification steps an applicant must complete. Each step is a docSet.

Available docSet types:

Type	Purpose
IDENTITY	Document verification: PASSPORT, ID_CARD, DRIVERS, RESIDENCE_PERMIT, VOTER_ID, etc. Can be restricted by issuing country.
SELFIE / SELFIE2	Biometrics and liveness.
APPLICANT_DATA	Personal data collection: full name, date of birth, address, nationality, tax number (TIN/CPF/CNPJ/etc.).
PROOF_OF_RESIDENCE / PROOF_OF_RESIDENCE2	Address document verification. References a PoA preset by poaStepSettingsId.
PHONE_VERIFICATION / EMAIL_VERIFICATION	Contact verification via OTP.
QUESTIONNAIRE / QUESTIONNAIRE2–4	Custom form. References a questionnaire definition by questionnaireDefId.
E_KYC	Non-document electronic verification against external databases. See E-KYC section.
DEVICE_CHECK	Device intelligence and fingerprinting. Requires DEVICE_INTELLIGENCE license.
COMPANY	KYB: company info collection.
COMPANY_DATA	KYB: company data fields.
COMPANY_DOCUMENTS	KYB: corporate documents upload.
COMPANY_BENEFICIARIES	KYB: UBOs and representatives verification.
ACCREDITED_INVESTOR	Accredited investor qualification.
E_SIGN	Electronic signature capture.
TR_RECIPIENT_INFORMATION	Travel Rule recipient data collection.

Level properties:

• applicantType: individual or company
• requiredIdDocs: the ordered list of docSets + optional includedCountries / excludedCountries
• disableWatchlists: set to true if tenant has WATCHLISTS entitlement but needs to disable AML Screening for a particular level
• crossCheckPresetId: cross-check preset for AML screening

IDENTITY — document type codes

Sumsub uses generic IdDocType values regardless of what the document is locally called. Map the regulation's document names to these types:

Generic document class	Sumsub IdDocType
International / biometric passport	PASSPORT
National identity card (any country)	ID_CARD
Driver's licence	DRIVERS
Residence / immigration permit	RESIDENCE_PERMIT
Voter ID	VOTER_ID
Documents with no dedicated Sumsub type (e.g. tax cards, social security cards)	OTHER_DOCS

includedCountries / excludedCountries use ISO-3166 alpha-3 (e.g. BRA, USA, DEU).

Two-sided capture should be specified whenever a mandatory identifier (tax number, national number) appears on the back of the document.

SELFIE — liveness options (videoRequired)

Value	Description	Use when
passiveLiveness	Default. Advanced passive liveness, no movement required.	Standard KYC — no stricter regulatory mandate.
activeLiveness	Active motion challenge (head movement detection).	Regulation explicitly requires active/dynamic liveness.
enabled	Short video — applicant pronounces displayed digits.	Regulation requires video identity check.
photoRequired	Photo-only selfie, no liveness.	Use only when explicitly requested; generally insufficient for AML compliance.
staticLiveness	Single-frame analysis.	Use only when explicitly requested.

For most AML/KYC regulations without a specific liveness requirement, default to passiveLiveness.

APPLICANT_DATA — common field names

Standard personal-data fields:

Field name	Meaning
firstName	First / given name
lastName	Last / family name
dob	Date of birth
country	Country of residence (ISO-3166 alpha-3)
town	City / town
street	Street address
postCode	Postal / ZIP code
nationality	Nationality (ISO-3166 alpha-3)
placeOfBirth	Place of birth
tin	Tax identification number (TIN, CPF, SSN, BSN, etc.)

When a regulation mandates collection of a national tax or identity number, map it to tin and mark it required: true.

DEVICE_CHECK — what it detects

When DEVICE_INTELLIGENCE license is active, this step flags: emulators, rooted/jailbroken devices, VPN/proxy/Tor connections, remote-desktop software, and crypto-mixer tools. Always note in the plan that this step silently falls back to disabled if the tenant lacks the entitlement — add a GET-back verification step.

B. Questionnaires — sumsub-create-questionnaire

Custom forms for collecting applicant data not captured by document checks.

Common use cases: source of funds, source of wealth, employment, PEP self-declaration, trading experience, risk profile.

Question types: text, textArea, date, dateTime, bool, select, selectDropdown, multiSelect, phone, countrySelect, countryMultiSelect, fileAttachment, multiFileAttachments.

Conditional logic: sections and items can be shown/hidden based on previous answers.

Risk scoring: each answer option can carry a score (0–100); scores sum automatically and can be referenced in downstream transaction monitoring rules.

One questionnaire per level. Group distinct topics (source of funds, PEP self-declaration, risk profile…) as separate sections within a single questionnaire — not as separate questionnaires. Default to one QUESTIONNAIRE step per level. A separate level legitimately gets its own questionnaire (e.g. an EDD level with an extended questionnaire) — that is still one-per-level, not an exception. Only plan multiple questionnaires on the same level if the user explicitly asks for it.

C. Proof of Address Presets — sumsub-create-poa-preset

Reusable configuration for what documents are accepted as proof of address.

Document categories:

• governmentOrganization — government-issued (voter registration, tax bill, etc.)
• utilityProvider — utility bills
• bank — bank statements and letters
• mobileOperator — telecom bills
• other

Key settings:

• maxMonths per category — maximum document age
• Cross-validation: name/address comparison between identity document (POI) and address document (POA) — fuzzy or strict mode
• PoI-as-PoA: accept the identity document itself as proof of address
• Neobank blocklist: exclude documents from specific institutions (Revolut, N26, Wise, etc.)
• Country-specific overrides: different rules per country

D. E-KYC (Non-Document Electronic Verification)

⚠️ Requires separate activation per country through a Sumsub Customer Success Manager (CSM). License: E_KYC_TARGET.

Configured via sumsub-create-level once activated.

How it works: the applicant submits unique identifiers (TIN, document number, bank login) which are validated against external databases — no document photo required.

Two configuration modes:

1. Standalone E_KYC docSet — electronic verification only; applicant cannot upload documents instead
2. IDENTITY docSet with the database source's checkSourceSettings nested inside it — applicant chooses: upload document photo OR complete E-KYC in the same step

Configuration rules:

• Country and source coverage depends entirely on client's license activations — there is no universal list. Which sources are actually available and enabled for a given country is resolved at build time by sumsub-check-databases (called by sumsub-create-level), which also reports each source's placement (top-level database validation vs. standalone/nested non-doc step) — don't assume coverage or placement in the plan.
• Recommended to pair with a SELFIE step for biometric verification against database records

Activation steps: (1) contact CSM to request per-country activation, (2) run sumsub-create-level — it uses sumsub-check-databases to confirm the country's sources and place them (top-level database validation, standalone E_KYC, or nested inside IDENTITY).

E. Transaction Monitoring — sumsub-create-kyt-rules

⚠️ Requires KYT license (and TRAVEL_RULE for crypto, TM_SCHEDULED_EVENTS for periodic re-KYC, KYT_ANTI_FRAUD for platform events).

Describes what to configure at plan time in plain language. sumsub-create-kyt-rules translates each rule into a conditionEl SumScript expression and POSTs it to the API. New rules always start in test mode (dryRun: true) — activating them requires the dashboard.

Rules that match against a named set (clientLists.<name> — high-risk countries, blocked emails, peer allowlists) need that list built and populated first with sumsub-manage-client-lists. Check its Sumsub-maintained lists (fatf_black_flag_countries, eu_high_risk_third_countries, …) before planning a hand-built copy.

Transaction types:

• finance — financial transactions (fiat and crypto)
• travelRule — crypto transactions subject to Travel Rule (FATF / VASP)
• kyc — KYC-related events
• userPlatformEvent — login, signup, password reset, 2FA changes
• scheduledEvent — periodic triggers (requires TM_SCHEDULED_EVENTS license)

Rule anatomy:

• Condition — trigger (e.g., "incoming crypto transaction > $10,000")
• Action: score (add risk points), onHold (freeze transaction), awaitUser (request confirmation), reject (block)
• Risk score (0–100) — cumulative; multiple rules sum their scores
• Applicant change — move applicant to another level, trigger final rejection, or route to manual review
• Case creation — auto-create a compliance investigation case on rule match

Automated pre-scoring enrichments (active for licensed tenants):

• AML watchlists (PEP, sanctions, adverse media)
• Crypto screening: Chainalysis, Elliptic, TRM Labs, Merkle Science, Crystal
• Travel Rule processing
• Device intelligence and fingerprinting
• BIN lookup and payment method analytics

Periodic Re-KYC (Scheduled Rules):

• Trigger: applicants on level X for N days → reassign to a new level (triggers re-verification)
• Requires TM_SCHEDULED_EVENTS license

Required licenses for TM features: KYT, TRAVEL_RULE, TM_SCHEDULED_EVENTS, KYT_ANTI_FRAUD, DEVICE_INTELLIGENCE.

F. Workflows — sumsub-create-workflow

Graph-based routing logic: determines which level an applicant goes through next based on conditions.

Node types: applicantLevel (run a level), exclusiveChoice (condition branch), manualReview, finalRejection, actions (tags, notes, source-key changes).

Edge conditions: by applicant country, number of attempts, review decision (approved / rejected / resubmission), custom expressions.

Use when regulation requires risk-based routing (standard KYC for low-risk, EDD for high-risk), re-verification flows, or multi-stage onboarding.

G. AML Resolution Rules — sumsub-create-aml-resolution-rules

The AML Resolution Rule Chain: an ordered list of rules that auto-review AML screening hits. Each rule selects hits by condition (vendor match types, name/DoB compatibility, risk labels, previous reviews) and sets the hit's review — match status (false_positive / potential_match / true_positive), risk level, whitelisted flag, note — and/or tags the applicant.

Use when the regulation permits or requires systematic hit disposition: auto-clearing false positives, carrying over prior review decisions, PEP out-of-office handling, or flagging nuanced cases for routing.

Relationship to other entities: the screening runs on an applicant level when the tenant has WATCHLISTS entitlement and the level doesn't set disableWatchlists: true; the rule chain governs what happens to the AML matches it produces. Rule tags are common applicant tags and surface in workflow conditions as checks.personWatchlist.tags / checks.companyWatchlist.tags — e.g. a rule tags youngPep, a workflow routes those applicants to manual review.

Requires an AI-purpose App Token and tenant enablement (the skill detects and reports if the API is unavailable).

H. Transaction Submission — sumsub-create-transaction

Sends transaction data to Sumsub's KYT monitoring system. Distinct from TM Rules:

• This skill handles data submission (what transaction data to send)
• TM Rules define what to do with that data (configured in the Dashboard)

Covers: finance transactions, Travel Rule (crypto counterparty data), platform events (login/signup).

---

Analysis Framework

| Regulation requirement | Sumsub

...