Sumsub — KYT Rules, Applicant Scoring & Risk Levels

Configures the full KYT transaction monitoring stack:

• Rules — translates user intent into KytTxnRule 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 (dryRun: true) — they appear in dryScore 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

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 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/home?sbx=true (Connect Sumsub to your AI agent -> Build & configure -> Generate token). 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:.

If the user has already supplied credentials in conversation, reuse them; otherwise ask once before running. Never echo the secret back.

Tenant Entitlements

Entitlements are gated per transaction type, not globally. Each types value needs any one of the keys listed for it — not all of them. There is no baseline entitlement that every rule requires: KYT is the entitlement for the finance type, nothing more.

A tenant that has only TRAVEL_RULE can create travelRule rules. A tenant that has only DEVICE_INTELLIGENCE can create kyc rules. Neither needs KYT. Do not require KYT for a type whose row does not list it.

Before creating or modifying a rule, run bash scripts/check_permissions.sh from the sumsub-check-permissions skill directory. The response body is {"allowedChecks": {"<KEY>": "<description>", ...}} — the keys of allowedChecks are the enabled entitlements. There is no allowed array.

Stop only when the requested type is not enabled — i.e. none of the keys on that type's row appear in allowedChecks. Do not build or POST that rule. Name the type as the user sees it (see Transaction Types — kyc is "Verification session events", never "kyc"), list the keys that would enable it joined by "or", and tell the user to contact their CSM or Sumsub support. Do not offer a different transaction type as a workaround — if the user wants a travelRule rule, a finance rule is not a substitute.

If the entitlement request itself fails (non-200, timeout), warn the user that entitlements could not be verified and proceed anyway. The backend is the authority and enforces the same gate on POST — see the No allowed transaction types found row in step 6.

Note on scheduled rules. The scheduled trigger mode is licensed by TM_SCHEDULED_EVENTS specifically, while the scheduledEvent type is also enabled by KYT. A tenant with only KYT may therefore pass this gate and still be refused by the backend on noEventTrigger. Build the rule as usual and surface the backend error verbatim if that happens.

Procedure

0. Fetch tenant entitlements — only when creating or modifying a rule. Run sumsub-check-permissions and keep the keys of allowedChecks. Once you know the rule's types, check that row in Tenant Entitlements and abort if none of its keys are present.

   Skip this step entirely for work that is not a rule: tags, applicant assessment and risk levels need no entitlement. The /tm/clientLists endpoints (step 2a) need WATCHLISTS or WATCHLISTS_FOR_TM — without either, create the list with sumsub-manage-client-lists, which needs none — except a Sumsub-maintained list, which then can't be installed at all (see Required permissions). Do not look for an entitlements endpoint other than the one sumsub-check-permissions calls — there is no other one.

1. Determine mode — create or modify.

   • Modify mode: the user provides a rule name (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 name or title, and store the full current document. Show the user the existing conditionEl, score, action, and types, 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.

2. Translate user intent to compact specs. For each rule the user wants to create, collect:

   • title (≤128 chars, required)
   • types — one or more transaction types (see table below)
   • A plain-English description of the condition (used to generate conditionEl in step 3)
   • score (integer, default 0), action (score | onHold | awaitUser | reject)
   • Optional: desc, tags, bundleName, priority, stopOnMatch, sourceKeys

2a. Ensure client lists exist — if any rule will reference clientLists.<name> in its conditionEl, 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. For any other name it creates an empty custom list of key entries, and a list's type and entry type can never be changed afterwards. So when the rule needs a list of emails, phones, applicant ids, device ids or IP ranges, or a blocklist / whitelist, or needs values in it, don't create it here: hand off to sumsub-manage-client-lists, which creates typed lists and populates them. For a Sumsub-maintained name (fatf_black_flag_countries, eu_high_risk_third_countries, … — see that skill's table) the POST installs Sumsub's own read-only list, which is correct: use it rather than building a custom country list. Do not proceed to validation or rule creation until every referenced client list is confirmed.

3. Generate conditionEl. 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 data.info.amount (source-currency amount) — unless the user explicitly asks for source-currency filtering.
   • Scheduled rules (types: ["scheduledEvent"]) do NOT use conditionEl for their trigger — use noEventTrigger instead (see references/kyt-rule-schema.md).
   • For multi-branch scoring (different score per sub-condition), use addScoreIf inside conditionEl and set the payload-level score: 0, action: "score" (see Scoring section).

3a. Validation is built into POST — the server validates conditionEl 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.

4. Build payload. Assemble the JSON for each rule following these constraints:

   Create mode:

   • Required fields only: title, types (min 1 value).
   • For eval rules: include conditionEl, score, and action when relevant.
   • Never send id or name — the server assigns both.

   Modify mode (new revision):

   • Include "name": "<existing-slug>" — the immutable slug from the existing rule.
   • Include "id": null — an explicit null. This signals the server to create a new revision rather than a new rule. Do not use "id": "" (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.
   • title and types remain required.

   Both modes — always apply:

   • Never send server-assigned or audit fields: clientId, actual, revision, timestamps (createdAt, modifiedAt, archivedAt), author fields.
   • Never send scope or bgCheckTargets — license-control fields managed by the server.
   • Create mode: never send dryRun or disabled; the server initialises them to true and false.
   • Modify mode: carry over dryRun and disabled 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: sourceKeys: [], caseAction: {}, applicantChange: {}, applicantActions: {"actions": {}}, varDefinitions: {"definitions": []}, varValues: {"values": {}}.
   • Do not mix scheduledEvent with other transaction types.

5. Show each payload to the user and ask for explicit confirmation before any POST.

6. 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 KytTxnRuleView. 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.

   The backend enforces the entitlement gate too. Two error messages mean the payload is fine and retrying it unchanged will never work — stop retrying that rule and report:

   • No allowed transaction types found → the tenant is not licensed for the types you sent. Tell the user which types their allowedChecks does enable, and advise contacting their CSM. Do not silently switch to a different type.
   • Unable to enable a rule without a specified condition → the rule needs a conditionEl (or, for scheduledEvent, a noEventTrigger).

   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.

7. GET each created rule back via bash ${CLAUDE_SKILL_DIR}/scripts/get_kyt_rule.sh {id}. Compare conditionEl and key fields to what was sent. Report any discrepancy.

8. Build the dashboard link for each rule:

   https://cockpit.sumsub.com/checkus/kyt/rulesManager/rulesList/{name}?clientId={clientId}&sbx=true
   

   Copy

   name and clientId come from the POST response body. Render as a clickable markdown link.

9. Report — for each rule, lead with its human-readable title:

   • Title and auto-generated name (the short immutable slug)
   • Status: testMode — must be activated in the dashboard to go live
   • types, action, score
   • Dashboard link as a clickable markdown link
   • Rule id 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 dryRun: true. It evaluates against transactions and its result appears in dryScore, 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:

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

Types may be combined in one rule except scheduledEvent which must be the only type.

The first column is the API value; the second is what the user reads. Put the API value in types and nowhere else — in reports, refusals, and clarifying questions use the second column, the name the dashboard shows. kyc is the one that actually misleads: the dashboard has no "kyc" label anywhere, so a message naming it that way sends the user looking for something that does not exist. The other four are only prettified, but the dashboard's wording is still the one to use.

Which types this tenant may use is gated per type — see Tenant Entitlements, the single source for that mapping.

Rule Actions

Across all matched rules, the strongest action wins and scores accumulate.

Scoring & conditionEl

Simple rule (single threshold, one score): Put the score in score and keep conditionEl as a pure boolean.

{
  "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 addScoreIf inside conditionEl. Set payload score: 0 and action: "score" — otherwise the payload score is double-counted.

• EOR (eager OR): every branch is evaluated, all matching branches accumulate score. Use for independent flags.
• OR (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 conditionEl 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

# KYC: questionnaire answer — nested questionnaire.section.item, dot notation only
questionnaires.myQuestionnaireId.mySectionId.myItemId == 'salary'

# KYC: same, when a segment contains a dash — backtick-quote that segment
questionnaires.`my-quest-id`.mySectionId.myItemId == 'salary'

Conditions on questionnaire answers have two traps that produce a rule which saves cleanly and never matches: the bracket form does not compile, and the compared value is the option's stored value, not the label shown to the applicant. Read references/kyt-rule-schema.md → questionnaires before writing one, including how to look up the three ids.

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 conditionEl as clientLists.<listName>. A list must exist before a rule that references it can be validated or created.

Checking and creating a list

# 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

If the GET returns 403, seeClientLists is missing. If the POST returns 403, manageClientLists is missing. In both cases, tell the user the missing permission and stop.

Both endpoints also require the WATCHLISTS or WATCHLISTS_FOR_TM entitlement. When the tenant has neither, create the list with sumsub-manage-client-lists instead — its endpoints need no entitlement. Except a Sumsub-maintained name (fatf_black_flag_countries, …): only these endpoints can install one, and that skill refuses the reserved name. Tell the user the tenant needs WATCHLISTS or WATCHLISTS_FOR_TM for that list, and stop — don't hand off, and don't build a copy under another name.

Usage in conditionEl

Reference a list by its exact name after the clientLists. 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

The endpoints above only get-or-create an empty custom list of key entries. As step 2a says, a list that needs values (countries, wallets, peer ids, …) or a typed entry is not created here: sumsub-manage-client-lists creates and populates it, via the same clientLists entity (shared seeClientLists/manageClientLists permissions). Resume at step 3 once it reports the list populated.

Tags

Tags link rule matches to applicant-level risk assessment:

• Add tags: ["TagName"] 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 applicantAssessment post-scoring runner aggregates tag scores into the applicant risk profile.

Scheduled Rules (scheduledEvent)

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 noEventTrigger structure.

Key constraints:

• types must be exactly ["scheduledEvent"] — cannot be combined with other types.
• Must include applicantChange or applicantActions (at least one).
• conditionEl is optional (use for secondary filtering, not as the primary trigger).
• noEventTrigger.type is either byLevelName (approved applicants at a level, N days after review) or byCustomExpression (free-form applicant filter expression).

Minimal scheduled rule:

{
  "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 caseAction:

{
  "caseAction": {
    "createCase": true,
    "groupByType": "byApplicant",
    "blueprintId": "<case-blueprint-id>",
    "priority": "high",
    "deadlineHours": 24
  }
}

groupByType: byRule (one case per rule) or byApplicant (one case per applicant, transactions grouped). blueprintId 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 revision.

Identify the rule

The user must supply the rule's name (immutable slug) or enough context to identify it by title. List all rules and find the match:

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 ${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 conditionEl, score, action, and types to the user before proceeding.

Payload shape

Take the existing rule document, apply only the user's requested changes, then:

• Set "id": null — explicit null (signals new revision, not new rule). Never use "" — it fails Jackson ObjectId deserialization with HTTP 400.
• Keep "name": "<slug>" — the existing immutable slug.
• Strip server-managed fields: clientId, actual, revision, scope, bgCheckTargets, timestamps, author fields.
• Keep dryRun and disabled from the existing document — they preserve the rule's current activation and test-mode state across the revision.

{
  "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 conditionEl 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 id (the latest revision gets a new id), old name, revision number, and all rule fields.
• GET the rule back by the new id to verify.
• The dashboard link uses the old name:

  https://cockpit.sumsub.com/checkus/kyt/rulesManager/rulesList/{name}?clientId={clientId}&sbx=true
  

  Copy
• Report the new revision 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

1. Rules fire — when a TM rule matches a transaction, it applies its tags to the applicant.
2. Tags accumulate — each tag carries a scoreWeight. Multiple rule matches sum tag scores.
3. Assessment aggregates — the assessment config controls which tags count toward the total score (includeInTotalScore), their relative weights (scoreWeight), and optional hierarchy (items).
4. Risk level assigned — the total score is compared against riskLevelThresholds 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

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 scripts/get_kyt_tags.sh

Step 2 — Configure assessment

Map tags to weighted scores. id is a client-assigned stable identifier for the entry.

{
  "scores": [
    {
      "id": "high-value-score",
      "tag": "HighValue",
      "includeInTotalScore": true,
      "scoreWeight": 1.0
    }
  ],
  "companyBeneficiarySettings": [
    { "beneficiaryType": "ubo",      "weight": 1.0 },
    { "beneficiaryType": "director", "weight": 0.5 }
  ]
}

Valid beneficiaryType values: shareholder, representative, director, ubo, companyOfficer, secretary, founder, investor, legalAdvisor, authorizedSignatory, trustee, trustBeneficiary, trustSettlor, trustProtector, payer.

# 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

# 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 tags to a rule's payload to connect rule matches to the assessment:

{
  "title": "Flag high-value transfers",
  "types": ["finance"],
  "conditionEl": "data.info.amountInDefaultCurrency > 10000",
  "score": 50,
  "action": "score",
  "tags": ["HighValue"]
}

When this rule matches, the HighValue 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
• examples/minimal.json — 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 (installed | available | archived)
• scripts/get_kyt_tags.sh — list all KYT tags with assessment config and linked rules
• scripts/post_kyt_tag.sh — create or update a KYT tag (requires manageKytSettings)
• scripts/get_kyt_applicant_assessment.sh — get applicant assessment scoring configuration
• scripts/patch_kyt_applicant_assessment.sh — replace applicant assessment scoring configuration (requires manageKytSettings)
• 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 manageKytSettings)
• 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-manage-client-lists — create typed client lists, populate their values, check membership
• sumsub-create-transaction — submit test transactions to verify rules
• sumsub-check-permissions — check tenant entitlements
• sumsub-api-auth — authentication reference