APIs

Use our API to simply integrate HeadlessForms into your project.

POST Form Submission via JSON

https://app.headlessforms.cloud/api/v1/form-submission/{FORM_TOKEN}
HEADERS

Content-Type application/json
Accept application/json
BODY raw

{
  "name": "John Doe",
  "email": "john@mail.com"
}

Example request

                            curl --location --request POST 'https://app.headlessforms.cloud/api/v1/form-submission/{FORM_TOKEN}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
	"name": "John Doe",
	"email": "john@mail.com"
}'
                        

Responses

200 OK

                                            {
  "status": 200,
  "error": null,
  "message": "Submission Stored",
  "data": []
}
                                

422 Unprocessable Entity

									{
  "status": 422,
  "error": "Validation Failed",
  "message": "Error",
  "data": {
    "email": [
      "The email must be a valid email address."
    ]
  }
}
								

403 Forbidden

									{
  "status": 403,
  "error": "Form Token Expired",
  "message": "Error",
  "data": []
}
                                

403 Forbidden

									{
  "status": 403,
  "error": "Access Denied",
  "message": "Error",
  "data": []
}
                                

POST Form Submission via JSON with validation rules

https://app.headlessforms.cloud/api/v1/form-submission/{FORM_TOKEN}
HEADERS

Content-Type application/json
Accept application/json
BODY raw

{
    "email": "john@mail.com",
    "name": "John Doe",
    "_validation": {
    	"email": [
    		"email",
    		"required",
    		"min:5"
    	],
    	"name": [
    		"required",
    		"min:5",
    		"max:10"
		]
    },
    "_validation_messages": {
    	"email": {
    		"type": "Incorrect email address",
    		"required": "Missing custom :attribute attribute!"
    	},
    	"name": {
    		"required": "You forget to enter :attribute",
    		"max":  "Should me maximum :max letters"
    	}
    },
    "_validation_behavior": "validate_and_return" // Possible values: 'validate_and_return', 'validate_and_save';
                                                  // Default value: 'validate_and_return';
                                                  // Ignored if '_validation' object is not passed
}

Example request

                            curl --location --request POST 'https://app.headlessforms.cloud/api/v1/form-submission/{FORM_TOKEN}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "email": "john@mail.com",
    "name": "John Doe",
    "_validation": {
    	"email": [
    		"email",
    		"required",
    		"min:5"
    	],
    	"name": [
    		"required",
    		"min:5",
    		"max:10"
		]
    },
    "_validation_messages": {
    	"email": {
    		"type": "Incorrect email address",
    		"required": "Missing custom :attribute attribute!"
    	},
    	"name": {
    		"max":  "Should me maximum :max letters",
    		"required": "You forget to enter :attribute"
    	}
    },
    "_validation_behavior": "validate_and_return"
}'
                        

Responses

200 OK

                                            {
  "message": "Submission Stored",
  "error": null,
  "status": 200
  "data": []
}
                                

422 Unprocessable Entity

									{
    "status": 422,
    "error": "Validation Failed",
    "message": "Error",
    "data": {
        "email": [
            {
                "type": "Incorrect email address",
                "required": "Missing custom email attribute!"
            }
        ],
        "name": [
            {
                "max": "Should me maximum 10 letters",
                "required": "You forget to enter name"
            }
        ]
    }
}
								

403 Forbidden

									{
  "status": 403,
  "error": "Form Token Expired",
  "message": "Error",
  "data": []
}
                                

403 Forbidden

									{
  "status": 403,
  "error": "Access Denied",
  "message": "Error",
  "data": []
}
                                
Available Validation rules

Rule Description Default Message
required Field is required The :attribute field is required.
email Accept only an valid email address The :attribute must be a valid email address.
string Accept any text The :attribute must be a string.
min:n Accept a string with >=n characters or numeric value >=n validation.min
max:n Accept a string with <=n characters or numeric value <=n validation.max
numeric Accept only numeric characters The :attribute must be a number.
date Accept date string The :attribute is not a valid date.

GET Form Submissions List

https://app.headlessforms.cloud/api/v1/form-submission/{FORM_TOKEN}?api_token={API_TOKEN}
HEADERS

Content-Type application/json
Accept application/json
PARAMS

api_token API_TOKEN Required
If you do not have an API token, you can create it in your profile
page 2
Default value: 1
per_page 100
Default value: 50
offset 2
Default value: 0
order_by created_at
Default value: created_at
Sorting Fields:
id
form_id
is_valid
is_spam
referer
ip
created_at
updated_at
deleted_at
order_direction ASC
Default value: DESC

Example request

                            curl --location --request GET 'https://app.headlessforms.cloud/api/v1/form-submission/{FORM_TOKEN}?api_token={API_TOKEN}&page=1&per_page=50&offset=2&order_by=created_at&order_direction=ASC' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'
                        

Responses

200 OK

									{
    "message": "Submissions List",
    "data": {
        "current_page": 1,
        "data": [
            {
                "id": 7,
                "form_id": "e3f0f882-17d0-41d3-88d7-567b8e66345a",
                "data": {
                    "name": "John Doe",
                    "email": "john@mail.com",
                    "_validation_messages": {
                        "name": {
                            "max": "Should me maximum :max letters",
                            "required": "You forget to enter :attribute"
                        }, "email": {
                            "type": "Incorrect email address",
                            "required": "Missing custom :attribute attribute!"
                        }
                    }
                },
                "validation_errors": [],
                "is_valid": true,
                "spam_score": 0,
                "spam_score_reason": null,
                "is_spam": false,
                "referer": null,
                "user_agent": "curl/7.64.1",
                "ip": "127.0.0.1",
                "created_at": "2021-07-20T14:28:58.000000Z",
                "updated_at": "2021-07-20T14:28:58.000000Z",
                "deleted_at": null
            },
            {
                "id": 11,
                "form_id": "e3f0f882-17d0-41d3-88d7-567b8e66345a",
                "data": {
                    "name": "John Doe",
                    "email": "john@mail.com",
                    "_validation_messages": {
                        "name": {
                            "max": "Should me maximum :max letters",
                            "required": "You forget to enter :attribute"
                        }, "email": {
                            "type": "Incorrect email address",
                            "required": "Missing custom :attribute attribute!"
                        }
                    }
                },
                "validation_errors": [],
                "is_valid": true,
                "spam_score": 0,
                "spam_score_reason": null,
                "is_spam": false,
                "referer": null,
                "user_agent": "curl/7.64.1",
                "ip": "172.22.0.1",
                "created_at": "2021-07-20T14:28:51.000000Z",
                "updated_at": "2021-07-20T14:28:51.000000Z",
                "deleted_at": null
            },

            ...

        ],
        "first_page_url": "https://app.headlessforms.cloud/api/v1/form-submission/{FORM_TOKEN}?page=1",
        "from": 1,
        "last_page": 1,
        "last_page_url": "https://app.headlessforms.cloud/api/v1/form-submission/{FORM_TOKEN}?page=1",
        "next_page_url": null,
        "path": "https://app.headlessforms.cloud/api/v1/form-submission/{FORM_TOKEN}",
        "per_page": 50,
        "prev_page_url": null,
        "to": 8,
        "total": 8
    },
    "error": null
}
								

204 No Content

									{
    "status": 204,
    "error": "Form Not Found",
    "message": "Error",
    "data": []
}
								

200 OK

									{
    "message": "Unauthenticated."
}
								

Form Settings

Overview

Chart

  • Form stats displaying
    • all-time submissions count
    • submissions with "Invalid" status
    • submissions with "Spam" status
  • Chart displays last 7 days by default, has selector for predefined date ranges and custom date picker

Submissions

Submissions List

What is available to do:

  1. View all submissions in reverse chronological order:
    1. Submitted timestamp
    2. Data fields
    3. Status field
    4. Spam score (see more at Anti-Spam Settings)
  2. Click on a submission opens sidebar with additional details such as system fields
  3. Export All submissions to CSV or XLS file
  4. Search for submissions by entering a keyword
  5. Change visibility and order of Data fields:
    1. Show/hide columns, uncheck box to hide a field in the Table
    2. Rearrange columns, drag-n-drop fields to change their order

Settings

Overview

  • Form Name: name for easy identification of form on the HeadlessForms website, never exposed to third-parties
  • Form Token: unique token for the form, used on your websites front-end in action attribute and for direct requests to HeadlessForms API.
  • Token Expires On: date after which the form will not accept any submissions; useful for temporary promotions
Redirect
  • Successful Redirect: define a page where a user who submits form will be redirected if submission is stored successfully
  • Failed Redirect: define a page or get parameter a user will be redirected to if submission fails
  • Both fields accept following options:
    • blank - redirects back to referrer, usually its the same domain as your website where you place the form
    • /page-name - redirects to [domain.com]/page-name
    • ?success=true - redirects to [domain.com]/?success=true

Spam protection

    General rules:
  • each submission has its own spam_score which equals to 0 when received by our API
  • each spam protection tool has its own weight set
  • if tool is set up then submission is checked with such tool
  • if tool returns us a response that submission might be a spam, then spam_score = spam_score + spam_tool.weight
Domain verification:

We verify if submissions are coming from the websites you listed or not. If submission is coming from a different domain, then such submissions will be blocked (i.e. not stored). We highly recommend to use this tool.

    How to enable:
  • Enter domain name which equals to domain name where your form is located
  • Press ADD button
Akismet:

Akismet checks your forms submissions against global database of spam to prevent your form from collecting malicious content. This tool is very useful for forms in blogs collecting reviews or comments.

    How to enable:
  • you need to receive at least 1 submission to your form
  • select your fields for corresponding akismet fields, for example email field in your form should be selected for Akismets comment_author_email
  • the more Akismets fields are connected to your forms fields the more precise it detects spam
Google ReCAPTCHA:

reCAPTCHA v3 returns a score for each request without user friction. The score is based on interactions with your site and enables you to take an appropriate action for your site.

    How to enable:
  • Enter reCAPTCHA secret key you receive in Googles admin panel
HoneyPot:

When a spam bot comes to a form, it fills out EVERY input field, but it ignores the CSS code. You will need to create a regular form input field with HTML - this will be the honeypot field. The spam bot will see the field, but you’ll use CSS to hide the field from users. If the honeypot field is empty, the form submission is considered as filled by a user. On the other hand, if the honeypot field has data, you know it could only have been filled out by a spam bot.

    How to enable:
  • enter field name which spam bots may will out for sure, usually its email
  • add field with the same name to your form on your website
  • hide this email with CSS
  • you may add multiple fields but do not forget to hide them from regular users
Email Verification:

This tool will verify email addresses in form submissions to check if they belong to real persons or spam networks. Each submission will be checked and marked if contains email from invalid, spammy or non-operational mailboxes. Works best with forms which collect emails (newsletters, promotions, subscriptions etc.)

    How to enable:
  • you need to receive at least 1 submission to your form
  • select a field from a submission which contains an email address

Validation settings

    Types of validations:
  • Do not validate - submissions are received from your form and are stored without validation.
  • Accept and mark - submissions which do not pass validation rules are marked as Invalid and stored.
  • Do not accept - submissions which do not pass validation are blocked.
    Validation Rules:
  • Field Name - enter field name in your form to validate
  • Field Type - select type if it needs validation
  • Required - check if this field is required in your form
  • Min/Max Length - enter min/max characters’ length to accept
  • Message - enter error message which will be returned in response to invalid submission data

Attachments settings

    These settings are fully designed to manage file-attachments to your forms. This is how to use it:
  1. Select maximum number of files a user can attach and send you with the form by changing "Maximum files per submission"
  2. Set maximum files size (single or sum for multiple files)
  3. Update your form code by adding "enctype="multipart/form-data" attribute and "input type=file" with corresponding attributes for single and multiple attachments:
    • Single: "name="attachments"
    • Multiple: "name="attachments[]" multiple"

Data mapping

This setting allows you to customize a user-friendly name of any field you set up in your form. For example, a field in your form may have a name like "qwerty123" to protect it from spam bots but the field is actually used to collect "Last Name" of a submitter. In order to rename such fields you need to receive at least one submission, then select a field name you want to rename and enter its new user-friendly name into text field on the right. New field name will be displayed everywhere: in the list of submissions and exported data.

Duplicate Form

Create a copy of the current form including Form Settings except ones which require a submission (Akismet, Email Verification). Please be aware: submissions are not copied.

Delete Form

Deletes current form with all settings and submissions. Can be restored by request to support team.

Integrations

Learn how to connect third-party services to your HeadlessForms account and expand your forms functionality.

Zapier

Create Zap which will trigger every time you receive a submission to your form.

How to enable:

  1. Create API Token in your HeadlessForms Profile
  2. Get your Form Token on Form Overview or Settings page
  3. Go to Zapier app
  4. Setup Trigger
    1. Select "New Submission" trigger
    2. Sign In to HeadlessForms with API Token from Step 1
    3. Enter Form Token from Step 2
  5. Setup Action
  6. That is it!

Webhook

Create webhooks which will trigger every time you receive a submission, update or delete form

How to enable:

  1. Choose one of available event (Form submitted, Form Updated, Form deleted)
  2. Choose the method of the future request (GET, POST)
  3. Paste url of the webhook
  4. Optionally paste additional data for request (json format only )
  5. Press "Validate" button
  6. Check the response
  7. Press "Save" button
  8. That is it!

Team Settings

Team Forms

Forms List functionality

  • See the full list of forms created in the current team
  • Search for a form by name
  • Quick actions:
    • Create a new form
    • Go to Form Settings
    • Delete a form

Members & Settings

Team Settings

Team owner can edit following information about the Team

  • Team Logo: accepts image file, crops and resizes it automatically
  • Team Name: is used for easy identification and also generates team slug
  • Time Zone: is used to convert submissions time from UTC and for other team-related activities.

Team Members

Team owner can manage the team:

  • Invite new member by email
  • Remove joined members from team
  • View and manage pending invitations