updateForm
Idempotent
Update an existing form record by its ID. Omitted fields keep their current values; changes are saved live.
Instructions
Update a form - Update an existing form record by ID. Fields omitted are untouched. Writes live data.
Required: form_id.
Cross-refs same as createForm — see Rule: Forms § Form-level recipe / § Lead-match / § Member-dashboard. Before flipping form_action_type to a public-facing value, run listFormFields to confirm the tail pattern exists.
Wrapper-enforced refusal: form_action_type=redirect AND empty form_target → call refused.
See also: createForm, deleteForm, listFormFields / createFormField.
Returns: { status: "success", message: {...updatedRecord} }.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| form_id | Yes | ||
| form_title | No | ||
| form_email_on | No | Send admin notification email on each submission. `0` = OFF, `1` = ON. | |
| form_action_type | No | Post-submit behavior. `widget` = success pop-up, `notification` = success alert banner, `redirect` = send user to `form_target` URL (wrapper-enforced: `form_target` required, see `form_target` field), `default` = member-dashboard class (admin-clone-only), `""` = no behavior (internal-only forms). When flipping FROM empty TO a public-facing value, verify the tail pattern (Button-last is agent-side, NOT wrapper-enforced) via `listFormFields`. See **Rule: Forms** § Form-level recipe. | |
| form_target | No | Destination URL, required when `form_action_type=redirect`, ignored otherwise. Full URL with `https://`. | |
| form_url | No | Save Action URL. Canonical value: `/api/widget/json/post/Bootstrap%20Theme%20-%20Function%20-%20Save%20Form`. If a form was created via this API with the correct value, leave this field alone on update - only touch it to repair a form that was created without it. | |
| table_index | No | Primary key column matching `form_table`: `website_contacts` → `ID`, `leads` → `lead_id`, `users_data` → `user_id`. Leave alone on update unless repairing a broken form. | |
| form_action_div | No | Target element ID (CSS selector with `#`) swapped on submit by the `widget` action type; harmlessly ignored on `notification` / `redirect`. Canonical value: `#main-content`. Override only when the user explicitly names a different target. | |
| form_success_message | No | Post-submit success copy. Canonical default for Standard public AND Lead-saving classes: `Your Message has been Received`. If the existing record already has a value and the user hasn't flagged the message as a problem, leave it alone. Only set this on update when (a) the user asks for different copy, or (b) the field is empty and you're filling in the canonical default. Applies to `form_action_type` ∈ {`widget`, `notification`, `redirect`}; not used by `default` class. | |
| label_to_placeholder | No | Form-level toggle. When `"1"`, BD collapses each field's `field_text` (label) into placeholder text inside the input. Per-field `field_placeholder` is overridden when this is on. | |
| _clear_fields | No | Column names to clear to empty string. Available on every `update*` operation. Works on base columns AND EAV/`users_meta` rows (rows preserved with `value=""`). To actually clear a field you MUST use this parameter — sending the field with `""` alone is a no-op (BD drops empty values). To remove a `users_meta` row entirely, use `deleteUserMeta`. See **Rule: Clearing fields**. Example: `_clear_fields: ["h2", "hero_link_url"]`. |