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