updateForm
Update an existing form record by ID, changing only the fields you specify while leaving all other settings untouched. Changes are applied 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}, _admin_edit_url: "..." }. _admin_edit_url is a centralized-admin deep-link to the Form Builder editor for this form's form_name — surface it to the user so they can jump straight to the admin edit screen for the form just updated.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| form_id | Yes | ||
| 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. | |
| form_title | No | ||
| form_target | No | Destination URL, required when `form_action_type=redirect`, ignored otherwise. Full URL with `https://`. | |
| 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. | |
| _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"]`. | |
| form_email_on | No | Send admin notification email on each submission. `0` = OFF, `1` = ON. | |
| 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_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_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. |