Sumsub — Create / Update Cross-Check Preset

⚠️ Read this before running this skill.

Sumsub's default cross-check preset is tuned for the best balance of conversion and approval rate. Most clients should not override it. If the user hasn't named a specific comparison they want to change, stop and say:

"Cross-check rules are already configured for the best approval rate. We strongly recommend keeping the defaults. Tell me a specific tweak you need (e.g. 'allow fuzzy address match', 'ignore middle name') and we'll create a minimal override."

Only proceed if the user has a concrete, named tweak.

What is a cross-check preset

A cross-check preset controls how Sumsub compares the name and address that appear on the proof-of-identity (POI) document with the same fields on the proof-of-address (POA) document. The preset decides whether small differences ("Jonathan" vs "Jon", "Apt 4" vs "Apartment 4") are accepted or flagged as mismatches.

Don't confuse with PoA preset's crossValidator. The sumsub-create-poa-preset skill has an internal block called crossValidator (CrossValidatorSettings on PoaDocumentSettings) with nameMode / addressMode / fuzzyThreshold — that's a per-PoA-preset override for the same comparison. A workspace-level CrossCheckPreset (this skill) supplies the default when no PoA-preset override applies. When a PoA preset's crossValidator is set, it wins for documents handled by that preset.

There are two preset modes:

• basic — what this skill creates. Picks nameComparisonMode and addressComparisonMode from a small enum, plus optional ignore-flags. Best for almost everyone.
• advanced — per-rule manual configuration. Not supported via the public API (POST returns 403 Forbidden — Advanced cross-check presets cannot be managed via API). Has to be done in the dashboard.

Endpoints

All require permission manageClientSettings. Body shape is the cross-check preset schema — client-settable fields only.

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 — cross-check rules affect every verification on the workspace. 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). Token + secret are shown once — copy both before closing the dialog. The helper scripts enforce this — they reject 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.

Procedure

1. Confirm necessity — Restate the user's request in one sentence and re-state the recommendation to keep defaults. If they have a specific named tweak, proceed. Otherwise stop.
2. Translate the user's intent into the compact spec (below). Map their ask to nameComparisonMode / addressComparisonMode / ignore-flags.
3. Validate — title non-empty (≤256 chars); mode is basic (advanced is forbidden via API); every comparison mode is a valid enum.
4. Generate payload — run ${CLAUDE_SKILL_DIR}/scripts/build_cross_check_preset.py with the compact spec on stdin → full payload on stdout.
5. Create vs. update:
   • New preset — POST via ${CLAUDE_SKILL_DIR}/scripts/post_cross_check_preset.sh. Payload must NOT include id.
   • Update existing — first GET via ${CLAUDE_SKILL_DIR}/scripts/get_cross_check_preset.sh so the user sees the diff, then PATCH via ${CLAUDE_SKILL_DIR}/scripts/patch_cross_check_preset.sh. Payload must include id.
6. GET the preset back and verify what landed.
7. Report — lead with the human-readable summary, end with the id:
   • title and a one-line summary of what was tweaked vs. the default.
   • Reminder: "Default cross-check rules are recommended for the highest approval rate; you've now overridden them for these comparisons — monitor conversion before rolling to production."
   • Final line: Preset ID (for level wiring / future PATCH): <id>.

Compact spec format (JSON or YAML on stdin)

title: "Strict address, lenient name"
description: "Allow nickname variants but require exact address."

mode: basic                          # ONLY basic — advanced is forbidden via API
basicSettings:
  nameComparisonMode: weakContainment  # one of: strict | weakContainment | def | ai
  addressComparisonMode: strict        # one of: strict | fuzzy
  ignoreMiddleNameMismatch: true
  ignoreProvidedInfoMismatch: false    # if true, don't flag user-typed info that disagrees with the doc

Comparison-mode meaning

nameComparisonMode:

• strict — exact match required.
• weakContainment — token-level containment (e.g. "Jon Smith" ⊆ "Jonathan Andrew Smith").
• def — Sumsub's recommended default; balances strictness and conversion.
• ai — ML-based comparison; tolerant of common variants and transliterations.

addressComparisonMode:

• strict — character-level match (after normalisation).
• fuzzy — tolerant of abbreviations and word order.

The deprecated values (fuzzy, containment, fuzzyContainment on names) are NOT accepted via this skill.

Outputs

On success, lead with the human-readable info:

• title and a one-line summary of what was tweaked vs. the workspace default.
• Reminder: "Default cross-check rules are recommended for the highest approval rate; you've now overridden them — monitor conversion before rolling to production."
• Final line: Preset ID (for level wiring / future PATCH): <id>.

On failure: HTTP status + Sumsub's description / errorName. Common causes:

• 403 Advanced cross-check presets cannot be managed via API — mode: advanced is dashboard-only. Switch to basic mode.
• 400 with a validation message — one of the comparison-mode enums is wrong (e.g. a deprecated fuzzy / containment / fuzzyContainment name mode).

Worked examples

• examples/strict-name-only.json — tighten name match, leave address on defaults.
• examples/lenient-for-emerging-markets.json — fuzzy address + ai name, ignore middle-name mismatch.

Hand-off — attaching the preset to a level

Cross-check presets are workspace-scoped. The default preset auto-applies to every level; if you've created a custom one, you have to attach it to specific levels by setting crossCheckPresetId on the level. That's done with sumsub-create-level (or a direct PATCH on the level via sumsub-api-generic).

See also

• references/cross-check-preset-schema.md — full schema, every enum, gotchas.
• Sumsub cross-check docs.