sumsub/agent-skills / skills/sumsub-create-questionnaire
sumsub-create-questionnaire
VerifiedCreate 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.7 KB |
| examples/source-of-funds.json | config | 2.8 KB |
| references/questionnaire-schema.md | markdown | 4.6 KB |
| scripts/build_questionnaire.pyexecutable | script | 5.7 KB |
| scripts/get_questionnaire.shexecutable | script | 1.6 KB |
| scripts/patch_questionnaire.shexecutable | script | 2.3 KB |
| scripts/post_questionnaire.shexecutable | script | 2.0 KB |
references/questionnaire-schema.md
View on GitHub# QuestionnaireDefinition — schema reference
Source: Sumsub OpenAPI (`components.schemas.QuestionnaireDefinition`).
## Top-level fields
| Field | Type | Notes |
|---|---|---|
| `id` | string | Slug — must be unique within the client. Used by levels via `questionnaireDefId`. |
| `title` | string | Human title shown to applicants. |
| `desc` | string | Optional applicant-facing description. |
| `localizedTitle` | LocalizedValue | `{values: [{lang, value}]}` — auto-built from `title`. |
| `localizedDesc` | LocalizedValue | Same shape; auto-built from `desc`. |
| `showTitleAsStepName` | boolean | If true, the questionnaire's title is used as the WebSDK step label. |
| `sections` | QuestionnaireSection[] | Required. Order matters. |
| `clientId`, `createdAt`, `_id` | — | Server-populated; do NOT send. |
## QuestionnaireSection
| Field | Type | Notes |
|---|---|---|
| `id` | string | Slug, unique within questionnaire. |
| `title` / `localizedTitle` | string / LocalizedValue | |
| `desc` / `localizedDesc` | string / LocalizedValue | Optional. |
| `condition` | string | Show/hide expression — see *Conditions*. |
| `items` | QuestionnaireItem[] | At least one. |
## QuestionnaireItem
| Field | Type | Notes |
|---|---|---|
| `id` | string | Slug, unique within section. |
| `title` / `localizedTitle` | string / LocalizedValue | |
| `desc` / `localizedDesc` | string / LocalizedValue | Optional helper text. |
| `placeholder` / `localizedPlaceholder` | string / LocalizedValue | Optional. |
| `type` | enum | See *Item types* below. |
| `required` | boolean | |
| `format` | string | Optional regex/format constraint for `text` types. |
| `condition` | string | Show/hide expression. |
| `options` | QuestionnaireItemOption[] | Required for `select` / `selectDropdown` / `multiSelect`. Each option: `{value, title, localizedTitle, score?}`. |
| `arbitraryDocType` | string | Used with file-attachment types when no preset doc type fits. |
## Item types (enum)
```
text, textArea, date, dateTime, bool, select, phone,
selectDropdown, multiSelect, countrySelect, countryMultiSelect,
fileAttachment, multiFileAttachments
```
- `select` → radio-style, single answer. Use for ≤7 options.
- `selectDropdown` → same semantics, dropdown UI. Use for long option lists.
- `multiSelect` → checkboxes; answer is an array.
- `countrySelect` / `countryMultiSelect` → ISO-3166-1 alpha-3 country codes; do NOT supply `options`.
- `bool` → renders as Yes/No; value is `"true"` / `"false"` strings server-side.
- `fileAttachment` / `multiFileAttachments` → uploads; not part of the spec value but referenced from applicant docs.
## Conditions
`condition` is a plain expression string evaluated against previously-answered items. Format:
```
<sectionId>.<itemId> <op> <literal> [AND|OR <sectionId>.<itemId> <op> <literal>]*
```
- Operators: `=`, `!=`. Combine with `AND` / `OR` (uppercase).
- Literals are bare tokens for option values (`= salary`), bare `true`/`false` for `bool`, ISO codes for country selects (`= GRC`). Tokens with spaces should be avoided — use slug values in `options`.
- Examples (verified against an existing dashboard questionnaire):
- `primary.main = salary`
- `primary.main = salary OR primary.main = business`
- `nationality_1.citizenship != GRC AND nationality_1.hasPriority1 = true`
`condition` works at item *and* section level; section-level conditions hide the entire block.
## LocalizedValue shape
```json
{ "values": [ { "lang": "en", "value": "..." } ] }
```
Add additional `{lang, value}` entries for multi-language deployments. The compact spec only carries English; extend the builder if you need more languages.
## Common gotchas
- **`id` is required on POST** — the server does not auto-generate it. Omitting `id` returns `HTTP 400 — Invalid questionnaire id: null`. Use a stable slug (e.g. `country-product-kyc`).
- `id` collisions across questionnaires fail with HTTP 400 — pick a fresh slug.
- Sending server-only fields (`_id`, `clientId`, `createdAt`) is tolerated but pointless; the builder strips them.
- Required `select`s with no `options` cause silent dashboard rendering bugs — the builder rejects them upfront.
- Conditions reference item ids by **section id + item id**, not item id alone. Common mistake.
- HTTP 400 with `description: "..."` is the contract for validation errors. Read it; don't retry blindly.
## Raw `showCondition` shape (wire format)
The compact spec uses plain strings (`"primary.main = other"`); the builder translates them. If constructing payloads directly, the server accepts:
```json
"showCondition": { "field": "<sectionId>.<itemId>", "op": "eq", "value": "<optionValue>" }
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |