Create a new form with the Formbox API

POST

forms

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",
  "sendRespondantEmailNotifications": false,
  "respondantEmailFromName": "<string>",
  "respondantEmailSubject": "<string>",
  "limitResponses": false,
  "isClosed": false,
  "maxResponses": null,
  "useCustomThankYouPage": false,
  "tpButtonText": "<string>",
  "tpButtonColor": "#030712",
  "tpButtonBackgroundColor": "#f3f4f6",
  "tpBackgroundColor": "#ffffff",
  "tpTextColor": "#030712",
  "tpHeader": "<string>",
  "tpMessage": "<string>",
  "tpButtonUrl": "<string>",
  "useCustomRedirect": false,
  "customSuccessUrl": "<string>",
  "customHoneypot": "<string>",
  "googleRecaptchaEnabled": false,
  "googleRecaptchaSecretKey": "<string>",
  "allowedDomains": "example.com, example.org"
}'

{
  "id": "<string>",
  "name": "<string>",
  "type": "<string>",
  "submissionStorageDuration": "<string>",
  "sendEmailNotifications": true,
  "sendRespondantEmailNotifications": true,
  "emailsToNotify": [
    "<string>"
  ],
  "allowedDomains": "<string>",
  "customHoneypot": "<string>",
  "limitResponses": true,
  "maxResponses": 123,
  "respondantEmailFromName": "<string>",
  "respondantEmailSubject": "<string>",
  "respondantEmailMessageHTML": "<string>",
  "submitButtonText": "<string>",
  "webhookEnabled": true,
  "webhookUrl": "<string>",
  "useCustomRedirect": true,
  "customSuccessUrl": "<string>",
  "useCustomThankYouPage": true,
  "tpBackgroundColor": "<string>",
  "tpTextColor": "<string>",
  "tpButtonBackgroundColor": "<string>",
  "tpButtonColor": "<string>",
  "tpHeader": "<string>",
  "tpMessage": "<string>",
  "tpButtonText": "<string>",
  "tpButtonUrl": "<string>",
  "googleRecaptchaEnabled": true,
  "googleRecaptchaSecretKey": "<string>",
  "showCustomClosedMessage": true,
  "closeMessageTitle": "<string>",
  "closeMessageDescription": "<string>",
  "headerTitle": "<string>",
  "headerDescription": "<string>",
  "pageMode": "compact",
  "backgroundColor": "<string>",
  "textColor": "<string>",
  "buttonBackgroundColor": "<string>",
  "buttonTextColor": "<string>",
  "accentColor": "<string>",
  "buttonBorderStyle": "full",
  "inputBorderStyle": "full",
  "headerImage": "<string>",
  "logo": "<string>",
  "fields": [
    {
      "id": "<string>",
      "label": "<string>",
      "description": "<string>",
      "type": "<string>",
      "subtype": "<string>",
      "required": true,
      "ratingCount": 123,
      "options": [
        {
          "id": "<string>",
          "value": "<string>"
        }
      ],
      "showDescription": true
    }
  ],
  "removeFormboxBranding": true,
  "isClosed": true,
  "orgId": "<string>",
  "createdAt": "<string>",
  "updatedAt": "<string>"
}

Headers

api-key

string

required

The API key.

Body

application/json

name

string

required

Form name

Minimum length: 1

type

enum<string>

default:endpoint

Form type. The default is endpoint.

Available options:

endpoint,

hosted

removeFormboxBranding

boolean

default:false

Remove Formbox branding from the form.

sendEmailNotifications

boolean

default:true

Send email notifications for new submissions.

emailsToNotify

string[]

Email addresses to send notifications to.

submissionStorageDuration

enum<string>

default:365

How long to store submissions.

Available options:

30,

60,

90,

365,

forever,

never

sendRespondantEmailNotifications

boolean

default:false

Send respondant email notifications.

respondantEmailFromName

string

From name for respondant email notifications.

respondantEmailSubject

string

Subject for respondant email notifications.

limitResponses

boolean

default:false

Limit the number of responses for the form.

isClosed

boolean

default:false

Is the form closed for new submissions?

maxResponses

number

Maximum number of responses for the form.

useCustomThankYouPage

boolean

default:false

Use a custom thank you page.

tpButtonText

string

Text for the thank you page button.

tpButtonColor

string

default:#030712

Color for the thank you page button.

tpButtonBackgroundColor

string

default:#f3f4f6

Background color for the thank you page button.

tpBackgroundColor

string

default:#ffffff

Background color for the thank you page.

tpTextColor

string

default:#030712

Text color for the thank you page.

tpHeader

string

Header text for the thank you page.

tpMessage

string

Message text for the thank you page.

tpButtonUrl

string

URL for the thank you page button.

useCustomRedirect

boolean

default:false

Use a custom redirect URL.

customSuccessUrl

string

Custom redirect URL for successful submissions.

customHoneypot

string

Custom honeypot field name.

googleRecaptchaEnabled

boolean

default:false

Enable Google reCAPTCHA.

googleRecaptchaSecretKey

string

Google reCAPTCHA secret key.

allowedDomains

string

Allowed domains for the form.

Example:

"example.com, example.org"

Response

200

application/json

The newly created form.

string

required

The unique ID of the form.

name

string

required

The name of the form.

type

string

required

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

submissionStorageDuration

string

required

The duration of the submission storage.

sendEmailNotifications

boolean

required

Whether to send email notifications for new submissions.

sendRespondantEmailNotifications

boolean

required

Whether to send respondant email notifications.

emailsToNotify

string[]

required

Email addresses to send notifications to.

allowedDomains

string

required

Allowed domains for the form.

customHoneypot

string

required

Custom honeypot field name.

limitResponses

boolean

required

Whether to limit the number of responses for the form.

maxResponses

number | null

required

Maximum number of responses for the form.

respondantEmailFromName

string

required

From name for respondant email notifications.

respondantEmailSubject

string

required

Subject for respondant email notifications.

respondantEmailMessageHTML

string

required

Message for respondant email notifications.

submitButtonText

string

required

Text for the submit button.

webhookEnabled

boolean

required

deprecated

Whether to enable webhooks.

webhookUrl

string

required

deprecated

Webhook URL.

useCustomRedirect

boolean

required

Whether to use a custom redirect URL.

customSuccessUrl

string

required

Custom redirect URL for successful submissions.

useCustomThankYouPage

boolean

required

Whether to use a custom thank you page.

tpBackgroundColor

string

required

Background color for the thank you page.

tpTextColor

string

required

Text color for the thank you page.

tpButtonBackgroundColor

string

required

Background color for the thank you page button.

tpButtonColor

string

required

Text color 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.

tpButtonText

string

required

Text for the thank you page button.

tpButtonUrl

string

required

URL for the thank you page button.

googleRecaptchaEnabled

boolean

required

Whether to enable Google reCAPTCHA.

googleRecaptchaSecretKey

string

required

Google reCAPTCHA secret key.

showCustomClosedMessage

boolean

required

Whether to show a custom closed message.

closeMessageTitle

string

required

Title for the closed message.

closeMessageDescription

string

required

Description for the closed message.

headerTitle

string

required

Title for the header.

headerDescription

string

required

Description for the header.

pageMode

enum<string>

required

The form page mode.

Available options:

compact,

full

backgroundColor

string

required

The form background color.

textColor

string

required

The form text color.

buttonBackgroundColor

string

required

The form button background color.

buttonTextColor

string

required

The form button text color.

accentColor

string

required

The form accent color.

buttonBorderStyle

enum<string>

required

The form button border style.

Available options:

full,

flat,

rounded

inputBorderStyle

enum<string>

required

The form input border style.

Available options:

full,

flat,

rounded

headerImage

string

required

The form header image.

logo

string

required

The form logo.

fields

object[]

required

The form fields for hosted forms.

removeFormboxBranding

boolean

required

Whether to remove Formbox branding from the form.

isClosed

boolean

required

Is the form closed?

orgId

string

required

The ID of the organization.

createdAt

string

required

The date the form was created.

updatedAt

string

required

The date the form was last updated.

Retrieve a list of forms Retrieve a 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",
  "sendRespondantEmailNotifications": false,
  "respondantEmailFromName": "<string>",
  "respondantEmailSubject": "<string>",
  "limitResponses": false,
  "isClosed": false,
  "maxResponses": null,
  "useCustomThankYouPage": false,
  "tpButtonText": "<string>",
  "tpButtonColor": "#030712",
  "tpButtonBackgroundColor": "#f3f4f6",
  "tpBackgroundColor": "#ffffff",
  "tpTextColor": "#030712",
  "tpHeader": "<string>",
  "tpMessage": "<string>",
  "tpButtonUrl": "<string>",
  "useCustomRedirect": false,
  "customSuccessUrl": "<string>",
  "customHoneypot": "<string>",
  "googleRecaptchaEnabled": false,
  "googleRecaptchaSecretKey": "<string>",
  "allowedDomains": "example.com, example.org"
}'

{
  "id": "<string>",
  "name": "<string>",
  "type": "<string>",
  "submissionStorageDuration": "<string>",
  "sendEmailNotifications": true,
  "sendRespondantEmailNotifications": true,
  "emailsToNotify": [
    "<string>"
  ],
  "allowedDomains": "<string>",
  "customHoneypot": "<string>",
  "limitResponses": true,
  "maxResponses": 123,
  "respondantEmailFromName": "<string>",
  "respondantEmailSubject": "<string>",
  "respondantEmailMessageHTML": "<string>",
  "submitButtonText": "<string>",
  "webhookEnabled": true,
  "webhookUrl": "<string>",
  "useCustomRedirect": true,
  "customSuccessUrl": "<string>",
  "useCustomThankYouPage": true,
  "tpBackgroundColor": "<string>",
  "tpTextColor": "<string>",
  "tpButtonBackgroundColor": "<string>",
  "tpButtonColor": "<string>",
  "tpHeader": "<string>",
  "tpMessage": "<string>",
  "tpButtonText": "<string>",
  "tpButtonUrl": "<string>",
  "googleRecaptchaEnabled": true,
  "googleRecaptchaSecretKey": "<string>",
  "showCustomClosedMessage": true,
  "closeMessageTitle": "<string>",
  "closeMessageDescription": "<string>",
  "headerTitle": "<string>",
  "headerDescription": "<string>",
  "pageMode": "compact",
  "backgroundColor": "<string>",
  "textColor": "<string>",
  "buttonBackgroundColor": "<string>",
  "buttonTextColor": "<string>",
  "accentColor": "<string>",
  "buttonBorderStyle": "full",
  "inputBorderStyle": "full",
  "headerImage": "<string>",
  "logo": "<string>",
  "fields": [
    {
      "id": "<string>",
      "label": "<string>",
      "description": "<string>",
      "type": "<string>",
      "subtype": "<string>",
      "required": true,
      "ratingCount": 123,
      "options": [
        {
          "id": "<string>",
          "value": "<string>"
        }
      ],
      "showDescription": true
    }
  ],
  "removeFormboxBranding": true,
  "isClosed": true,
  "orgId": "<string>",
  "createdAt": "<string>",
  "updatedAt": "<string>"
}

API Reference

Forms

Submissions

Create a new form

Headers

Body

Response