Get a Form
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.
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.
formRef*||The Form, addressed by its canonical id or by its public id, the segment its public URL carries. Responses always carry the canonical id.
OK
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 GET 'https://getaiform.com/api/v1/organizations/497f6eca-6276-4993-bfeb-53cbbbba6f08/forms/497f6eca-6276-4993-bfeb-53cbbbba6f08'{ "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 }}Create a Form POST
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.
Update a Form PATCH
Updates the fields the patch names on the Form's draft and leaves the rest alone. Server-owned fields are not part of the patch. An edit reaches respondents only once the Form is published. Set validateOnly to check the patch without writing anything.