Sumsub Create Poa Preset

Sumsub — Create POA Preset

Builds a POA preset JSON payload from a compact spec, POSTs it to the Sumsub API, and reports the resulting preset id so it can be attached to one or more levels via level.requiredIdDocs.docSets[].poaStepSettingsId.

Prerequisite — level must have a PROOF_OF_RESIDENCE step. A POA preset has no effect unless it is attached to a PROOF_OF_RESIDENCE (or PROOF_OF_RESIDENCE2/3/4) docset in at least one level. If the user hasn't created (or described) a level that includes a POA step, surface this before building the preset — there is no point creating it in isolation.

Endpoints

All three require permission manageClientSettings. Body shape is the POA preset schema — client-settable fields only (clientId, createdAt, createdBy, modifiedAt, audit trail are server-managed and echoed back on the response).

After creation, attach by editing a level: requiredIdDocs.docSets[].poaStepSettingsId = "<the new id>" on any PROOF_OF_RESIDENCE doc-set.

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

POA preset creation has historically been gated behind the POA entitlement, but in practice the API accepts the write for most tenants regardless — the entitlement is often baseline, covered by other keys, or simply not surfaced in allowedChecks. Don't treat its absence as a blocker.

1. Invoke sumsub-check-permissions and inspect allowedChecks — informational, for diagnostics.
2. If `POA` is present — proceed.
3. If `POA` is missing — proceed anyway, with a one-line user-visible note that the documented entitlement isn't listed (so they know what to mention to support if the POST eventually fails). Do NOT pause for confirmation — Sumsub will reject the write itself if the tenant truly lacks the right, and the 4xx from that will be more informative than a pre-emptive halt.
4. If the POST returns a 4xx that mentions an entitlement — surface the error body verbatim and suggest contacting CSM / Sumsub support.

Procedure

1. Fetch tenant entitlements — see section above.
2. Translate the user's intent into the compact spec (below). Most users describe presets in terms of "what we accept" (bank statements, utility bills) and "for how long" (validity in months) — map that into providers keys, subTypes, and validMonths.
3. Validate: name non-empty; includedCountries and excludedCountries aren't both set; every provider key is a PoaCompanyContactType; every subTypes entry is a PoaSubType; every country code is ISO-3166-1 alpha-3 uppercase; crossValidator.fuzzyThreshold in [0, 1].
4. Generate payload via ${CLAUDE_SKILL_DIR}/scripts/build_poa_preset.py (compact spec on stdin → full payload on stdout).
5. Create vs. update:

• New preset — POST via ${CLAUDE_SKILL_DIR}/scripts/post_poa_preset.sh. The payload must not carry id.
• Update existing — first GET the current state via ${CLAUDE_SKILL_DIR}/scripts/get_poa_preset.sh so the user sees the diff, then PATCH via ${CLAUDE_SKILL_DIR}/scripts/patch_poa_preset.sh. The payload must include the preset's id.

1. Build the dashboard link. Read id and clientId from the response body and format:

   https://cockpit.sumsub.com/checkus/sdkIntegrations/globalSettings/userVerification/proofOfAddress/<id>?clientId=<clientId>&sbx=true

The sbx=true query param targets the Sandbox workspace — it is the canonical sandbox link param shared across all skills.

1. Report — lead with the human-readable name; surface the id only at the end as the value to pass into the next API call:

• Name and country scope (incl/excl) + per-country override countries.
• A brief summary of what's accepted (provider types covered, default validity).
• Dashboard link as a clickable markdown link.
• Final line: Preset ID for level wiring: <id>.

Compact spec format (JSON or YAML on stdin)

name: "Standard POA (6 months)"
desc: "Default Proof of Address rules with 6-month validity"

# Country scope — choose AT MOST ONE
# includedCountries: [GBR, DEU, FRA]    # allow-list
excludedCountries: [PRK, IRN]            # block-list

# Global defaults
settings:
  acceptMultiplePages: true
  acceptDocScreenshot: true
  requireCountryMatch: false             # require POI country == POA country
  useIssueDateForExpiry: false           # use only issueDate (ignore expiry) for "fresh enough" check
  validMonths: 6                         # shortcut: applied to every provider that omits its own validMonths
  addressTypes: [dwelling, poBox]        # allowed PoA address types
  acceptableLanguages: [en, de, fr]

  # Document providers and the doc sub-types each may produce
  # Keys (PoaCompanyContactType): bank | utilityProvider | governmentOrganization | mobileOperator | other
  providers:
    bank:
      validMonths: 6
      acceptUnconventional: true         # accept non-mainstream banks (with allowedOrgNames below)
      subTypes: [bankStatement, bankLetter, other]
      allowedOrgs:                       # only used when acceptUnconventional=true
        names:    ["Some Local Co-op Bank"]
        websites: ["coopbank.example"]
      forbiddenDocumentNames: []
      forbiddenOrgNames:    []
      forbiddenOrgWebsites: []
    utilityProvider:
      subTypes: [telecom, utilityBill, other]
    governmentOrganization:
      subTypes: [statement, voterRegistration, taxBill, other]
    mobileOperator: {}                   # accept defaults
    other:
      subTypes: [lease, other, universityLetter]

  # Accept identity document as proof of address
  poiAsPoa:
    enabled: true                        # acceptPoiAsPoa
    sameDoc:  true                       # acceptSamePoiAsPoa (same doc for POI + POA)
    validMonths: 3
    allowedTypes: [PASSPORT, ID_CARD, RESIDENCE_PERMIT, DRIVERS]

  # Name/address comparison between POI and POA
  crossValidator:
    nameMode:    weakContainment         # strict | weakContainment | def | ai | fuzzy | containment | fuzzyContainment
    addressMode: fuzzy                   # strict | fuzzy
    fuzzyThreshold: 0.75
    ignoreMiddleName: false
    ignoreFixedInfo: false

# Per-country overrides — same shape as `settings`. Only the keys you set are overridden;
# others fall through to the global `settings`.
byCountry:
  BRA: