Input schema (JSON)
{
"type": "object",
"required": [
"funnel_id",
"spec"
],
"properties": {
"spec": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the funnel, shown to the person who opens it in their account."
},
"nodes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"ref": {
"type": "string",
"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."
},
"icon": {
"type": "string",
"description": "Icon shown with the question. Optional."
},
"mode": {
"type": "string",
"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\"."
},
"text": {
"type": "string",
"description": "The question itself, as the person will read it."
},
"answers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"max": {
"type": "string",
"description": "Highest accepted value. A number for \"number\", HH:mm for \"time\". Optional."
},
"min": {
"type": "string",
"description": "Lowest accepted value. A number for \"number\", HH:mm for \"time\". Optional."
},
"icon": {
"type": "string",
"description": "Icon name for a \"boolean\" tile. Optional."
},
"type": {
"type": "string",
"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\"."
},
"unit": {
"type": "string",
"description": "Unit shown next to a \"number\", e.g. \"EUR\" or \"kg\". Optional."
},
"label": {
"type": "string",
"description": "Label shown above the field. For text-block, this is the text itself."
},
"width": {
"type": "integer",
"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."
},
"target": {
"type": "string",
"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."
},
"display": {
"type": "string",
"description": "For \"checkbox-group\": \"list\" (options listed one below the other, the default) or \"dropdown\" (a dropdown showing the picked options as tags). Optional."
},
"options": {
"type": "array",
"items": {
"type": "string"
},
"description": "Selectable values. Required for \"select\" and \"checkbox-group\", ignored otherwise."
},
"variant": {
"type": "string",
"description": "Role of a \"text-block\": \"body\", \"lead\" or \"note\". Optional."
},
"decimals": {
"type": [
"integer",
"null"
],
"description": "Decimal places for \"number\". Optional."
},
"mediaUrl": {
"type": "string",
"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."
},
"required": {
"type": "boolean",
"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)."
},
"rowTitle": {
"type": "string",
"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."
},
"selection": {
"type": "string",
"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."
},
"tableRows": {
"type": "array",
"items": {
"type": "string"
},
"description": "Row labels of a \"table\"."
},
"consentText": {
"type": "string",
"description": "Consent checkbox text under a \"contact\" block. Empty means no checkbox."
},
"placeholder": {
"type": "string",
"description": "Placeholder or helper text inside the field. Optional."
},
"tableColumns": {
"type": "array",
"items": {
"type": "string"
},
"description": "Column labels of a \"table\"."
},
"contactFields": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Field key. A standard one — \"anrede\", \"name\", \"lastname\", \"email\", \"phone\", \"address\", \"postcode\", \"city\" — or your own name for a custom field."
},
"type": {
"type": "string",
"description": "Type of a CUSTOM field: \"text\", \"textarea\", \"email\", \"phone\", \"number\", \"date\", \"select\", \"checkbox\". Ignored for the standard keys."
},
"label": {
"type": "string",
"description": "Label. Empty on a standard field keeps the translated default; required on a custom one."
},
"width": {
"type": "string",
"description": "Width in the contact block's own grid: \"full\", \"twothirds\", \"half\" or \"third\"."
},
"enabled": {
"type": "boolean",
"description": "Whether the field is shown at all."
},
"options": {
"type": "array",
"items": {
"type": "string"
},
"description": "Selectable values for a custom \"select\" field."
},
"required": {
"type": "boolean",
"description": "Whether it must be filled in."
},
"placeholder": {
"type": "string",
"description": "Placeholder inside the field. Optional."
}
}
},
"description": "The sub-fields of a \"contact\" block, in order. Leave empty to keep the default set (salutation, first name, last name, email, phone)."
},
"consentRequired": {
"type": [
"boolean",
"null"
],
"description": "Whether that consent checkbox must be ticked. Only meaningful with ConsentText."
}
}
},
"description": "The answers. In \"single\" mode each one can lead somewhere else — that is the branching."
},
"subheader": {
"type": "string",
"description": "A sentence under the question. Optional."
}
}
},
"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."
},
"screens": {
"type": [
"object",
"null"
],
"properties": {
"intro": {
"type": [
"object",
"null"
],
"properties": {
"blocks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "Where a \"button\" leads. Leave empty on the intro page — there the button starts the form instead of following a link."
},
"text": {
"type": "string",
"description": "The text of the block. For \"button\" this is its label. Ignored for \"divider\"."
},
"type": {
"type": "string",
"description": "Block type. One of: \"heading\", \"text\", \"button\", \"divider\"."
},
"variant": {
"type": "string",
"description": "Style variant of the block, e.g. \"neutral\" or \"accent\". Optional."
}
}
},
"description": "The blocks of the page, top to bottom."
},
"enabled": {
"type": [
"boolean",
"null"
],
"description": "Whether the page is shown. Only meaningful for the intro page; success and dismiss are always shown when reached."
},
"confetti": {
"type": [
"boolean",
"null"
],
"description": "Confetti animation. Success page only."
}
},
"description": "Optional page shown BEFORE the first step. Set enabled = true to show it."
},
"dismiss": {
"type": [
"object",
"null"
],
"properties": {
"blocks": {
"$ref": "#/properties/spec/properties/screens/properties/intro/properties/blocks",
"items": {},
"description": "The blocks of the page, top to bottom."
},
"enabled": {
"type": [
"boolean",
"null"
],
"description": "Whether the page is shown. Only meaningful for the intro page; success and dismiss are always shown when reached."
},
"confetti": {
"type": [
"boolean",
"null"
],
"description": "Confetti animation. Success page only."
}
},
"description": "Page shown when a funnel ends in dismissal. Funnels only — a form has no such exit."
},
"success": {
"type": [
"object",
"null"
],
"properties": {
"blocks": {
"$ref": "#/properties/spec/properties/screens/properties/intro/properties/blocks",
"items": {},
"description": "The blocks of the page, top to bottom."
},
"enabled": {
"type": [
"boolean",
"null"
],
"description": "Whether the page is shown. Only meaningful for the intro page; success and dismiss are always shown when reached."
},
"confetti": {
"type": [
"boolean",
"null"
],
"description": "Confetti animation. Success page only."
}
},
"description": "Page shown after a successful submission."
}
},
"description": "The pages shown before and after the funnel: intro, success and dismiss."
},
"themeId": {
"type": "string",
"description": "Design preset id, e.g. \"classic\" or \"midnight\". Call asksteps_list_themes for the list. Leave empty to keep the current design (or the default on a new funnel)."
},
"settings": {
"type": [
"object",
"null"
],
"properties": {
"progressBar": {
"type": [
"boolean",
"null"
],
"description": "Show a progress bar across the steps. Omit to leave unchanged."
},
"submitLabel": {
"type": "string",
"description": "Label of the submit button. Empty keeps the current one."
},
"leadConfirmation": {
"type": [
"boolean",
"null"
],
"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."
}
},
"description": "Funnel-wide settings. Omit to leave them as they are."
}
},
"description": "The complete new funnel. Everything not included is removed."
},
"funnel_id": {
"type": "string",
"description": "The funnel id, from asksteps_get_funnel."
}
}
}