Update Form

Update any part of a form — fields, settings, theme, or metadata. Only include the fields you want to change.

forms.edit

PUT/v1/forms/:id

Request Body

All fields are optional. Only include what you want to change.

Parameter	Type	Description
name	string	Form name
title	string	Public-facing title
description	string	Form description
fields	array	Complete fields array (replaces existing)
conditions	array	Conditional logic rules
settings	object	Form settings (deep-merged — safe to send partial updates)
theme	object \| null	Theme overrides (merged with existing; send null to reset)
customCss	string	Custom CSS for the form. Use this top-level field — it is the canonical source and is synced automatically with settings.advanced.customCss.
embedMode	string	Embed mode: "isolated" (Shadow DOM) or "open" (inherits site CSS)
siteId	string	Move form to a different site

⚠️

The fields array is replaced entirely, not merged. Always send the complete fields array when updating fields.

💡

The settings object is deep-merged with the existing settings. You can safely update just settings.thankYou without affecting settings.security, settings.tracking, etc.

Settings Object Reference

The settings object contains all form behavior configuration. Each sub-object is independently mergeable.

settings.thankYou

Controls what happens after form submission — show a message or redirect to a URL.

Parameter	Type	Description
type*	string	"message" to show a thank you page, or "redirect" to send the user to a URL
message	string	HTML content for the thank you message. Supports merge tags like {name}, {email}, {company}, etc. Only used when type is "message".
redirectUrl	string	URL to redirect to after submission. Only used when type is "redirect".
redirectDelay	number	Seconds to wait before redirecting (0-10). Default: 0.
showSubmitAnother	boolean	Show a "Submit Another Response" button on the thank you page. Default: false.
iconSize	number	Size in pixels of the success checkmark icon (32-96). Default: 48.

settings.security

Spam protection and submission limits.

Parameter	Type	Description
honeypot	boolean	Enable honeypot field for bot detection. Default: true.
rateLimitPerHour	number	Max submissions per IP per hour. Default: 10.
recaptchaEnabled	boolean	Enable reCAPTCHA v3 for this form. Default: false. The site key used is determined by the site's reCAPTCHA configuration — custom key if set, otherwise the platform global key.
recaptchaThreshold	number	reCAPTCHA v3 score threshold (0.0–1.0). Submissions scoring below this are rejected. Default: 0.5. Higher values (e.g. 0.7) are stricter; lower values (e.g. 0.3) allow more traffic through.
maxSubmissions	number	Total submission limit (0 = unlimited). Default: 0.
maxPerIp	number	Max submissions per IP total (0 = unlimited). Default: 0.
allowedDomains	string[]	Restrict form to specific domains (empty = allow all).
recaptchaBadgeMode	string	"text" (default) — hides the floating badge and shows a centered attribution line at the bottom of the form. "badge" — shows Google's default floating corner badge. "none" — hides both (you handle compliance).

💡

settings.security.recaptchaEnabled is the canonical reCAPTCHA toggle. The API keeps a flat settings.recaptchaEnabled in sync automatically — you can use either path and the value will always match.

settings.tracking

Analytics and conversion tracking.

Parameter	Type	Description
gaId	string	Google Analytics measurement ID (e.g. G-XXXXXXXXXX).
fbPixelId	string	Facebook Pixel ID.
headScripts	string	Custom scripts injected into the form head.
submitScripts	string	Scripts executed on form submission.
captureUtm	boolean	Capture UTM parameters from the page URL. Default: true.

settings.emailNotifications

Email notification configuration for new submissions.

Parameter	Type	Description
enabled	boolean	Enable email notifications. Default: false.
recipients	string[]	Email addresses to notify.
fromName	string	Sender display name (e.g. "ProForms").
subject	string	Email subject line. Supports merge tags like {form_name}, {name}, {site_name}.
bodyHtml	string	Custom HTML email body. Supports merge tags.
includeSummaryTable	boolean	Include a table of all submitted fields. Default: true.
metadata	object	Toggle submission details in email footer. All default to true.
metadata.showTimestamp	boolean	Include submission date/time.
metadata.showIpAddress	boolean	Include submitter IP address.
metadata.showDevice	boolean	Include parsed device/browser info.
metadata.showReferrer	boolean	Include referrer URL.
metadata.showPageUrl	boolean	Include form host page URL.
metadata.showUtmParams	boolean	Include UTM parameters (source, medium, campaign, etc).

settings.confirmationEmail

Auto-responder confirmation email sent to the form submitter.

Parameter	Type	Description
enabled	boolean	Enable confirmation email. Default: false.
emailFieldKey	string	The field key of the email field to send the confirmation to.
subject	string	Email subject line. Supports merge tags. Default: "Thank you for contacting {site_name}".
bodyHtml	string	Custom HTML body (used when templateStyle is "custom"). Supports merge tags.
templateStyle	string	"html" (default thank-you template), "plain" (plain text), or "custom" (use bodyHtml).
replyTo	string	Reply-to email address for the confirmation.
includeSummary	boolean	Include a summary of the submission data. Default: true.
attachments	array	Static file attachments. Each: { name: string, url: string }.

settings.integrations

Webhook and third-party integrations.

Parameter	Type	Description
webhooks	array	Array of webhook configurations. Each: { url, method, headers, events, enabled }.

settings.advanced

Advanced form configuration.

Parameter	Type	Description
customCss	string	Additional CSS scoped to this form.
customJs	string	Custom JavaScript executed in the form context.
internalName	string	Internal name for organization (not shown to users).
description	string	Internal description/notes.
tags	string[]	Tags for organizing forms.
autoDeleteDays	number	Auto-delete submissions after N days (0 = never).

Top-level settings

Parameter	Type	Description
submitButtonText	string	Submit button label. Default: "Submit".
buttonIcon	string	Icon to show on the submit button (e.g. "arrow", "send", "check").
buttonIconPosition	string	"left" or "right". Default: "right".
honeypotEnabled	boolean	Legacy honeypot toggle (prefer security.honeypot).
multiStep	boolean	Enable multi-step form mode.
closedMessage	string	Message shown when form is archived/closed.

Email Field Validation

Email fields support configurable validation strictness set via the validation object on the field.

Parameter	Type	Description
validation.emailValidation	string	"standard" (default) — basic format check (x@x.x). "strict" — format check plus blocks common disposable/temporary email domains. "none" — no format validation, accepts any input.

💡

Both client-side (live) and server-side (on submit) validation respect the emailValidation setting — they stay in sync automatically.

Phone Field Validation

Phone fields support auto-formatting, digit-only enforcement, and country-based digit validation. These are set per-field inside the validation object on each field.

Parameter	Type	Description
validation.phoneFormat	string	"us" — exactly 10 digits (US/Canada, default). "international" — 7–15 digits. "any" — no digit limit.
validation.phoneDisplayFormat	string	"parens" — (480) 555-5555 (default). "dashes" — 480-555-5555. "dots" — 480.555.5555. "none" — 4805555555 (raw digits, no mask).

💡

Auto-formatting kicks in as the user types — digits are masked in real time to the chosen format. Letters are blocked. Paste is sanitized to digits only. The placeholder automatically matches the display format if no custom placeholder is set.

curl — phone field with auto-formatting

curl -X PUT "https://proforms.io/api/v1/forms/f_abc123" \
  -H "Authorization: Bearer pf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": [
      {
        "key": "phone",
        "type": "phone",
        "label": "Phone Number",
        "required": true,
        "width": "full",
        "order": 0,
        "validation": {
          "phoneFormat": "us",
          "phoneDisplayFormat": "parens"
        }
      }
    ]
  }'

Examples

Set redirect after submission

curl

curl -X PUT "https://proforms.io/api/v1/forms/f_abc123" \
  -H "Authorization: Bearer pf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "thankYou": {
        "type": "redirect",
        "redirectUrl": "https://example.com/thank-you",
        "redirectDelay": 3
      }
    }
  }'

Custom thank you message with merge tags

curl

curl -X PUT "https://proforms.io/api/v1/forms/f_abc123" \
  -H "Authorization: Bearer pf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "thankYou": {
        "type": "message",
        "message": "<h2>Thanks, {name}!</h2><p>We received your request and will reach out to <strong>{email}</strong> within 24 hours.</p>",
        "showSubmitAnother": true,
        "iconSize": 64
      }
    }
  }'

Update embed mode and button text

curl

curl -X PUT "https://proforms.io/api/v1/forms/f_abc123" \
  -H "Authorization: Bearer pf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "embedMode": "open",
    "settings": {
      "submitButtonText": "Get My Free Quote"
    }
  }'

Configure security settings

curl

curl -X PUT "https://proforms.io/api/v1/forms/f_abc123" \
  -H "Authorization: Bearer pf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "security": {
        "rateLimitPerHour": 20,
        "maxSubmissions": 500,
        "allowedDomains": ["example.com", "app.example.com"]
      }
    }
  }'

Enable reCAPTCHA with custom threshold

curl

curl -X PUT "https://proforms.io/api/v1/forms/f_abc123" \
  -H "Authorization: Bearer pf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "security": {
        "recaptchaEnabled": true,
        "recaptchaThreshold": 0.7
      }
    }
  }'

The reCAPTCHA site key is resolved automatically — uses the site's custom key if configured, otherwise falls back to the ProForms platform key. The threshold (0.0–1.0) determines how strict scoring is; 0.5 is Google's recommended default.

Disable reCAPTCHA

curl

curl -X PUT "https://proforms.io/api/v1/forms/f_abc123" \
  -H "Authorization: Bearer pf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "security": {
        "recaptchaEnabled": false
      }
    }
  }'

Apply custom CSS

curl

curl -X PUT "https://proforms.io/api/v1/forms/f_abc123" \
  -H "Authorization: Bearer pf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "customCss": ".proform { border-radius: 16px; } .proform-submit { background: #1a1a1a; }"
  }'

Response

200 OK

{
  "success": true,
  "data": {
    "id": "f_abc123",
    "name": "Updated Contact Form",
    "version": 4,
    "updatedAt": "2026-02-17T11:00:00.000Z"
  }
}

💡

The version number increments with every update, which is useful for conflict detection.