Skip to main content
POST
/
forms
Create a new form
curl --request POST \
  --url https://app.formbox.app/api/v1/forms \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '
{
  "name": "<string>",
  "type": "endpoint",
  "removeFormboxBranding": false,
  "sendEmailNotifications": true,
  "emailsToNotify": [],
  "submissionStorageDuration": "365",
  "sendRespondentEmailNotifications": false,
  "respondentEmailFromName": "",
  "respondentEmailSubject": "",
  "respondentEmailMessageHTML": "",
  "limitResponses": false,
  "isClosed": false,
  "autoCloseEnabled": false,
  "autoCloseDate": "<string>",
  "autoCloseTimezone": "<string>",
  "autoCloseTime": "<string>",
  "maxResponses": null,
  "useCustomThankYouPage": false,
  "tpButtonText": "",
  "tpButtonColor": "#030712",
  "tpButtonBackgroundColor": "#f3f4f6",
  "tpBackgroundColor": "#ffffff",
  "tpTextColor": "#030712",
  "tpHeader": "",
  "tpMessage": "",
  "tpButtonUrl": "",
  "useCustomRedirect": false,
  "customSuccessUrl": "",
  "customHoneypot": "",
  "googleRecaptchaEnabled": false,
  "googleRecaptchaSecretKey": "",
  "saveAnswers": true,
  "allowedDomains": ""
}
'
{
  "id": "<string>",
  "name": "<string>",
  "organizationId": "<string>",
  "removeFormboxBranding": true,
  "sendEmailNotifications": true,
  "emailsToNotify": [
    "<string>"
  ],
  "submissionStorageDuration": "<string>",
  "sendRespondentEmailNotifications": true,
  "respondentEmailFromName": "<string>",
  "respondentEmailSubject": "<string>",
  "respondentEmailMessageHTML": "<string>",
  "submitButtonText": "<string>",
  "limitResponses": true,
  "isClosed": true,
  "autoCloseEnabled": true,
  "autoCloseDate": "<string>",
  "autoCloseTime": "<string>",
  "autoCloseTimezone": "<string>",
  "maxResponses": 123,
  "useCustomRedirect": true,
  "customSuccessUrl": "<string>",
  "webhookEnabled": true,
  "webhookUrl": "<string>",
  "customHoneypot": "<string>",
  "googleRecaptchaEnabled": true,
  "allowedDomains": "<string>",
  "allowedCountries": "<string>",
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "type": "endpoint",
  "fields": [
    {
      "id": "<string>",
      "label": "<string>",
      "type": "<string>",
      "subtype": "<string>",
      "required": true,
      "showDescription": true,
      "description": "<string>",
      "ratingCount": 123,
      "scaleMin": 123,
      "scaleMax": 123,
      "minLabel": "<string>",
      "maxLabel": "<string>",
      "options": [
        {
          "id": "<string>",
          "value": "<string>"
        }
      ],
      "logic": {
        "rules": [
          {
            "id": "<string>",
            "action": "show_field",
            "when": {
              "combinator": "all",
              "conditions": [
                {
                  "id": "<string>",
                  "sourceFieldId": "<string>",
                  "operator": "is_empty",
                  "value": "<string>"
                }
              ]
            },
            "targetFieldId": "<string>",
            "targetFieldIds": [
              "<string>"
            ],
            "targetPageId": "<string>"
          }
        ]
      }
    }
  ],
  "accentColor": "<string>",
  "backgroundColor": "<string>",
  "buttonBackgroundColor": "<string>",
  "buttonBorderStyle": "full",
  "buttonTextColor": "<string>",
  "closeMessageDescription": "<string>",
  "closeMessageTitle": "<string>",
  "headerDescription": "<string>",
  "headerImage": "<string>",
  "headerTitle": "<string>",
  "seoDescription": "<string>",
  "seoImage": "<string>",
  "seoTitle": "<string>",
  "inputBorderStyle": "full",
  "logo": "<string>",
  "pageMode": "compact",
  "saveAnswers": true,
  "showCustomClosedMessage": true,
  "textColor": "<string>",
  "tpBackgroundColor": "<string>",
  "tpButtonColor": "<string>",
  "tpButtonText": "<string>",
  "tpButtonUrl": "<string>",
  "tpHeader": "<string>",
  "tpMessage": "<string>",
  "tpTextColor": "<string>",
  "useCustomThankYouPage": true,
  "tpButtonBackgroundColor": "<string>",
  "ipBlacklist": "<string>",
  "imageCompressionType": [
    "webp"
  ],
  "disableEmailDataCensoring": true
}

Headers

api-key
string
required

The API key.

Body

application/json
name
string
required
Minimum string length: 1
type
enum<string>
default:endpoint
Available options:
endpoint,
hosted
removeFormboxBranding
boolean
default:false
sendEmailNotifications
boolean
default:true
emailsToNotify
string[]
submissionStorageDuration
enum<string>
default:365
Available options:
30,
60,
90,
365,
forever,
never
sendRespondentEmailNotifications
boolean
default:false
respondentEmailFromName
string
default:""
respondentEmailSubject
string
default:""
respondentEmailMessageHTML
string
default:""
limitResponses
boolean
default:false
isClosed
boolean
default:false
autoCloseEnabled
boolean
default:false
autoCloseDate
string | null
autoCloseTimezone
string | null
autoCloseTime
string | null
maxResponses
number
useCustomThankYouPage
boolean
default:false
tpButtonText
string
default:""
tpButtonColor
string
default:#030712
tpButtonBackgroundColor
string
default:#f3f4f6
tpBackgroundColor
string
default:#ffffff
tpTextColor
string
default:#030712
tpHeader
string
default:""
tpMessage
string
default:""
tpButtonUrl
string
default:""
useCustomRedirect
boolean
default:false
customSuccessUrl
string
default:""
customHoneypot
string
default:""
googleRecaptchaEnabled
boolean
default:false
googleRecaptchaSecretKey
string
default:""
saveAnswers
boolean
default:true
allowedDomains
string
default:""

Response

The newly created form.

id
string
required

The unique ID of the form.

name
string
required

The name of the form.

organizationId
string
required

The ID of the organization.

removeFormboxBranding
boolean
required

Whether to remove Formbox branding from the form.

sendEmailNotifications
boolean
required

Whether to send email notifications for new submissions.

emailsToNotify
string[]
required

Email addresses to send notifications to.

submissionStorageDuration
string
required

The duration of the submission storage.

sendRespondentEmailNotifications
boolean
required

Whether to send respondent email notifications.

respondentEmailFromName
string
required

From name for respondent email notifications.

respondentEmailSubject
string
required

Subject for respondent email notifications.

respondentEmailMessageHTML
string
required

Message for respondent email notifications.

submitButtonText
string
required

Text for the submit button.

limitResponses
boolean
required

Whether to limit the number of responses for the form.

isClosed
boolean
required

Is the form closed?

autoCloseEnabled
boolean
required

Whether to auto close the form on a specific date.

autoCloseDate
string | null
required

The date to auto close the form.

autoCloseTime
string | null
required

The time to auto close the form.

autoCloseTimezone
string | null
required

The timezone for the auto close date and time.

maxResponses
number | null
required

Maximum number of responses for the form.

useCustomRedirect
boolean
required

Whether to use a custom redirect URL.

customSuccessUrl
string
required

Custom redirect URL for successful submissions.

webhookEnabled
boolean
required
deprecated

Whether to enable webhooks.

webhookUrl
string
required
deprecated

Webhook URL.

customHoneypot
string
required

Custom honeypot field name.

googleRecaptchaEnabled
boolean
required

Whether to enable Google reCAPTCHA.

allowedDomains
string
required

Allowed domains for the form.

allowedCountries
string
required

Allowed countries for the form.

createdAt
string
required

The date the form was created.

updatedAt
string
required

The date the form was last updated.

type
enum<string>
required

The type of the form. Can be endpoint or hosted.

Available options:
endpoint,
hosted
fields
object[]
required

The form fields for hosted forms.

accentColor
string
required

The form accent color.

backgroundColor
string
required

The form background color.

buttonBackgroundColor
string
required

The form button background color.

buttonBorderStyle
enum<string>
required

The form button border style.

Available options:
full,
flat,
rounded
buttonTextColor
string
required

The form button text color.

closeMessageDescription
string
required

Description for the closed message.

closeMessageTitle
string
required

Title for the closed message.

headerDescription
string
required

Description for the header.

headerImage
string
required

The form header image.

headerTitle
string
required

Title for the header.

seoDescription
string
required

Description used for social sharing and link previews.

seoImage
string
required

Absolute HTTPS image URL used for social sharing previews.

seoTitle
string
required

Title used for social sharing and link previews.

inputBorderStyle
enum<string>
required

The form input border style.

Available options:
full,
flat,
rounded

The form logo.

pageMode
enum<string>
required

The form page mode.

Available options:
compact,
full
saveAnswers
boolean
required

Whether answers are saved.

showCustomClosedMessage
boolean
required

Whether to show a custom closed message.

textColor
string
required

The form text color.

tpBackgroundColor
string
required

Background color for the thank you page.

tpButtonColor
string
required

Text color for the thank you page button.

tpButtonText
string
required

Text for the thank you page button.

tpButtonUrl
string
required

URL for the thank you page button.

tpHeader
string
required

Header text for the thank you page.

tpMessage
string
required

Message text for the thank you page.

tpTextColor
string
required

Text color for the thank you page.

useCustomThankYouPage
boolean
required

Whether to use a custom thank you page.

tpButtonBackgroundColor
string
required

Background color for the thank you page button.

ipBlacklist
string
required

IP blacklist for the form.

imageCompressionType
enum<string>[]
required

The image types used for this form.

Available options:
webp,
jpeg,
png
disableEmailDataCensoring
boolean
required

Whether to disable email data censoring for submission notifications.

Last modified on January 7, 2026