Sumsub — Create Level

Builds an ApplicantLevel JSON payload from a compact spec, POSTs (or PATCHes) it to the Sumsub API, and reports the resulting name / id.

Endpoints

Body: ApplicantLevel. Returns the persisted level with id, createdAt, audit trails.

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 — creating a level is a workspace-visible write. If the user offers a prod token, 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:.

If the user has already supplied credentials in conversation, reuse them; otherwise ask once before running. Never echo the secret back.

Procedure

1. Fetch tenant entitlements. Invoke the sumsub-check-permissions skill and parse the JSON result. Store the allowed array; use it for all feature-gate checks in step 2 and the entitlements section below. Do this before anything else.
2. Check existing entities. Before building anything, list existing levels, POA presets, and questionnaires (GET the respective list endpoints). If a matching entity already exists, offer to reuse its id and skip the POST — the server creates a duplicate on every POST with no name deduplication.
3. Translate the user's request to the compact spec below — name, applicant type, and a list of doc-set steps in the order they should appear in the WebSDK flow.
4. Validate — confirm every type is a real IdDocSetType, every QUESTIONNAIRE step has a questionnaireDefId that points to an existing questionnaire, every PROOF_OF_RESIDENCE* step has a poaPresetId / poaStepSettingsId (the server rejects the level if it's missing — run sumsub-create-poa-preset first if no preset exists), every COMPANY step has at least one named sub-step. Use the allowed array from step 0 to reject any entitlement-gated feature not present in it.
5. Generate payload — run ${CLAUDE_SKILL_DIR}/scripts/build_level.py with the spec on stdin → full payload on stdout.
6. Show the resolved payload to the user and ask for explicit confirmation before the first POST.
7. Create vs. update:

• New level — POST via ${CLAUDE_SKILL_DIR}/scripts/post_level.sh. Returns response body + HTTP status.
• Update existing — GET the current state via ${CLAUDE_SKILL_DIR}/scripts/get_level.sh so the user sees the diff, then PATCH via ${CLAUDE_SKILL_DIR}/scripts/patch_level.sh. The spec passed to `build_level.py` must include `id: <level-id>` — the builder preserves it into the payload, and PATCH refuses bodies without it. PATCH replaces `requiredIdDocs.docSets` as a single array — every docSet you send must carry the full intended state, since fields omitted from a docSet are wiped on the server. Copy preserved values from the GET response into your PATCH spec.

1. GET the level back via ${CLAUDE_SKILL_DIR}/scripts/get_level.sh and compare to what was sent — several fields land differently from what was sent (see gotchas in references/level-schema.md). Report any discrepancy to the user.
2. Build the dashboard link. Read id, applicantType, and clientId from the response body and format:

   https://cockpit.sumsub.com/checkus/sdkIntegrations/levels/<applicantType>Level/<id>?clientId=<clientId>&xSNSEnv=sbx

The <applicantType>Level segment is literally individualLevel for applicantType: individual (confirmed) and companyLevel for applicantType: company (assumed by analogy — surface as the best guess and flag if it 404s). The xSNSEnv=sbx 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:

• name, applicantType, ordered list of docSets created.
• Dashboard link as a clickable markdown link.
• Final line: Level ID (for SDK access tokens / future PATCH): <id>.

Surface 4xx errors verbatim — they usually point to a missing questionnaireDefId or an unknown enum value.

Tenant entitlements

Many level settings are gated behind tenant entitlements (allowedChecks). Before enabling a feature, check that the required BackgroundCheckTarget is present in the allowed array returned by sumsub-check-permissions (fetched in step 0).

DocSet type → required permission (OR — any one suffices):

Types not in this table (IDENTITY, SELFIE, APPLICANT_DATA, EMAIL_VERIFICATION, PHONE_VERIFICATION, etc.) are available to all tenants — no entitlement required.

If a requested feature requires an entitlement the tenant doesn't have — stop immediately. Do not build or POST the level. Tell the user which entitlement is missing, that the feature is unavailable on their account, and that they need to contact their CSM or Sumsub support to get it enabled. Resume only after the user confirms the entitlement has been added or explicitly decides to drop the feature.

Exception — POA. The POA / ADVANCED_POA_TYPE_DETECTION keys are often absent from allowedChecks even on tenants where the API actually accepts PROOF_OF_RESIDENCE levels (the entitlement seems to be baseline or covered by other keys; the documented mapping is stale on some tenants). When only POA is missing, proceed with a one-line warning to the user so they have context if support is later needed. Do NOT pause for explicit confirmation — Sumsub itself will reject the write if the tenant truly lacks the right, and that 4xx will be more informative than a pre-emptive halt. Surface any entitlement-related error verbatim if it comes back.

Safety

Creating a level is a write to a shared workspace. Always:

• Show the resolved payload to the user before the first POST (step 4 above).
• After each successful POST, GET the entity back and compare to what was sent — silent overrides are common.
• Do not re-POST a dependency (PoA preset, questionnaire) if it already succeeded mid-session — reuse the returned id.
• Do not delete or modify levels you didn't create in this session unless the user explicitly names them.

Names, not ids, in user-facing messages

This applies to every message you send the user about this level — not just the final report:

• Pre-POST summary: when you list which questionnaire and which POA preset will be attached, refer to each by name / title (e.g. "POA preset «POA — 60 days»", "questionnaire «Applicant basics»"). Do not paste the raw id ("6a16bfd4ded0fe13aa48165d") into prose — the user can't read it and it does not let them judge whether you picked the right entity.
• Final report: still ends with Level ID (for SDK access tokens / future PATCH): <id> on its own line — that line is the one place a raw id is correct, because the user needs to copy it for the next API call.
• Diagnostic messages: when a 4xx response references a dependency id (POA preset not found, etc.), translate it to the name before showing the user.

If you don't yet know an entity's name (e.g. user supplied only an id from outside this session), GET the entity first and surface its name; do not fall back to the id.

Compact spec format

Accepts JSON or YAML on stdin. The builder fills in sensible defaults for each doc-set type (see references/level-schema.md).

{
  "name": "Basic KYC",
  "applicantType": "individual",
  "type": "standalone",
  "docSets": [
    {"type": "IDENTITY", "docTypes": ["PASSPORT","ID_CARD","DRIVERS"]},
    {"type": "SELFIE", "videoRequired": "passiveLiveness"},
    {"type": "PROOF_OF_RESIDENCE", "docTypes": ["UTILITY_BILL"]},
    {"type": "QUESTIONNAIRE", "questionnaireDefId": "source-of-funds"}
  ]
}

Supported docSets[].type values

APPLICANT_DATA, EMAIL_VERIFICATION, PHONE_VERIFICATION, IDENTITY, IDENTITY2/3/4, SELFIE, SELFIE2, PROOF_OF_RESIDENCE, PROOF_OF_RESIDENCE2, PROOF_OF_PAYMENT, PAYMENT_METHODS, INVESTABILITY, COMPANY, COMPANY_DATA, COMPANY_DOCUMENTS, COMPANY_BENEFICIARIES, ACCREDITED_INVESTOR, E_SIGN, QUESTIONNAIRE/2/3/4, E_KYC, OTHER_DOCS, TR_RECIPIENT_INFORMATION, DEVICE_CHECK.

Per-type compact shortcuts

Unknown keys in a docSet are passed through to the API verbatim, so escape hatches are easy when you need an obscure field.

Dashboard ↔ API mapping for IDENTITY step

Verbatim labels from the Sumsub dashboard sidebar, paired with the API value to write. Match the user's description to a label, then use the value.

¹ Only meaningful with videoRequired: docapture. Silently dropped from the payload otherwise (matches the dashboard's own behavior — it deletes both keys when the radio is toggled to File upload). ² required auto-rejects Web SDK applicants; Mobile SDK only.

Defaults emitted by the builder (necessary for the dashboard to render — the controls bind to actual stored values, not implicit UI defaults; empty fields render as "Select" placeholder, not as the default option):

• videoRequired: docapture → captureMode: manualAndAuto, uploaderMode: always (unless caller overrides).
• IDENTITY always gets nfcVerificationSettings: {mode: disabled} unless caller overrides.

These match what the dashboard's own Vue watcher writes when the user first toggles Live capture. Caveat on PATCH: requiredIdDocs.docSets is replaced wholesale (only top-level Level fields merge) — every docSet in the PATCH spec must carry the full intended state, since omitted sub-fields are wiped. GET the level first and copy values you want to preserve.

Chaining with other Sumsub-* skills

This skill's QUESTIONNAIRE and PROOF_OF_RESIDENCE doc-sets accept ids produced by sibling skills, so a 3-step build-everything-from-scratch flow is natural:

See examples/with-presets.json for an end-to-end level that references both.

Outputs

On success, lead with the human-readable info:

• name, applicantType, ordered list of docSets[].idDocSetType.
• Dashboard link: https://cockpit.sumsub.com/checkus/sdkIntegrations/levels/<applicantType>Level/<id>?clientId=<clientId>&xSNSEnv=sbx. Render as a clickable markdown link. The <applicantType>Level segment is individualLevel for individuals (confirmed) or companyLevel for companies (assumed pattern). All three fields (id, applicantType, clientId) come from the POST response body; xSNSEnv=sbx targets the Sandbox workspace.
• Finally, on its own line: Level ID (for SDK access tokens / future PATCH): <id>.

On failure: HTTP status + the description/errorName from Sumsub's error envelope.

Worked examples

• examples/identity-selfie.json — the most common pattern.
• examples/identity-live-capture.json — IDENTITY-only with Live capture + all docapture sub-options + NFC.
• examples/questionnaire-only.json — pure data-collection level (like the SOF level in this repo).
• examples/full-kyc.json — APPLICANT_DATA + IDENTITY + SELFIE + PROOF_OF_RESIDENCE + QUESTIONNAIRE.
• examples/kyb-company.json — KYB level with company + UBOs + representatives steps.
• examples/with-presets.json — references both a questionnaire (questionnaireDefId) and a POA preset (poaPresetId) returned by sibling skills.

See also

• references/level-schema.md — full ApplicantLevel schema, all enum values, gotchas.