PATCH
/forms/{formId}Update a form
Updates a form by applying only the fields included in the request body; all other settings remain unchanged. Supply the formId path parameter and the settings to change, such as name, allowedDomains, or spamProtection.
- IdempotentThe SDK sends
Idempotency-Key, so a retried request is only applied once.
formIdstringrequired
The unique identifier of the form to update. Must contain at least one character.
Partial form settings to update. Only supplied fields are changed.
allowedDomainsarrayoptional
The sites a submission may be sent from. Each entry also covers its subdomains, and a pasted address is reduced to its host. Once the list is set, a submission must carry an Origin or Referer header naming one of them, so a server-side request is rejected unless it sends one. An empty list or null accepts submissions from anywhere.
automaticSpamFilterbooleanoptional
Whether submissions to this form are screened by the automatic spam filter. Defaults to true. Setting it to false stores every submission, including the ones the filter would have held back, and each of those counts against the workspace's quota.
botpoisonSecretKeystringoptional
The Botpoison secret key the form verifies challenges with. Write-only: it is stored on the form and never returned. Null removes it, which is refused while the form's spamProtection uses it.
customHoneypotstringoptional
Custom honeypot field name, up to 128 characters, or null.
customSpamWordsstringoptional
Custom spam words, up to 2560 characters, or null.
descriptionstringoptional
Form description, up to 512 characters, or null.
emailThreadingbooleanoptional
Whether email notifications for the form use email threading.
hCaptchaSecretKeystringoptional
The hCaptcha secret key the form verifies challenges with. Write-only: it is stored on the form and never returned. Null removes it, which is refused while the form's spamProtection uses it.
namestringoptional
The form name. Must contain between 1 and 128 characters.
notificationEmailsarray<string>optional
Email addresses to notify about submissions. Each address must be valid and no longer than 128 characters; the array can contain at most 100 addresses.
recaptchaV2SecretKeystringoptional
The reCAPTCHA v2 secret key the form verifies challenges with. Write-only: it is stored on the form and never returned. Null removes it, which is refused while the form's spamProtection uses it.
slackChannelstringoptional
Slack channel for form notifications, up to 128 characters, or null.
spamProtectionstringoptional
The challenge a submitter must pass. Requires the provider's secret key, stored on the form earlier or sent in the same request. Null disables it.
technologystringoptional
Technology associated with the form, up to 128 characters, or null.
turnstileSecretKeystringoptional
The Turnstile secret key the form verifies challenges with. Write-only: it is stored on the form and never returned. Null removes it, which is refused while the form's spamProtection uses it.
webhookUrlstringoptional
Where each submission is delivered. Must be an http or https URL, and must resolve to a public address when called.
200Returns the updated form object, including its identifier and current configuration.
allowedDomainsarray<string>required
The sites a submission may be sent from. Each entry also covers its subdomains. Empty means submissions are accepted from anywhere.
automaticSpamFilterbooleanrequired
createdAtstringrequired
customHoneypotstringrequired
customSpamWordsstringrequired
descriptionstringrequired
emailThreadingbooleanrequired
idstringrequired
namestringrequired
notificationEmailsarray<string>required
slackChannelstringrequired
spamProtectionstringrequired
technologystringrequired
updatedAtstringrequired
webhookUrlstringrequired
workspaceIdstringrequired
400Returned when the request is malformed or fails validation.
codestringrequired
detailstringrequired
statusnumberrequired
titlestringrequired
typestringrequired
401Returned when the token is missing, malformed, revoked, or expired.
codestringrequired
detailstringrequired
statusnumberrequired
titlestringrequired
typestringrequired
403Returned when the token lacks the required scope, the workspace is not upgraded, or a limit was reached.
codestringrequired
detailstringrequired
statusnumberrequired
titlestringrequired
typestringrequired
404Returned when the resource does not exist.
codestringrequired
detailstringrequired
statusnumberrequired
titlestringrequired
typestringrequired
429Returned when the caller is rate limited and should retry later.
codestringrequired
detailstringrequired
statusnumberrequired
titlestringrequired
typestringrequired
500Returned when a server-side error occurs.
codestringrequired
detailstringrequired
statusnumberrequired
titlestringrequired
typestringrequired
Error handling
A 400 is returned when the request is malformed or fails validation. A 401 is returned when the token is missing, malformed, revoked, or expired, and a 403 is returned when the token lacks the required scope, the workspace is not upgraded, or a limit was reached. A 404 indicates the form does not exist, a 429 means the caller is rate limited, and a 500 indicates a server-side failure. The formId path parameter must contain at least one character; name, if supplied, must contain between 1 and 128 characters.