/resources/api/agent/amlResolutionRules

draft → published → archived

aml_rules_api.py

GET

/draft

draft

notices[]

GET

/published

published

GET

/archive

archive [marker]

GET

/library

library

POST

/draft/rules

upsert

id

id

notices[]

PUT

/draft/rules/order

reorder

{"ruleIds": [...]}

DELETE

/draft/rules/{id}

delete <id>

POST

/draft/publish

publish

error

Publishing via the API is for the integration phase. Once the integration is considered active, the API may refuse to publish (a

4xx

); the chain must then be reviewed and published by a human from the Sumsub web UI. Treat a publish refusal as expected at that stage, not an error to work around — report it and point the user to the web UI.

manageAmlCases

manageClientSettings

• 403 "This endpoint is not allowed for this type of token"

  → the token is a regular App Token, not an AI one. Ask the user to mint an AI token.

• 404 "API is not available"

  on every endpoint → the AML Resolution Rules API is not enabled for this tenant. Stop immediately — tell the user to contact their CSM or Sumsub support; do not retry other endpoints.

sumsub-api-auth

401 Invalid signature

⚠️ Sandbox tokens only. Do not accept or use a production App Token here — these rules auto-review real AML hits. If the user offers a prod token, 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 — that page mints the AI token these endpoints require, see above). Token + secret are shown once — copy both before closing the dialog.

aml_rules_api.py

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. Rules run top to bottom — order matters.
2. Each rule is evaluated against every hit that is not yet reviewed. A hit that gets a

   matchStatus

   (from moderation or an earlier rule) is skipped by later rules.
3. Effects are visible mid-run: tags and recomputed

   screening.answer

   /

   screening.tags

   /

   screening.matchStatuses

   from earlier rules are seen by later ones — this enables chaining (rule A tags

   match_tin

   , rule B reacts to

   screening.tags containsAny ["match_tin"]

   ).
4. Put specific, decisive rules (ID matches, previous-review carry-over) before broad clean-up rules — a broad

   false_positive

   rule placed first steals hits from preciser rules below it.

1. Tenant entitlement

   WATCHLISTS

   — all-or-nothing, tenant-wide. Verify it by invoking the

   sumsub-check-permissions

   skill.

   WATCHLISTS

   present → AML screening is available and on by default on every level.

   WATCHLISTS

   absent → AML screening is off for the entire tenant; no applicant-level setting can turn it on, and this rule chain will never see a hit.
2. Per-level opt-out

   disableWatchlists

   — only relevant once gate 1 passes. Screening runs on a level unless that level sets the top-level

   disableWatchlists: true

   (how a client carves out levels that shouldn't be screened). This is the

   sumsub-create-level

   skill's concern, not this one.

WATCHLISTS

disableWatchlists

false

true

WATCHLISTS

checks.personWatchlist.tags

checks.companyWatchlist.tags

1. AML rule — condition "the hit carries the

   pep

   risk label and the applicant is under 30", tags action

   ["youngPep"]

   .
2. Workflow edge — a

   condition

   testing that

   checks.personWatchlist.tags

   contains

   youngPep

   → a manual-review node.

sumsub-create-workflow

1. Confirm AML screening is enabled for the tenant (see Precondition). Invoke the

   sumsub-check-permissions

   skill and verify

   WATCHLISTS

   is among the tenant's allowed entitlements. If it's absent, AML screening is off tenant-wide, so this rule chain will never fire: tell the user plainly (the entitlement is enabled by their CSM / Sumsub support), and get explicit confirmation before proceeding — do not silently build a chain that does nothing. If present, proceed.
2. Read the draft:

   ${CLAUDE_SKILL_DIR}/scripts/aml_rules_api.py draft

   . This is also the availability check — on

   404 "API is not available"

   or

   403

   , stop and report (see Endpoints above). Review the existing rules: if a rule with the same intent already exists, offer to update it by

   id

   instead of appending a duplicate — upsert has no name deduplication. Note which rule ids exist before you make changes — you'll need that to honor the delete consent policy.
3. Check the library first:

   ${CLAUDE_SKILL_DIR}/scripts/aml_rules_api.py library

   . If a ready-made template matches the user's intent, start from its

   rule

   definition — strip the

   id

   , adjust, and continue. Check the template's

   vendors

   list against the AML vendor the tenant uses.
4. Write the rule spec (below). Author the

   condition

   as the real Condition AST, directly — there is no expression mini-language (see Authoring conditions). Scope the rule to an entity type with an

   input.entityType

   criterion (default individual — see Authoring conditions). Verify every

   exp

   path against references/aml-rules-context-fields.md, and any enum-backed field's allowed values against references/aml-rules-enumerations.md — unknown paths produce

   unknownField

   error notices that block publishing.
5. Assemble the rule payload with

   ${CLAUDE_SKILL_DIR}/scripts/build_aml_rule.py

   — compact spec on stdin → full rule JSON on stdout. The builder is a thin assembler: it passes the

   condition

   AST through, assembles the review/tags actions, validates operators / the

   matchStatus

   enum / the emptyAction guard, and errors here (before any network call) on a typo or a malformed AST.
6. Show the resolved payload to the user and get explicit confirmation before the first upsert. If the rule's

   tags

   action introduces a tag that doesn't exist yet, call that out explicitly: upserting will create it as a tenant-wide applicant tag (visible in dashboard filters, workflows, everywhere) — confirm the name is one worth keeping (clear, concise, reusable) or reuse an existing tag instead.
7. Upsert via

   ${CLAUDE_SKILL_DIR}/scripts/build_aml_rule.py < spec.json | ${CLAUDE_SKILL_DIR}/scripts/aml_rules_api.py upsert

   → response is the full draft with recomputed

   notices[]

   . Repeat steps 3–6 for each rule when creating several. Record the id the server assigns each rule you create — that's how you know it's yours (step 9).
8. Inspect

   notices

   .

   error

   notices (e.g.

   invalidTag

   ,

   unknownField

   ,

   unknownFunction

   ) block publishing — fix the rule and re-upsert with its

   id

   .

   warning

   /

   info

   are advisory; surface them. See the notice key table in references/aml-resolution-rules-schema.md.
9. Order the chain. New rules land at the end. If the evaluation order needs changing, pass the full permutation:

   echo '{"ruleIds": [...]}' | ${CLAUDE_SKILL_DIR}/scripts/aml_rules_api.py reorder

   .
10. Delete rules — only per the consent policy below.

    ${CLAUDE_SKILL_DIR}/scripts/aml_rules_api.py delete <ruleId>

    .
11. Publish only on explicit request (see the "Publishing affects LIVE production" note):

    ${CLAUDE_SKILL_DIR}/scripts/aml_rules_api.py publish

    . Publishing makes the chain live against real AML hits across live and sandbox — never publish without the user asking; until then the draft is dormant. The backend may refuse the publish once the chain is active (too many applicants already processed / integration complete) — a

    4xx

    . That's expected: report it and direct the user to publish from the Sumsub web UI (see the Endpoints note).
12. Report (lead with rule names, never bare ids):
    • The rule chain in evaluation order (names), the draft

      revision

      , and a notices summary.
    • Draft (editable) view: https://cockpit.sumsub.com/checkus/sdkIntegrations/globalSettings/amlScreening?revision=draft&tab=amlRules&sbx=true
    • Published (live) view, after publishing: https://cockpit.sumsub.com/checkus/sdkIntegrations/globalSettings/amlScreening?revision=published&tab=amlRules&sbx=true
    • Render both as clickable markdown links;

      sbx=true

      targets the Sandbox workspace.
    • End with a dedicated

      Rule id (for future updates / reorder): <id>

      line — the one place a raw id belongs in your output.
    • On failure: surface Sumsub's

      description

      /

      errorName

      verbatim.

delete

• A rule you created in this session — delete it freely when it was a mistake, the user asked you to replace it, or you're iterating on your own work. (Updating in place by

  id

  is usually better than delete-then-recreate, because it preserves the rule's position; reach for delete when the rule should genuinely go away.)
• Any rule you did not create — a pre-existing rule, one from an earlier session, or one a human authored — delete only with explicit user consent for that specific rule. Name the rule (by its

  name

  ) and confirm before deleting. Never delete someone else's rule as a side effect of "cleaning up" or "rebuilding" the chain.
• When unsure whether a rule is yours, treat it as not yours and ask.

notices[]

condition

condition: "screening.vendor = …"

conditionRaw

⚠️ Scope every rule to an entity type. Individual and company matches expose different fields and read differently, so a rule built for one can misfire on the other. Each rule MUST carry an

input.entityType

criterion — infer the target from the rule's intent (person name / DoB / PEP signals → individual; company name / KYB signals → company), and default to individual when unsure:

• Individual (the usual case):

  { "op": "ne", "args": [ {"exp": "input.entityType"}, {"lit": "\"company\""} ] }

  — entityType ≠ company.
• Company / organization:

  { "op": "eq", "args": [ {"exp": "input.entityType"}, {"lit": "\"company\""} ] }

  .

Omit it only for a deliberately entity-agnostic rule (rare — e.g. "whitelist every

sanctions

hit from country X"). Most library templates already carry this criterion — keep it when you adapt one.

{
  "or": [                                  // OR of AND-groups; first matching branch wins
    { "and": [
      { "op": "eq", "args": [ {"exp": "screening.vendor"}, {"lit": "\"complyAdvantageCSOM\""} ] },
      { "op": "in", "args": [ {"exp": "input.country"},    {"lit": "[\"BRA\", \"ARG\"]"} ] }
    ] }
  ]
}

• {exp: "<path>"}

  — an expression path, verbatim (from references/aml-rules-context-fields.md). It's the left side of a comparison, and also the right side for field-to-field checks (

  {exp: "match.analysis.parentName"}

  ).

• {lit: "<json>"}

  — a literal, supplied already JSON-encoded as a string (the form the API stores):

  "\"complyAdvantageCSOM\""

  ,

  "2"

  ,

  "true"

  ,

  "[\"pep\", \"sanctions\"]"

  . An un-encoded literal (

  {lit: "BRA"}

  ) is rejected by the API, so the encoding is required.

• op

  is one of the comparison operators (

  eq ne lt lte gt gte in notIn contains notContains containsAny notContainsAny containsAll containsOnly startsWith endsWith match empty notEmpty eqIgnoreCase …

  ; full set in references/aml-resolution-rules-schema.md). The builder validates every

  op

  against its known set.
• Set membership on list fields (

  match.riskLabels

  ,

  screening.tags

  ,

  match.complyAdvantage.matchTypes

  ):

  contains

  /

  containsAny

  = has the value(s);

  containsAll

  = has all of;

  containsOnly

  = has nothing but the listed values. To match "only label X" (e.g. adverse-media-only hits) use

  containsOnly ["X"]

  — never

  notContainsAny [the-other-labels]

  , which leaks because it silently assumes you enumerated the whole closed vocabulary (the risk-label set is exactly six — see references/aml-rules-enumerations.md).

• call

  invokes a built-in function — the one operator AML conditions have that workflows don't. The first arg is the function name as

  {exp: "namesIncompatible"}

  , the rest are its arguments:

  {op: "call", args: [{exp: "dobsIncompatible"}, {exp: "match.dobs"}, {exp: "input.dob"}, {lit: "\"strict\""}]}

  . Functions and their signatures: references/aml-resolution-rules-schema.md.
• Negation is expressed with the

  not*

  operators (

  notIn

  ,

  notContains

  ,

  notContainsAny

  ,

  ne

  ,

  notEmpty

  , …) — do not set a

  negate

  flag; a top-level

  condition.negate

  is rejected (UI-unsupported), matching the workflow skill.
• Dates: any

  Date

  field (

  input.dob

  ,

  match.previousReview.modifiedAt

  ,

  match.sources.latestEndDate

  ) exposes

  .ageInDays

  /

  .ageInYears

  /

  .year

  etc. — e.g.

  {op: "lt", args: [{exp: "match.previousReview.modifiedAt.ageInYears"}, {lit: "2"}]}

  .

Condition

And

Criterion

exp

• examples/minimal.json

  — tag-only rule (

  containsOnly

  on risk labels).

• examples/auto-clear-dob-mismatch.json

  —

  call

  functions + vendor match types; the most common auto-clear topology.

• examples/reuse-previous-review.json

  — whole-review

  expression

  form carrying over a previous decision, with a date-age condition. Also the rare entity-agnostic rule (carrying a prior decision reads the same for individuals and companies) — the one case that needs no

  input.entityType

  filter.

• references/aml-resolution-rules-schema.md — endpoints with rate limits, every field and enum, condition AST shape, operator list, built-in function signatures, notice message keys, execution model.
• references/aml-rules-expressions.md — expression-reference index + preamble (root variables,

  applicant

  /

  Date

  shapes, the enum caveat). Points to the two data files below; all three are lookup databases, don't read end-to-end.
• references/aml-rules-context-fields.md — every legal

  exp

  path with its type (

  ## Types

  /

  ## Index

  /

  ## Functions

  ).
• references/aml-rules-enumerations.md — allowed values for the closed-enum fields (risk labels, match statuses, PEP institution kinds, match types, …).

• sumsub-create-workflow

  — authors the same Condition AST in workflow edge conditions; its expressions reference covers the

  applicant

  /

  applicantIdDoc

  shapes.