sumsub-create-questionnaire

Original：🇺🇸 English

Translated

4 scriptsChecked / no sensitive code detected

Create or update a Sumsub KYC questionnaire definition. POST `/resources/api/agent/questionnaires` to create new (fails 409 if id exists), PATCH same path to update (fails 404 if id is unknown), GET `/resources/api/agent/questionnaires/{id}` to read one back. TRIGGER when the user asks to "create / add / build / update / edit a Sumsub questionnaire", or supplies a list of questions / sections meant for a Sumsub applicant flow, or references a questionnaire id / definition to be POSTed or PATCHed. SKIP for other Sumsub entities (levels, workflows, applicants), questionnaire data (answers) submission, or non-Sumsub form builders.

3installs

Sourcesumsub/agent-skills

Added on2026-08-12

NPX Install

npx skill4agent add sumsub/agent-skills sumsub-create-questionnaire

SKILL.md Content

View Translation Comparison →

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

Method	Path	When
`POST`	`/resources/api/agent/questionnaires`	Create a new questionnaire. Fails with `409 CONFLICT` if `id` already exists.
`PATCH`	`/resources/api/agent/questionnaires`	Update an existing questionnaire (by `id` in body). Fails with `404 NOT_FOUND` if no such questionnaire.
`GET`	`/resources/api/agent/questionnaires/{id}`	Read one questionnaire (verify what landed; resolve `title` from a known `id` ).
`GET`	`/resources/api/questionnaires/list`	List all questionnaires. (Stays on the non-agent path.)
`GET`	`/resources/api/questionnaires/usedByLevels`	List questionnaires with the levels that reference them. (Stays on the non-agent path.)

All require permission

manageClientSettings

. Body shape is the questionnaire schema — 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

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/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:
.

Var	Example
`SUMSUB_APP_TOKEN`	`sbx:...` — sandbox App Token from the dashboard.
`SUMSUB_SECRET_KEY`	The paired secret shown once at token creation.
`SUMSUB_BASE`	Optional. Defaults to `https://api.sumsub.com` .

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 in the

allowed

array.

If
QUESTIONNAIRE
is not in
allowed
— 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

Fetch tenant entitlements — see section above.
Gather spec. Map the user's questions into the compact spec format below — never hand-write the full localized payload.
Validate — confirm
```
id
```
is a unique slug, every item has a supported
```
type
```
, every conditional reference points to a real
```
<sectionId>.<itemId>
```
.
Generate payload by running
```
${CLAUDE_SKILL_DIR}/scripts/build_questionnaire.py
```
with the spec on stdin. Inspect the output briefly.
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
```
${CLAUDE_SKILL_DIR}/scripts/post_questionnaire.sh <payload.json>
```
  (or
```
… | post_questionnaire.sh -
```
  ). If the user already supplied an
```
id
```
  they used before, GET it first via
```
${CLAUDE_SKILL_DIR}/scripts/get_questionnaire.sh
```
  to avoid a
```
409 CONFLICT
```
  .
- Update existing — GET via
```
${CLAUDE_SKILL_DIR}/scripts/get_questionnaire.sh
```
  first so the user sees what they're overwriting; then PATCH via
```
${CLAUDE_SKILL_DIR}/scripts/patch_questionnaire.sh <payload.json>
```
  .
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>&xSNSEnv=sbx
```
The
```
xSNSEnv=sbx
```
query param targets the Sandbox workspace — it is the canonical sandbox link param shared across all skills.
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 for syntax.

json

{
  "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>&xSNSEnv=sbx
```
. Render as a clickable markdown link so the user can jump to the entity. Both
```
id
```
and
```
clientId
```
are in the POST response body;
```
xSNSEnv=sbx
```
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):