POST Form Submission via JSON

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

                            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

• Success
• Validation Error
• Form Token Expired
• Unknown Domain

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

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

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

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

POST Form Submission via JSON with validation rules

{
    "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
}

                            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

• Success
• Validation Error
• Form Token Expired
• Unknown Domain

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

									{
    "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"
            }
        ]
    }
}
								

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

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

GET Form Submissions List

                            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

• Success
• Not Found
• Unauthenticated

									{
    "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
}
								

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

									{
    "message": "Unauthenticated."
}
								

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.

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 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