Sumsub — KYT Rules, Applicant Scoring & Risk Levels
Configures the full KYT transaction monitoring stack:
- Rules — translates user intent into payloads and POSTs them one at a time. Supports creating new rules and modifying existing ones (by posting a new revision). New rules always start in testMode () — they appear in but do not affect the live outcome until activated in the dashboard.
- Tags & applicant scoring — creates and configures tags (named risk markers) and the assessment that maps tag weights into a composite applicant risk score.
- Risk levels — configures the score thresholds that translate a numeric risk score into a human-readable label (e.g. Low / Med / High).
Rules, tags, and risk levels form a single pipeline: a rule fires → applies tags → tags accumulate a weighted score → score maps to a risk level.
Endpoints
| Method | Path | Description | Response |
|---|
| /resources/api/agent/tm/rules/-/installed
| List existing rules. Supports and . Requires . | { list: { items: [...] } }
|
| /resources/api/agent/tm/rules
| Create a new rule or a new revision. For creation omit and . For a revision include the existing slug and . Requires . | 200 rule object · 400 error message |
| /resources/api/agent/tm/rules/-/bundle/{bundleName}/{category}
| List rules in a bundle by name and installation status. : , , . Requires . | { list: { items: [...] } }
|
| /resources/api/agent/tm/rules/{id}
| Read one rule by id. Requires . | rule object |
| /resources/api/agent/tm/settings/tags
| List all KYT tags with their assessment configuration and linked rules. | |
| /resources/api/agent/tm/settings/tag
| Create or update a KYT tag. Body: {"tag": {"name": "...", "styleClass": "...", "color": "#RRGGBBAA", "scorable": true, "includeInReporting": true, "scoreWeight": 1.0}}
. must be 8-digit hex. Requires . | 200 empty body |
| /resources/api/agent/tm/settings/applicantAssessment
| Get current applicant assessment scoring configuration (tag weights, hierarchy, company beneficiary weights). | assessment settings object |
| /resources/api/agent/tm/settings/applicantAssessment
| Replace applicant assessment scoring configuration. Requires . | 200 updated assessment settings |
| /resources/api/agent/tm/settings/riskLevel
| Get current applicant risk level thresholds. | risk level settings object |
| /resources/api/agent/tm/settings/riskLevel
| Replace risk level thresholds. Body: min 2 items, each with (≤256), (≥0), — one of: , , , , , , , , , , , , , , . Requires . | 200 updated risk level settings |
| /resources/api/agent/tm/clientLists/{listName}
| Fetch a client list by name. 404 if not found. Requires . | client list object |
| /resources/api/agent/tm/clientLists/{listName}
| Create a client list (idempotent). Requires . | client list object |
See
references/kyt-rule-schema.md
for the full rule SumScript expression field reference and type system.
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 . |
If the user has already supplied credentials in conversation, reuse them;
otherwise ask once before running. Never echo the secret back.
Tenant Entitlements
KYT rules require the
entitlement at minimum. Additional per-type requirements apply:
| Rule value | Required entitlement |
|---|
| |
| |
| (or TM_INDIVIDUAL_APPLICANT_SCORING
, TM_COMPANY_APPLICANT_SCORING
, , ) |
| + |
| + |
Before creating any rules, run
bash scripts/check_permissions.sh
from the
skill directory
and verify
(and any type-specific permission) is present in the
array.
If is not in — stop immediately. Do not build or POST any rules.
Tell the user the entitlement is missing and that they need to contact their CSM or Sumsub support to get it enabled.
Procedure
-
Fetch tenant entitlements. Run
and store the
array.
Verify
is present; abort with an explanation if missing.
-
Determine mode — create or modify.
- Modify mode: the user provides a rule (immutable slug, e.g.
fin-ben-pep-ter-list-abo-thr-WoGD
) or enough context to identify one. Run bash ${CLAUDE_SKILL_DIR}/scripts/get_kyt_rules.sh
, find the rule by or , and store the full current document. Show the user the existing , , , and , then collect only the fields they want to change. Skip to step 2a.
- Create mode: the user describes a new rule. Run
bash ${CLAUDE_SKILL_DIR}/scripts/get_kyt_rules.sh
and check for a title collision — the server creates a duplicate on every POST with no deduplication. If a rule with a matching title already exists, offer to skip creation and modify the existing one instead.
-
Translate user intent to compact specs. For each rule the user wants to create, collect:
- (≤128 chars, required)
- — one or more transaction types (see table below)
- A plain-English description of the condition (used to generate in step 3)
- (integer, default 0), ( | | | )
- Optional: , , , , ,
2a.
Ensure client lists exist — if any rule will reference
in its
,
verify each list exists before generating or validating expressions:
bash bash ${CLAUDE_SKILL_DIR}/scripts/get_kyt_client_list.sh <listName>
- HTTP 200 → list exists; proceed.
- HTTP 404 → list does not exist; create it:
bash bash ${CLAUDE_SKILL_DIR}/scripts/create_kyt_client_list.sh <listName>
The POST is idempotent — it succeeds even if the list was created in the meantime.
Do not proceed to validation or rule creation until every referenced client list is confirmed.
- Generate . For each rule that needs a condition:
- Construct the SumScript boolean expression using the type definitions in
references/kyt-rule-schema.md
.
- Do not guess field paths. Only use fields confirmed in the schema — verify the path
from root to leaf before writing the expression.
- For default-currency amount checks use
data.info.amountInDefaultCurrency
(normalized amount),
not (source-currency amount) — unless the user explicitly asks for
source-currency filtering.
- Scheduled rules (
types: ["scheduledEvent"]
) do NOT use for their trigger —
use instead (see references/kyt-rule-schema.md).
- For multi-branch scoring (different score per sub-condition), use inside
and set the payload-level , (see Scoring section).
3a.
Validation is built into POST — the server validates
syntax during the create call (step 6). No separate pre-flight step is needed. If validation fails the server returns HTTP 400 with an error message describing the problem — fix the expression and re-POST.
-
Build payload. Assemble the JSON for each rule following these constraints:
Create mode:
- Required fields only: , (min 1 value).
- For rules: include , , and when relevant.
- Never send or — the server assigns both.
Modify mode (new revision):
- Include
"name": "<existing-slug>"
— the immutable slug from the existing rule.
- Include — an explicit null. This signals the server to create a new revision rather than a new rule. Do not use (empty string) — Jackson will reject it as an invalid ObjectId and return HTTP 400.
- Carry over all unchanged fields from the existing rule document. Only change the fields the user asked to modify.
- and remain required.
Both modes — always apply:
- Never send server-assigned or audit fields: , , ,
timestamps (, , ), author fields.
- Never send or — license-control fields managed by the server.
- Create mode: never send or ; the server initialises them to and .
- Modify mode: carry over and from the existing rule document — the server uses the sent values to preserve the rule's current activation and test-mode state across the revision.
- Omit empty optional containers: , ,
,
applicantActions: {"actions": {}}
,
varDefinitions: {"definitions": []}
, varValues: {"values": {}}
.
- Do not mix with other transaction types.
-
Show each payload to the user and ask for explicit confirmation before any POST.
-
POST each rule via
bash ${CLAUDE_SKILL_DIR}/scripts/post_kyt_rule.sh < payload.json
.
Rules are created one at a time. Check the exit code:
- Exit 0 → HTTP 200; the response body is the created . Proceed to step 7.
- Exit 1 → HTTP 4xx/5xx; the response body contains the error message. Surface it verbatim,
fix the expression, and re-POST.
Retry cap: allow at most 10 POST attempts per rule. If the 10th attempt still fails,
mark that rule as failed, record the last error message, and move on to the next rule —
do not abort the entire batch. Report all failed rules in step 9.
-
GET each created rule back via
bash ${CLAUDE_SKILL_DIR}/scripts/get_kyt_rule.sh {id}
.
Compare
and key fields to what was sent. Report any discrepancy.
-
Build the dashboard link for each rule:
https://cockpit.sumsub.com/checkus/kyt/rulesManager/rulesList/{name}?clientId={clientId}&xSNSEnv=sbx
and
come from the POST response body. Render as a clickable markdown link.
-
Report — for each rule, lead with its human-readable title:
- Title and auto-generated (the short immutable slug)
- Status: testMode — must be activated in the dashboard to go live
- , ,
- Dashboard link as a clickable markdown link
- Rule on its own final line
For rules that exhausted all 10 attempts, report them in a Failed rules section with the
title and the last HTTP 400 error message.
Surface 4xx errors verbatim.
⚠️ testMode default. Every new rule starts with
. It evaluates against
transactions and its result appears in
, but does not affect the real score or
action. To make a rule live, open it in the dashboard and set it to "Active".
Compact Spec Format
Express each rule as a JSON object before generating the full payload:
jsonc
{
"title": "Hold large outgoing transfers", // required, ≤128 chars
"desc": "Holds outgoing transactions over 50 000 in default currency",
"types": ["finance"], // required
"condition": "outgoing AND amount > 50 000 default currency", // natural language → conditionEl
"score": 100, // 0 if using addScoreIf
"action": "onHold", // score | onHold | awaitUser | reject
"tags": ["HighAmount"], // optional; auto-created if new
"bundleName": "AML Compliance", // optional group
"priority": 10, // optional; higher = evaluated first
"stopOnMatch": false, // optional
"sourceKeys": ["payment-gateway-1"] // optional top-level filter
}
Transaction Types
| Type | When to use | required? | Notes |
|---|
| Payment transfers, deposits, withdrawals | Yes | Most common type |
| Travel-rule transactions | Yes | Requires entitlement |
| KYC/verification session events | Yes | |
| Login, password reset, 2FA events | Yes | Requires |
| Periodic applicant re-checks | No (use ) | Must be alone in |
Types may be combined in one rule except
which must be the only type.
Rule Actions
| Action | Priority | Effect |
|---|
| 0 | Adds score only (default) |
| 5 | Holds the transaction for review |
| 7 | Awaits user action before proceeding |
| 10 | Rejects the transaction outright |
Across all matched rules, the strongest action wins and scores accumulate.
Scoring &
Simple rule (single threshold, one score): Put the score in
and keep
as a pure boolean.
json
{
"title": "Hold high outgoing finance",
"types": ["finance"],
"conditionEl": "data.info.direction == 'out' AND data.info.amountInDefaultCurrency > 50000",
"score": 100,
"action": "onHold"
}
Multi-branch scoring (different scores per sub-condition): Use
inside
.
Set payload
and
— otherwise the payload score is double-counted.
- (eager OR): every branch is evaluated, all matching branches accumulate score. Use for independent flags.
- (short-circuit): stops at the first matching branch. Use for mutually exclusive tiers (strictest first).
addScoreIf(data.info.amountInDefaultCurrency > 100000, 50) EOR
addScoreIf(applicant.country IN clientLists.sanctioned_countries, 100) EOR
addScoreIf("pep" IN applicant.riskLabels.aml, 75)
Common Patterns
# Finance: outgoing transfer over threshold
data.info.direction == 'out' AND data.info.amountInDefaultCurrency > 50000
# Finance: applicant in a client list
applicant.country IN clientLists.high_risk_countries
# Finance: incoming from specific payment type
data.info.direction == 'in' AND data.info.type == 'transfer'
# Finance: crypto transaction
data.info.currencyType == 'crypto'
# KYC: applicant review rejected
applicant.review.decision == 'rejected'
# Travel Rule: counterparty VASP not found
txn.travelRuleInfo.status == 'counterpartyVaspNotFound'
# Aggregation: applicant sent > 3 transactions in last 24 hours
txns.finance.byApplicant.out.lastHours(24).count() > 3
# Aggregation: total outgoing amount in last 30 days
txns.finance.byApplicant.out.lastDays(30).sum(it.data.info.amountInDefaultCurrency) > 100000
For the full type system and all available fields, see
references/kyt-rule-schema.md
.
Client Lists
Client lists are named sets of values (countries, currencies, peer IDs, etc.) referenced in
as
. A list must exist before a rule that references it can be validated or created.
Checking and creating a list
bash
# Check if a list exists
bash ${CLAUDE_SKILL_DIR}/scripts/get_kyt_client_list.sh high_risk_countries
# Create a list (idempotent)
bash ${CLAUDE_SKILL_DIR}/scripts/create_kyt_client_list.sh high_risk_countries
The POST creates an empty list if it doesn't exist and returns the list document either way.
Required permissions
| Operation | Permission |
|---|
| GET (read) | |
| POST (create) | |
If the GET returns 403,
is missing. If the POST returns 403,
is missing. In both cases, tell the user the missing permission and stop.
Usage in
Reference a list by its exact name after the
prefix:
# Country in a named list
applicant.country IN clientLists.high_risk_countries
# Peer wallet not in an allowlist
NOT (txn.counterparty.wallet IN clientLists.approved_wallets)
# Combined
applicant.country IN clientLists.sanctioned_countries AND data.info.amountInDefaultCurrency > 1000
List contents are managed separately in the Sumsub dashboard (KYT → Client Lists) — the API endpoints only create an empty list; adding values is a dashboard-only operation.
Tags
Tags link rule matches to applicant-level risk assessment:
- Add to a rule — the tag name auto-creates in KYT settings if new.
- When the rule matches, each tag accumulates the rule's score for the applicant.
- The post-scoring runner aggregates tag scores into the applicant risk profile.
Scheduled Rules ()
Scheduled rules fire without an incoming transaction. They find applicants based on trigger criteria
and generate synthetic events. See
references/kyt-rule-schema.md
for the full
structure.
Key constraints:
- must be exactly — cannot be combined with other types.
- Must include or (at least one).
- is optional (use for secondary filtering, not as the primary trigger).
- is either (approved applicants at a level, N days after review)
or (free-form applicant filter expression).
Minimal scheduled rule:
json
{
"title": "Annual KYC refresh",
"types": ["scheduledEvent"],
"noEventTrigger": {
"type": "byLevelName",
"levelParams": {
"levelName": "basic-kyc-level",
"days": 365
}
},
"applicantChange": {
"type": "applicantLevel",
"applicantLevel": {
"levelName": "re-verification-level"
}
}
}
Case Creation on Match
To automatically create a compliance case when a rule matches, add
:
json
{
"caseAction": {
"createCase": true,
"groupByType": "byApplicant",
"blueprintId": "<case-blueprint-id>",
"priority": "high",
"deadlineHours": 24
}
}
:
(one case per rule) or
(one case per applicant, transactions grouped).
is optional — omit to use the default case template.
Modifying an Existing Rule
To update a rule, POST a new revision to the same endpoint used for creation. The server replaces the current revision atomically and increments
.
Identify the rule
The user must supply the rule's
(immutable slug) or enough context to identify it by title. List all rules and find the match:
bash
bash ${CLAUDE_SKILL_DIR}/scripts/get_kyt_rules.sh | python3 -c "
import json, sys
items = json.load(sys.stdin).get('list', {}).get('items', [])
for r in items:
if r.get('name') == 'fin-ben-pep-ter-list-abo-thr-WoGD':
print(json.dumps(r, indent=2))
"
Or search by title substring:
bash
bash ${CLAUDE_SKILL_DIR}/scripts/get_kyt_rules.sh | python3 -c "
import json, sys
items = json.load(sys.stdin).get('list', {}).get('items', [])
for r in items:
if 'PEP' in r.get('title', '').upper():
print(json.dumps(r, indent=2))
"
Show the matching rule's current
,
,
, and
to the user before proceeding.
Payload shape
Take the existing rule document, apply only the user's requested changes, then:
- Set — explicit null (signals new revision, not new rule). Never use — it fails Jackson ObjectId deserialization with HTTP 400.
- Keep — the existing immutable slug.
- Strip server-managed fields: , , , , , timestamps, author fields.
- Keep and from the existing document — they preserve the rule's current activation and test-mode state across the revision.
json
{
"id": null,
"name": "fin-ben-pep-ter-list-abo-thr-WoGD",
"title": "Finance — Beneficiary in PEP and terror list above threshold",
"types": ["finance"],
"conditionEl": "beneficiary.fullName IN clientLists.pep_and_terror AND data.info.amountInDefaultCurrency > 5000",
"score": 100,
"action": "onHold",
"dryRun": true,
"disabled": false
}
Validate before posting
If
changed, the POST validates it automatically. If the server returns HTTP 400, fix the expression and re-POST (same 10-attempt cap as create mode applies).
After posting
- The response contains the new (the latest revision gets a new id), old , number, and all rule fields.
- GET the rule back by the new to verify.
- The dashboard link uses the old :
https://cockpit.sumsub.com/checkus/kyt/rulesManager/rulesList/{name}?clientId={clientId}&xSNSEnv=sbx
- Report the new number alongside the title and updated fields.
Applicant Risk Scoring
Applicant risk scoring calculates a composite risk score for each applicant based on the transaction monitoring rules that matched them. The score is built from three layers configured independently:
Rules (produce tags on match)
└─ Tags (each carries a score weight)
└─ Assessment (maps tags → weighted score)
└─ Risk Levels (score thresholds → Low / Med / High label)
How it works
- Rules fire — when a TM rule matches a transaction, it applies its to the applicant.
- Tags accumulate — each tag carries a . Multiple rule matches sum tag scores.
- Assessment aggregates — the assessment config controls which tags count toward the total score (), their relative weights (), and optional hierarchy ().
- Risk level assigned — the total score is compared against to produce a human-readable risk label (e.g. Low / Med / High).
For companies,
companyBeneficiarySettings
in the assessment applies role-based weights (UBO, director, shareholder…) so the applicant's score accounts for the risk of their associated parties.
Configuring applicant scoring — step by step
Step 1 — Create/update tags
bash
echo '{"tag": {"name": "HighValue", "styleClass": "red", "color": "#FF000080", "scorable": true, "scoreWeight": 1.0}}' \
| bash scripts/post_kyt_tag.sh
Read back all tags to confirm:
bash
bash scripts/get_kyt_tags.sh
Step 2 — Configure assessment
Map tags to weighted scores.
is a client-assigned stable identifier for the entry.
json
{
"scores": [
{
"id": "high-value-score",
"tag": "HighValue",
"includeInTotalScore": true,
"scoreWeight": 1.0
}
],
"companyBeneficiarySettings": [
{ "beneficiaryType": "ubo", "weight": 1.0 },
{ "beneficiaryType": "director", "weight": 0.5 }
]
}
Valid
values:
,
,
,
,
,
,
,
,
,
,
,
,
,
,
.
bash
# Read current
bash scripts/get_kyt_applicant_assessment.sh
# Apply new config
echo '<payload>' | bash scripts/patch_kyt_applicant_assessment.sh
Step 3 — Configure risk level thresholds
bash
# Read current
bash scripts/get_kyt_risk_level_settings.sh
# Apply new thresholds (min 2 required)
echo '{"riskLevelThresholds": [
{"label": "Low", "rangeFrom": 0, "styleClass": "green"},
{"label": "High", "rangeFrom": 75, "styleClass": "red"}
]}' | bash scripts/patch_kyt_risk_level_settings.sh
Tags in rules
Add
to a rule's payload to connect rule matches to the assessment:
json
{
"title": "Flag high-value transfers",
"types": ["finance"],
"conditionEl": "data.info.amountInDefaultCurrency > 10000",
"score": 50,
"action": "score",
"tags": ["HighValue"]
}
When this rule matches, the
tag is applied to the applicant and its weight contributes to their risk score.
See Also
references/kyt-rule-schema.md
— full field reference and SumScript type system
- — bare-minimum working payload
examples/eval-finance-hold.json
— complete finance hold rule
scripts/get_kyt_bundle.sh
— list rules in a bundle by name and category ( | | )
- — list all KYT tags with assessment config and linked rules
- — create or update a KYT tag (requires )
scripts/get_kyt_applicant_assessment.sh
— get applicant assessment scoring configuration
scripts/patch_kyt_applicant_assessment.sh
— replace applicant assessment scoring configuration (requires )
scripts/get_kyt_risk_level_settings.sh
— get current applicant risk level thresholds
scripts/patch_kyt_risk_level_settings.sh
— replace applicant risk level thresholds (min 2, requires )
scripts/get_kyt_client_list.sh
— check whether a client list exists by name
scripts/create_kyt_client_list.sh
— create a client list (idempotent)
sumsub-create-transaction
— submit test transactions to verify rules
- — check tenant entitlements
- — authentication reference