Create a Form
Creates a Form in the Organization. The server assigns the Form's path, public id, and timestamps, so the create envelope carries none of them, and a new Form is a draft until it is published. Set validateOnly to check the envelope without writing anything.
x-api-key<token>A Dashform API key, sent in the x-api-key header. Keys are created in the dashboard and act as the user who owns them.
organizationRef*||The Organization that owns the Form, addressed by its canonical id or by its slug. Responses always carry the canonical id.
application/json- body
form*Fields for the new Form. An omitted field takes its default value; steps replace the whole list when supplied.
validateOnly?booleanRun every check the request would run and stop before persisting anything. The response describes the outcome the request would have had.
falseOK
application/json- response
Form definition.
aiHandoff*AI Handoff links on the published Start Screen. Read from the current Form, so a change takes effect without republishing. Turning it off only hides the links; a respondent's AI can still submit a Reply. A form with a Payment Step never shows them and refuses Replies submitted by a respondent's AI.
backgrounds*array<|>Background media assets available in the form
branding*Custom branding settings for a form
context*array<string>Concrete factual reference data for AI context (product specs, policies, pricing, hours, locations, rules). Do not include short topic summaries, form descriptions, interview instructions, question prompts, or generic filler; put short summary text in description instead.
createTime*stringRFC 3339 timestamp when the Form was created.
date-timedefaultMode*stringDefault respondent experience mode: guided (step-by-step), conversational (chat), or voice. A form with a Payment Step must be guided.
"guided""conversational""voice"description*stringForm description summarizing its purpose
i18n*Source language and translations.
leadScoring*live?booleanOutput only. True when one of the Form's Revisions carries the live alternate id. Address that Revision itself through the live id under the Form's revisions collection.
falsemarketplace*Marketplace participation and listing profile.
maxFollowUpQuestions*integerMaximum AI follow-up questions per response.
0 <= value <= 9007199254740991name*stringForm name/title
path*stringCanonical Form resource path in the form organizations/{organization_id}/forms/{form_id}.
^organizations\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)\/forms\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$publicId*stringPublic-facing form identifier.
publicUrl*stringPublic URL where the form can be accessed
replyCount*integerOutput only. Total number of replies received.
0 <= value <= 9007199254740991steps*array<||||||||||||||||||||>Ordered start, question, and end steps. Write each question step's description, the question it carries, by the Form's type, reading the type from the Form when the request does not set it. In a Logic Funnel (structured) the respondent reads it as is: write the exact, natural, conversational question, such as "What's your full name?", "How would you rate your experience so far?" or "Which of these best describes you?", never instructional phrasing like "Ask for…" or "Collect the user's…". In an AI Funnel (dynamic) the agent that runs the conversation reads it as the field to capture: begin with "Ask for their " and name the specific signal, such as "Ask for their full name.", "Ask for their work email." or "Ask for their satisfaction with onboarding on a 1–5 scale.". Never leave it blank. Statement, legal, and payment steps carry display copy rather than a question, so this rule does not apply to them.
theme*Visual theme configuration for a form
tone*stringConversational tone (e.g. professional, friendly, casual)
type*stringForm type: structured (Logic Funnel with explicit steps) or dynamic (AI Funnel with adaptive conversation)
"structured""dynamic"updateTime*stringRFC 3339 timestamp when the Form was last updated.
date-timevoice*Voice availability selected by the maker.
curl -X POST 'https://getaiform.com/api/v1/organizations/497f6eca-6276-4993-bfeb-53cbbbba6f08/forms' \ -H 'Content-Type: application/json' \ -d '{ "form": {}}'{ "aiHandoff": { "enabled": true }, "backgrounds": [ { "overlayOpacity": 0, "position": "left-half", "type": "image", "url": "string" } ], "branding": { "enabled": true, "logoLinkUrl": "string", "logoUrl": "string" }, "context": [ "string" ], "createTime": "2019-08-24T14:15:22Z", "defaultMode": "guided", "description": "string", "i18n": { "sourceLocale": "string", "supportedLocales": [ "string" ], "translations": { "property1": { "description": { "override": true, "sourceHash": "string", "stale": true, "value": "string" }, "name": { "override": true, "sourceHash": "string", "stale": true, "value": "string" }, "steps": { "property1": { "buttonText": { "override": true, "sourceHash": "string", "stale": true, "value": "string" }, "description": { "override": true, "sourceHash": "string", "stale": true, "value": "string" }, "options": [ { "override": true, "sourceHash": "string", "stale": true, "value": "string" } ], "title": { "override": true, "sourceHash": "string", "stale": true, "value": "string" } }, "property2": { "buttonText": { "override": true, "sourceHash": "string", "stale": true, "value": "string" }, "description": { "override": true, "sourceHash": "string", "stale": true, "value": "string" }, "options": [ { "override": true, "sourceHash": "string", "stale": true, "value": "string" } ], "title": { "override": true, "sourceHash": "string", "stale": true, "value": "string" } } } }, "property2": { "description": { "override": true, "sourceHash": "string", "stale": true, "value": "string" }, "name": { "override": true, "sourceHash": "string", "stale": true, "value": "string" }, "steps": { "property1": { "buttonText": { "override": true, "sourceHash": "string", "stale": true, "value": "string" }, "description": { "override": true, "sourceHash": "string", "stale": true, "value": "string" }, "options": [ { "override": true, "sourceHash": "string", "stale": true, "value": "string" } ], "title": { "override": true, "sourceHash": "string", "stale": true, "value": "string" } }, "property2": { "buttonText": { "override": true, "sourceHash": "string", "stale": true, "value": "string" }, "description": { "override": true, "sourceHash": "string", "stale": true, "value": "string" }, "options": [ { "override": true, "sourceHash": "string", "stale": true, "value": "string" } ], "title": { "override": true, "sourceHash": "string", "stale": true, "value": "string" } } } } } }, "leadScoring": { "enabled": true, "high": "string", "low": "string", "medium": "string" }, "live": false, "marketplace": { "bookingUrl": "string", "category": "string", "description": "string", "industry": "string", "languages": [ "string" ], "location": { "address": "string", "area": "string", "city": "string" }, "name": "string", "services": [ { "category": "string", "description": "string", "duration": "string", "name": "string", "priceRange": { "currency": "string", "max": 0, "min": 0 } } ], "enabled": true }, "maxFollowUpQuestions": 0, "name": "string", "path": "string", "publicId": "string", "publicUrl": "string", "replyCount": 0, "steps": [ { "background": { "overlayOpacity": 0, "position": "left-half", "type": "image", "url": "string" }, "branches": [ { "groups": [ [ { "negate": true, "operator": "equals", "stepKey": "string", "value": "string" } ] ], "targetStepKey": "string" } ], "description": "string", "key": "string", "title": "string", "buttonText": "string", "logoUrl": "string", "redirectUrl": "string", "type": "start" } ], "theme": { "backgroundColor": "string", "buttonRadiusPx": 0, "buttonSize": "regular", "buttonTextColor": "string", "fontFamily": "sans", "foregroundColor": "string", "primaryColor": "string", "textAnimation": "typing", "textSize": "regular" }, "tone": "string", "type": "structured", "updateTime": "2019-08-24T14:15:22Z", "voice": { "enabled": true }}List the Forms of an Organization GET
Lists the Organization's Forms, most recently updated first. Page with pageSize and the nextPageToken the response carries, and narrow the page with filter and orderBy.
Get a Form GET
Reads one Form. The Form carries its current draft; live says whether one of its Revisions is published, and the published Revision itself is addressed under the Form.