API - POST Validation Parameters

You can set validation rules right into submission request!
Add the parameters described below to your request body.

_validation

Here you can send a list of validation rules. Validation rules are sent as object with field name as key and array of validation rules as value.
Example:

{
  ...
  "_validation": {
    "email": [
      "email",
      "required",
      "min:5"
    ],
    "name": [
      "required",
      "min:5",
      "max:10"
    ]
  },
  ...
}

Available validation rules

Rule	Description	Default Message
required	Field is required	The :attribute field is required.
email	Accept a valid email address only	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	The :attribute must be at least :min characters.
max:n	Accept a string with <=n characters or numeric value <=n	The :attribute may not be greater than :max characters.
numeric	Accept only numeric characters	The :attribute must be a number.
date	Accept date string	The :attribute is not a valid date.

WARNING

If you include validation rules in your request, they override your form validation rules if any are set up!

_validation_messages

Optionaly you can customize the validation messages for each field and validation. In the message you can work with placeholders starting with ":".

{
  ...
    "_validation_messages": {
      "email": {                                // Field name
        "type": "Incorrect email address",      // Rule followed by Validation Message
        "required": "Missing custom :attribute attribute!"
      }
    },
  ...
}

_validation_behavior

Determines validator behaviour.

WARNING

Ignored if '_validation' object is not passed

Available options

validate_and_return (Default)

If validation fails validation errors are returned and submission is not saved.

validate_and_save

The submission is stored anyway. If validation fails the submission is marked as invalid and validation errors are stored in meta data.

Examples with validation rules

JSON

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

curl --location --request POST 'https://api.headlessforms.cloud/api/v1/form/{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 be maximum :max letters",
    		"required": "You forget to enter :attribute"
    	}
    },
    "_validation_behavior": "validate_and_return"
}'

Possible Responses

Success (200 OK)

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

Validation Error (422 Unprocessable Entity)

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