sumsub-create-cross-check-preset

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.

1. Translate the user's intent into the compact spec (below). Map their

ask to nameComparisonMode / addressComparisonMode / ignore-flags.

1. Validate — title non-empty (≤256 chars); mode is basic

(advanced is forbidden via API); every comparison mode is a valid enum.

1. Generate payload — run ${CLAUDE_SKILL_DIR}/scripts/build_cross_check_preset.py with the compact spec on stdin → full payload on stdout.
2. 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.

1. GET the preset back and verify what landed.
2. 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.