Sumsub — Create Questionnaire

Builds a questionnaire definition JSON payload from a compact spec, POSTs it to the Sumsub API, and reports the resulting id (client-supplied slug) and _id (server-assigned identifier).

Endpoints

All require permission manageClientSettings. Body shape is the [questionnaire schema](references/questionnaire-schema.md) — client-settable fields only (clientId, createdAt, audit metadata are server-managed).

POST vs PATCH — these are now strict. POST refuses an existing id;
PATCH refuses a missing one. The pre-INT-4893 "single POST upsert" behavior
is gone — always pick the right verb up front (call GET /{id} first if
unsure whether the questionnaire exists).

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](../sumsub-api-auth/SKILL.md) 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

Creating a questionnaire requires the QUESTIONNAIRE entitlement. Before doing anything else, invoke the sumsub-check-permissions skill and verify that QUESTIONNAIRE is present as a key in the allowedChecks map.

If QUESTIONNAIRE is not in allowedChecks — stop immediately. Do not build or POST the questionnaire. Tell the user the entitlement is missing and that they need to contact their CSM or Sumsub support to get it enabled.

Procedure

1. Fetch tenant entitlements — see section above.
2. Gather spec. Map the user's questions into the compact spec format below — never hand-write the full localized payload.
3. Validate — confirm id is a unique slug, every item has a supported type, every conditional reference points to a real <sectionId>.<itemId>.
4. Generate payload by running ${CLAUDESKILLDIR}/scripts/build_questionnaire.py with the spec on stdin. Inspect the output briefly.
5. Create vs. update — POST/PATCH scripts accept the payload as a path argument or on stdin (pipe it from build_questionnaire.py for a one-liner):

- New — POST via ${CLAUDESKILLDIR}/scripts/postquestionnaire.sh <payload.json> (or … | postquestionnaire.sh -). If the user already supplied an id they used before, GET it first via ${CLAUDESKILLDIR}/scripts/getquestionnaire.sh to avoid a 409 CONFLICT. - Update existing — GET via ${CLAUDESKILLDIR}/scripts/getquestionnaire.sh first so the user sees what they're overwriting; then PATCH via ${CLAUDESKILLDIR}/scripts/patch_questionnaire.sh <payload.json>.

1. Build the dashboard link. Read id and clientId from the response body (both fields are present on the persisted questionnaire) and format:

`` https://cockpit.sumsub.com/checkus/sdkIntegrations/questionnaireDetails/<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 title:

- title, section/item count, country/lang coverage if relevant. - Dashboard link as a clickable markdown link. - Final line: Questionnaire ID (for level wiring / future PATCH): <id>.

Surface any 4xx with the description field from the error body. For 409 CONFLICT on POST — suggest PATCH instead.

Compact spec format

JSON or YAML accepted on stdin. English titles are auto-wrapped into localizedTitle / localizedDesc. Use condition strings for show/hide logic — see [references/questionnaire-schema.md](references/questionnaire-schema.md) for syntax.

{
  "id": "source-of-funds",
  "title": "Source of Funds",
  "desc": "Optional one-liner shown to applicants.",
  "showTitleAsStepName": true,
  "sections": [
    {
      "id": "primary",
      "title": "Primary Source",
      "desc": "Optional section description.",
      "condition": null,
      "items": [
        {"id": "main", "title": "Main source?", "type": "select", "required": true,
         "options": [["salary","Salary"],["business","Business"],["other","Other"]]},
        {"id": "other", "title": "Specify", "type": "text",
         "condition": "primary.main = other"}
      ]
    }
  ]
}

Supported item types

text, textArea, date, dateTime, bool, select, phone, selectDropdown, multiSelect, countrySelect, countryMultiSelect, fileAttachment, multiFileAttachments.

select / selectDropdown / multiSelect require options: [[value, title], ...].

Outputs

On success, lead with the human-readable info:

• title, section/item count, createdAt.
• Dashboard link: https://cockpit.sumsub.com/checkus/sdkIntegrations/questionnaireDetails/<id>?clientId=<clientId>&sbx=true. Render as a clickable markdown link so the user can jump to the entity. Both id and clientId are in the POST response body; sbx=true targets the Sandbox workspace.
• Finally, on its own line: Questionnaire ID (slug, for level wiring / future PATCH): <id>.

On failure: print HTTP status + description/type from the error envelope; do not retry blindly. On 409 CONFLICT from POST — suggest PATCH for an update.

Names, not ids, in user-facing messages

This applies to every message about the questionnaire — pre-POST summary, mid-flow status updates, diagnostics — not only the final report:

• Refer to the questionnaire by title ("Applicant basics"), not by its id slug, in prose.
• The slug id belongs only on the final dedicated line (Questionnaire ID (slug): <id>) — that line is the one place a raw id is correct, because the user needs to copy it into a level's questionnaireDefId.
• When mentioning sections or items, prefer their title over their id.

Hand-off to sumsub-create-level

The id returned here (the questionnaire slug) is what you pass on a level's QUESTIONNAIRE doc-set. The level skill accepts it as questionnaireDefId (canonical) or questionnaireId (alias):

{
  "type": "QUESTIONNAIRE",
  "questionnaireDefId": "<id from this skill>"
}

See [sumsub-create-level/examples/with-presets.json](../sumsub-create-level/examples/with-presets.json).

See also

• [references/questionnaire-schema.md](references/questionnaire-schema.md) — full field list, condition expressions, gotchas.
• [examples/source-of-funds.json](examples/source-of-funds.json) — multi-section spec with conditional branches.