API Reference

Endpoint

POST https://app.formkove.com/api/forms/{form_id}/submissions

Replace {form_id} with your form ID from the Formkove dashboard.

Request Body

Send a JSON object with your form fields. Formkove accepts any custom field names; just match them to your frontend input fields.

Special Fields

While Formkove accepts any custom data fields, the following fields are parsed specially:

Field	Type	Description
email / replyto / reply_to / reply-to / _replyto	string	Extracted as the visitor’s email address and set as the Reply-To header in email notifications. If multiple exist, the first non-empty valid email is used.
YOUR_HONEYPOT_NAME	string	Honeypot spam check. The field name must match the custom honeypot field name configured in your form’s dashboard settings. If this field contains any non-empty value, the submission is treated as spam and silently ignored.

[!NOTE]

• Redirects: For client-side JSON (fetch) submissions, redirects are not followed and the API returns a JSON response. For standard HTML form submissions, custom redirects must be appended as a query parameter (e.g., ?redirect=https://yoursite.com/thanks) to the form’s action URL rather than passed in the request body.
• Email Subjects: The email notification subject is automatically formatted as New Submission for "[Form Name]" and cannot be overridden by form fields.

The form_id in the URL identifies the form and routes the submission. No additional key field is needed.

Example Request

fetch('https://app.formkove.com/api/forms/YOUR_FORM_ID/submissions', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json'
    },
    body: JSON.stringify({
        name: 'Jane Smith',
        email: 'jane@example.com',
        message: 'Hi, I would like to schedule a demo.'
    })
});

Response Codes

201 Created (Success)

{
    "success": true,
    "id": "sub_abc123"
}

400 Bad Request (Client Error)

Client-side parsing or validation errors, such as:

{
    "success": false,
    "error": "Invalid submission body"
}

Other potential 400 errors include:

• {"success": false, "error": "Too many fields or a field value is too large"}

403 Forbidden

Returned when security checks fail or limits are exceeded:

• Spam Protection Failure (Turnstile):

  {
      "success": false,
      "error": "Security verification failed"
  }

• Quota Exceeded:

  {
      "success": false,
      "error": "Submission limit reached"
  }

404 Not Found

Returned when the form ID does not exist or is invalid:

{
    "success": false,
    "error": "Form not found"
}

429 Rate Limited

Returned when the submission rate limit for the client IP is exceeded:

{
    "success": false,
    "error": "Too many submissions. Please try again later."
}

The response includes Retry-After and rate limiting headers.

500 / 503 Server Error

Returned when backend services or database systems are temporarily unavailable:

{
    "success": false,
    "error": "Service temporarily unavailable. Please try again later."
}

Cross-Origin Requests

The API supports CORS for client-side form submissions. JavaScript fetch() calls work directly from the browser, with no server-side proxy needed.

No File Uploads via JSON

File attachments are not supported in JSON body submissions. To receive files, use the standard HTML form submission method (multipart/form-data). This is available on Pro and Agency plans.

---

For a complete fetch-based implementation, see JavaScript Form Submission.