API Reference

Endpoints, request formats, and response codes for the SimplyForms public API.

Submit a form

POST/v1/forms/{formId}/submissions

Submit data to a form. This is a public endpoint— no authentication required.

Request

Accepts two content types:

  • application/x-www-form-urlencoded — standard HTML form submission.
  • application/json — JSON body with key-value pairs.

Example (JSON)

curl -X POST https://your-api.com/v1/forms/YOUR_FORM_ID/submissions \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe",
    "email": "jane@example.com",
    "message": "Hello from the API!"
  }'

Example (fetch)

const response = await fetch(
  "https://your-api.com/v1/forms/YOUR_FORM_ID/submissions",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Jane Doe",
      email: "jane@example.com",
      message: "Hello from the API!",
    }),
  }
);

const result = await response.json();
console.log(result); // { success: true, message: "Submitted successfully" }

Response

Success (200)

{ "success": true, "message": "Submitted successfully" }

If a redirect URL is configured for the form, the response will be a 303 redirect instead.

Errors

StatusReason
400Empty submission body, missing Turnstile token, or failed spam verification.
404Form not found — check your Form ID.
500Server error (e.g., database failure, misconfigured Turnstile).

Special Fields

FieldDescription
_honeyHoneypot field. If filled, submission is silently accepted but ignored.
_gotchaAlternative honeypot field. Same behavior as _honey.
emailIf present, used as the reply-to address in email notifications.
_replytoExplicit reply-to override (used if email is not present).
cf-turnstile-responseCloudflare Turnstile token. Required when Turnstile is enabled for the form. Automatically removed before storing.