Skip to main content
POST
/
api
/
v1
/
forms
/
submit
Submit Form
curl --request POST \
  --url https://api.example.com/api/v1/forms/submit \
  --header 'Content-Type: application/json' \
  --data '
{
  "formId": "<string>",
  "data": {
    "email": "<string>",
    "[fieldName]": {}
  },
  "redirectUrl": "<string>"
}
'
{
  "success": true,
  "message": "<string>",
  "submissionId": "<string>",
  "redirect": {
    "url": "<string>",
    "allowed": true,
    "reason": "<string>"
  }
}

​
Authentication

This endpoint requires API key authentication. Provide your API key in one of two ways:
  • Recommended: X-API-Key header
  • Alternative: Authorization: Bearer <api_key> header

​
Content Types

This endpoint supports two content types:
  • application/json - For standard form data
  • multipart/form-data - For forms with file uploads

​
Request Body

​
formId
string
required
The unique identifier of the form to submit to
​
data
object
required
Form submission data as key-value pairs matching the form’s field schema. Keys should match the field names defined in the form.
​
redirectUrl
string
Custom URL to redirect users after successful submission. Requires STANDARD or PRO plan. Free plan users will be redirected to the default Mantlz thank-you page.

​
Response

​
success
boolean
Whether the submission was successful
​
message
string
Success message
​
submissionId
string
Unique identifier for the created submission
​
redirect
object
Redirect configuration

​
Rate Limiting

This endpoint is rate-limited by IP address to prevent abuse. Rate limit information is returned in the response headers:
  • X-RateLimit-Limit: Maximum number of requests allowed
  • X-RateLimit-Remaining: Number of requests remaining in the current window
  • X-RateLimit-Reset: Unix timestamp when the rate limit resets

​
Automated Workflows

Depending on your plan and form configuration, the following actions may be triggered automatically:

​
Email Confirmations

Plans: STANDARD, PRO If email settings are enabled and a valid email is provided in the submission data, an automatic confirmation email will be sent to the submitter.

​
Developer Notifications

Plans: PRO If developer notifications are enabled, an email notification will be sent to the form owner for each submission.

​
Slack Notifications

Plans: All (if configured) If Slack webhook is configured for the form, a notification will be sent to your Slack channel.

​
Discord Notifications

Plans: All (if configured) If Discord webhook is configured for the form, a notification will be sent to your Discord server.

​
Analytics Enhancement

Submission data is automatically enhanced with analytics information:
  • User agent detection
  • Country detection (via Cloudflare headers)
  • Language preferences
  • IP address (for debugging purposes)

​
File Uploads

To submit forms with file attachments:
  1. Use multipart/form-data content type
  2. Include files as File or Blob objects
  3. Files are automatically uploaded and URLs are stored in the submission data

​
Error Responses

​
message
string
Error message describing what went wrong

​
Status Codes

  • 400 - Bad Request: Invalid parameters or missing required fields
  • 401 - Unauthorized: Invalid or inactive API key
  • 403 - Forbidden: Form does not belong to the API key owner
  • 404 - Not Found: Form not found
  • 429 - Too Many Requests: Rate limit exceeded
  • 500 - Internal Server Error: File upload failure or server error
curl -X POST "https://api.mantlz.app/api/v1/forms/submit" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "formId": "clx1234567890abcdef",
    "data": {
      "email": "[email protected]",
      "name": "John Doe",
      "message": "This is a test submission"
    },
    "redirectUrl": "https://yoursite.com/thank-you"
  }'

​
Example Response - Success

{
  "success": true,
  "message": "Form submitted successfully",
  "submissionId": "clx9876543210zyxwvu",
  "redirect": {
    "url": "https://yoursite.com/thank-you",
    "allowed": true
  }
}

​
Example Response - Free Plan Redirect Override

{
  "success": true,
  "message": "Form submitted successfully",
  "submissionId": "clx9876543210zyxwvu",
  "redirect": {
    "url": "https://mantlz.app/thank-you",
    "allowed": false,
    "reason": "Custom redirects require STANDARD or PRO plan"
  }
}

​
Example Response - Rate Limit Exceeded

{
  "message": "Too many requests, please try again later.",
  "limit": 10,
  "reset": 1709567890,
  "remaining": 0
}

​
Notes

  • Submissions are logged for debugging purposes (PRO plan)
  • File uploads are stored externally and URLs are returned
  • The email field in submission data is used for confirmation emails
  • Custom redirects require STANDARD or PRO plan
  • Rate limiting is applied per IP address to prevent spam
  • All submissions are enhanced with analytics data automatically

Build docs developers (and LLMs) love

Get started for freeTalk to us