Update a Form
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.
apiKeyx-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.
application/json- body
form*Fields to write. An omitted field is left untouched and null clears a nullable field; steps replace the whole list when supplied. A Form's type is fixed at creation.
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.
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 PATCH 'https://getaiform.com/api/v2/organizations/497f6eca-6276-4993-bfeb-53cbbbba6f08/forms/497f6eca-6276-4993-bfeb-53cbbbba6f08' \ -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 }}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.
Delete a Form DELETE
Deletes the Form. The response is empty, and a later read answers 404. Set validateOnly to check the request without deleting anything.