Submit Endpoint

The form submission API accepts POST requests with your form data.

Endpoint

POST /api/v1/form/{form_id}

The {form_id} is assigned when you create a form. Find it on your form's detail page in the dashboard.

Headers

Request Body

Include your form fields as key-value pairs. The field names must match the field schema configured on the form.

JSON

curl -X POST https://headless-form.robertboes.nl/api/v1/form/01JCK... \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alex",
    "email": "alex@example.com",
    "message": "Hello from my site!"
  }'

Form-Encoded

curl -X POST https://headless-form.robertboes.nl/api/v1/form/01JCK... \
  -d "name=Alex&email=alex@example.com&message=Hello"

JavaScript (fetch)

const response = await fetch('https://headless-form.robertboes.nl/api/v1/form/01JCK...', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Alex',
    email: 'alex@example.com',
    message: 'Hello!',
  }),
});

const data = await response.json();

HTML Form

<form action="https://headless-form.robertboes.nl/api/v1/form/01JCK..." method="POST">
  <input type="text" name="name" required />
  <input type="email" name="email" required />
  <textarea name="message"></textarea>
  <button type="submit">Send</button>
</form>

Success Response

200 OK

{
  "message": "Form submitted successfully."
}

Bot Protection Tokens

If the form has bot protection enabled, include the appropriate token field in your request body:

These fields are automatically removed from the submission data.

Honeypot Field

If the form has honeypot protection enabled, include the honeypot field in your HTML form but keep it hidden and empty. Use the field name you configured in the dashboard:

<div style="display: none;" aria-hidden="true">
  <input type="text" name="your_honeypot_field" tabindex="-1" autocomplete="off" />
</div>

CORS / Preflight

Browser-based submissions trigger a preflight OPTIONS request. Headless Forms handles this automatically based on your configured allowed origins.

For server-to-server submissions, use the X-Form-Access-Token header to bypass origin checks.

Error Responses

See Error Responses for all possible error codes and formats.