POST
/formsCreate a form
Creates a form in a workspace and applies any settings supplied with it. Provide the required name and workspaceId, then include any form settings you want to configure; spamProtection requires the corresponding provider secret key.
- IdempotentThe SDK sends
Idempotency-Key, so a retried request is only applied once.
Form settings for creation. name and workspaceId are required.
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.
namestringrequired
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.
workspaceIdstringrequired
The identifier of the workspace in which to create the form.
201Returns the created form, including its identifier and configured form settings.
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 a resource does not exist, a 429 means the caller is rate limited, and a 500 indicates a server-side failure. name and workspaceId are required; name must contain between 1 and 128 characters, and spamProtection must be one of the documented provider values or null.