Submit Form Data API

Every form you create in Lucid Forms is assigned a unique submission endpoint. You can submit data to this endpoint from websites, desktop applications, mobile apps, serverless functions, or custom backend scripts.

---

Endpoint Details

• Endpoint URL: https://api.lucidforms.co/f/{form-id}
• HTTP Method: POST

---

Headers

To configure how the server processes and replies to your submission, send the following HTTP headers:

Header	Value	Description
Accept	application/json	Recommended for AJAX. Tells Lucid Forms to return a JSON response with status codes. If omitted, we reply with a 302 Redirect to our success page.
Content-Type	application/json	Send this if you are posting raw JSON payloads.
Content-Type	application/x-www-form-urlencoded	Send this if posting standard browser-urlencoded form payloads.
Content-Type	multipart/form-data	Required for file uploads. Do not set this header manually in Fetch/AXIOS; the browser will automatically format the multipart boundary details.

---

Request Payload

The request body can contain any key-value pairs matching your form fields.

Special Fields

Lucid Forms intercepts specific fields to handle platform features:

• _honeypot: Used to catch automated bots silently. If this field contains any text, the submission is immediately blocked.
• email / Email: Used as the destination email address if Email Auto-Responders or the Reply-To header is active.
• cf-turnstile-response: The challenge verification token generated by Cloudflare Turnstile (if Turnstile CAPTCHA is enabled in your form settings).
• g-recaptcha-response: The verification token generated by Google reCAPTCHA v2 (if enabled).
• h-captcha-response: The verification token generated by hCaptcha (if enabled).

JSON Payload Example:

{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "message": "Hello from my custom API client!",
  "_honeypot": ""
}

---

Response Status Codes

1. 200 OK (JSON Response)

Returned when a submission is accepted and the Accept: application/json header is set.

Response Body:

{
  "success": true,
  "submission_id": "sub_8f29jK23nS",
  "message": "Submission received successfully."
}

2. 302 Found (Redirection)

Returned when a submission is accepted and the Accept header is not set to application/json.

• Redirects to your custom Redirect URL (configured in dashboard).
• If no custom redirect is configured, redirects to the default Lucid Forms success page.

3. 400 Bad Request

Returned if the form inputs are invalid, a spam keyword is matched, or CAPTCHA verification fails.

Response Body:

{
  "success": false,
  "error": "CAPTCHA verification failed. Please try again."
}

4. 404 Not Found

Returned if the form ID in the URL does not exist or has been deleted.

5. 429 Too Many Requests

Returned if the form is rate-limited (spam security) or if the form has reached its monthly submission quota limit. Upgrade to a premium plan to restore access.

---

JavaScript Fetch Implementation

fetch('https://api.lucidforms.co/f/{form-id}', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    name: 'Alex Rivera',
    email: 'alex@example.com',
    message: 'Testing custom POST requests.'
  })
})
.then(response => response.json())
.then(data => {
  if (data.success) {
    console.log('Submission ID:', data.submission_id);
  } else {
    console.error('Error:', data.error);
  }
})
.catch(err => console.error('Network Error:', err));