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

sumsub-api-auth

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/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

sbx:

.

SUMSUB_APP_TOKEN

sbx:...

SUMSUB_SECRET_KEY

SUMSUB_BASE

https://api.sumsub.com

1. Fetch tenant entitlements. Run

   sumsub-check-permissions

   and store the

   allowed

   array. Verify

   KYT

   is present; abort with an explanation if missing.
2. 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.
3. 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

clientLists.<name>

conditionEl

bash     bash ${CLAUDE_SKILL_DIR}/scripts/get_kyt_client_list.sh <listName>     

bash       bash ${CLAUDE_SKILL_DIR}/scripts/create_kyt_client_list.sh <listName>       

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

conditionEl

1. 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.
2. Show each payload to the user and ask for explicit confirmation before any POST.
3. 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.
   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.
4. 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.
5. Build the dashboard link for each rule:

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

   name

   and

   clientId

   come from the POST response body. Render as a clickable markdown link.
6. 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".

score

conditionEl

{
  "title": "Hold high outgoing finance",
  "types": ["finance"],
  "conditionEl": "data.info.direction == 'out' AND data.info.amountInDefaultCurrency > 50000",
  "score": 100,
  "action": "onHold"
}

addScoreIf

conditionEl

score: 0

action: "score"

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

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

references/kyt-rule-schema.md

noEventTrigger

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

{
  "title": "Annual KYC refresh",
  "types": ["scheduledEvent"],
  "noEventTrigger": {
    "type": "byLevelName",
    "levelParams": {
      "levelName": "basic-kyc-level",
      "days": 365
    }
  },
  "applicantChange": {
    "type": "applicantLevel",
    "applicantLevel": {
      "levelName": "re-verification-level"
    }
  }
}

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

• 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}&xSNSEnv=sbx

• Report the new

  revision

  number alongside the title and updated fields.

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

companyBeneficiarySettings

• 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-create-transaction

  — submit test transactions to verify rules

• sumsub-check-permissions

  — check tenant entitlements

• sumsub-api-auth

  — authentication reference