Creates a conversational funnel in the connected asksteps account: one question at a time, where each answer decides what comes next. Requires "forms:write". Use this instead of asksteps_create_form when answers should lead to DIFFERENT follow-up questions, or when someone should be able to be ruled out part-way through. Give every question a short ref ("budget", "contact") and point each answer's target at another ref, at "next", at "success" or at "dismiss". The first question in the list is where the funnel starts. It is NOT published; publishing is a separate step.
View input schema
{
"type": "object",
"properties": {
"spec": {
"description": "The funnel: a name and its questions with their answers and targets.",
"type": "object",
"properties": {
"name": {
"description": "Name of the funnel, shown to the person who opens it in their account.",
"type": "string"
},
"themeId": {
"description": "Design id. The designs shipped with the product (e.g. \"classic\" or \"midnight\") are listed by asksteps_list_themes; the account's own designs (\"design-<number>\") by asksteps_list_designs. Leave empty to keep the current design (or the default on a new funnel). An unknown id is rejected — it is never silently replaced by the default.",
"type": "string"
},
"settings": {
"description": "Funnel-wide settings. Omit to leave them as they are.",
"type": [
"object",
"null"
],
"properties": {
"submitLabel": {
"description": "Label of the submit button. Empty keeps the current one.",
"type": "string"
},
"progressBar": {
"description": "Show a progress bar across the steps. Omit to leave unchanged.",
"type": [
"boolean",
"null"
]
},
"leadConfirmation": {
"description": "Send a confirmation email to the person who filled in the form. Off by default. Only switch this on when the user explicitly asks for it — the address is unverified.",
"type": [
"boolean",
"null"
]
}
}
},
"screens": {
"description": "The pages shown before and after the funnel: intro, success and dismiss.",
"type": [
"object",
"null"
],
"properties": {
"intro": {
"description": "Optional page shown BEFORE the first step. Set enabled = true to show it.",
"type": [
"object",
"null"
],
"properties": {
"enabled": {
"description": "Whether the page is shown. Only meaningful for the intro page; success and dismiss are always shown when reached.",
"type": [
"boolean",
"null"
]
},
"confetti": {
"description": "Confetti animation. Success page only.",
"type": [
"boolean",
"null"
]
},
"blocks": {
"description": "The blocks of the page, top to bottom.",
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"description": "Block type. One of: \"heading\", \"text\", \"button\", \"divider\".",
"type": "string"
},
"text": {
"description": "The text of the block. For \"button\" this is its label. Ignored for \"divider\".",
"type": "string"
},
"variant": {
"description": "Style variant of the block, e.g. \"neutral\" or \"accent\". Optional.",
"type": "string"
},
"href": {
"description": "Where a \"button\" leads. Leave empty on the intro page — there the button starts the form instead of following a link.",
"type": "string"
}
}
}
}
}
},
"success": {
"description": "Page shown after a successful submission.",
"type": [
"object",
"null"
],
"properties": {
"enabled": {
"description": "Whether the page is shown. Only meaningful for the intro page; success and dismiss are always shown when reached.",
"type": [
"boolean",
"null"
]
},
"confetti": {
"description": "Confetti animation. Success page only.",
"type": [
"boolean",
"null"
]
},
"blocks": {
"description": "The blocks of the page, top to bottom.",
"$ref": "#/properties/spec/properties/screens/properties/intro/properties/blocks",
"items": {}
}
}
},
"dismiss": {
"description": "Page shown when a funnel ends in dismissal. Funnels only — a form has no such exit.",
"type": [
"object",
"null"
],
"properties": {
"enabled": {
"description": "Whether the page is shown. Only meaningful for the intro page; success and dismiss are always shown when reached.",
"type": [
"boolean",
"null"
]
},
"confetti": {
"description": "Confetti animation. Success page only.",
"type": [
"boolean",
"null"
]
},
"blocks": {
"description": "The blocks of the page, top to bottom.",
"$ref": "#/properties/spec/properties/screens/properties/intro/properties/blocks",
"items": {}
}
}
}
}
},
"nodes": {
"description": "The questions, in order. THE FIRST ONE IS WHERE THE FUNNEL STARTS. Every question needs at least one answer, and every answer needs a target.",
"type": "array",
"items": {
"type": "object",
"properties": {
"ref": {
"description": "A short name for this question, used as the jump target of other answers, e.g. \"budget\" or \"contact\". Lower-case letters, digits, hyphen and underscore. It is never shown to anyone — it only wires the funnel together.",
"type": "string"
},
"text": {
"description": "The question itself, as the person will read it.",
"type": "string"
},
"subheader": {
"description": "A sentence under the question. Optional.",
"type": "string"
},
"mode": {
"description": "How the question is answered: \"single\" (picking one answer moves on straight away), \"multiple\" (tick several, then continue) or \"contact\" (the built-in contact block). Default is \"single\".",
"type": "string"
},
"icon": {
"description": "Icon shown with the question. Optional.",
"type": "string"
},
"answers": {
"description": "The answers. In \"single\" mode each one can lead somewhere else — that is the branching.",
"type": "array",
"items": {
"type": "object",
"properties": {
"target": {
"description": "Where this answer leads. One of: \"success\" (finish and show the success page), \"dismiss\" (end without a submission — for answers that rule the person out), \"next\" (the following question in the list), or the ref of another question. This is required on every answer: an answer that leads nowhere is a dead end the person cannot get out of.",
"type": "string"
},
"type": {
"description": "Field type. One of: \"text\" (single line), \"text-area\" (multi-line), \"number\", \"date\", \"time\", \"select\" (dropdown, needs options), \"checkbox-group\" (choice group, needs options; one or several answers, see Selection), \"boolean\" (single yes/no checkbox), \"file\" (upload), \"signature\" (drawn signature), \"image-upload\" (the visitor uploads one photo, e.g. a passport photo), \"contact\" (the built-in contact block: name, email, phone — use this instead of building those three by hand), \"text-block\" (explanatory text, not an input), \"table\" (a grid to fill in), \"image-choice\" (a picture to pick), \"image\", \"video\". Two more element types exist but are set only in the asksteps studio: appointment booking and custom HTML. A form that contains one of them can be read here but not written (\"editable\" is false and \"blockedBy\" says why).",
"type": "string"
},
"label": {
"description": "Label shown above the field. For text-block, this is the text itself.",
"type": "string"
},
"placeholder": {
"description": "Placeholder or helper text inside the field. Optional.",
"type": "string"
},
"required": {
"description": "Whether the person must fill this in. Ignored for \"text-block\" (it asks nothing) and for \"contact\" (that block carries its own per-field settings).",
"type": "boolean"
},
"options": {
"description": "Selectable values. Required for \"select\" and \"checkbox-group\", ignored otherwise.",
"type": "array",
"items": {
"type": "string"
}
},
"width": {
"description": "Width in a 12-column grid: 12 = full width (default), 6 = half, 4 = third. Put short related fields like first and last name side by side with 6 and 6.",
"type": "integer"
},
"rowTitle": {
"description": "Group heading placed above this field. A non-empty value also starts a new row, so this is how you split a step into named sections.",
"type": "string"
},
"min": {
"description": "Lowest accepted value. A number for \"number\", HH:mm for \"time\". Optional.",
"type": "string"
},
"max": {
"description": "Highest accepted value. A number for \"number\", HH:mm for \"time\". Optional.",
"type": "string"
},
"decimals": {
"description": "Decimal places for \"number\". Optional.",
"type": [
"integer",
"null"
]
},
"unit": {
"description": "Unit shown next to a \"number\", e.g. \"EUR\" or \"kg\". Optional.",
"type": "string"
},
"variant": {
"description": "Role of a \"text-block\": \"body\", \"lead\" or \"note\". Optional.",
"type": "string"
},
"icon": {
"description": "Icon name for a \"boolean\" tile. Optional.",
"type": "string"
},
"selection": {
"description": "For \"checkbox-group\": \"single\" (exactly one option may be picked, e.g. yes/no, gender, a membership class) or \"multiple\" (any number, the default). Optional.",
"type": "string"
},
"display": {
"description": "For \"checkbox-group\": \"list\" (options listed one below the other, the default) or \"dropdown\" (a dropdown showing the picked options as tags). Optional.",
"type": "string"
},
"mediaUrl": {
"description": "Absolute https URL of the picture or video, for \"image\", \"video\" and \"image-choice\". You cannot upload files here — point at something already online, or let the user add the file in the asksteps studio.",
"type": "string"
},
"tableRows": {
"description": "Row labels of a \"table\".",
"type": "array",
"items": {
"type": "string"
}
},
"tableColumns": {
"description": "Column labels of a \"table\".",
"type": "array",
"items": {
"type": "string"
}
},
"contactFields": {
"description": "The sub-fields of a \"contact\" block, in order. Leave empty to keep the default set (salutation, first name, last name, email, phone).",
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"description": "Field key. A standard one — \"anrede\", \"name\", \"lastname\", \"email\", \"phone\", \"address\", \"postcode\", \"city\" — or your own name for a custom field.",
"type": "string"
},
"label": {
"description": "Label. Empty on a standard field keeps the translated default; required on a custom one.",
"type": "string"
},
"placeholder": {
"description": "Placeholder inside the field. Optional.",
"type": "string"
},
"enabled": {
"description": "Whether the field is shown at all.",
"type": "boolean"
},
"required": {
"description": "Whether it must be filled in.",
"type": "boolean"
},
"type": {
"description": "Type of a CUSTOM field: \"text\", \"textarea\", \"email\", \"phone\", \"number\", \"date\", \"select\", \"checkbox\". Ignored for the standard keys.",
"type": "string"
},
"options": {
"description": "Selectable values for a custom \"select\" field.",
"type": "array",
"items": {
"type": "string"
}
},
"width": {
"description": "Width in the contact block's own grid: \"full\", \"twothirds\", \"half\" or \"third\".",
"type": "string"
}
}
}
},
"consentText": {
"description": "Consent checkbox text under a \"contact\" block. Empty means no checkbox.",
"type": "string"
},
"consentRequired": {
"description": "Whether that consent checkbox must be ticked. Only meaningful with ConsentText.",
"type": [
"boolean",
"null"
]
}
}
}
}
}
}
}
}
}
},
"required": [
"spec"
]
}