Form Fields, Arrays and File Uploads
Maintained by the SplitForms team · Updated
SplitForms accepts JSON objects, URL-encoded forms and multipart FormData. Send your form’s public access_key with /api/submit, or put it in the /f/YOUR_ACCESS_KEY URL. Keep your existing visitor field names. Use multipart FormData for file bytes; a filename in a JSON object is only text.
Choose the request format
For a standard HTML form, set method="POST" and give every input a name. For a JavaScript form with files, build FormData from the form element. Let the browser set Content-Type so its multipart boundary matches the body. JSON is useful for text-only integrations; the top-level value must be an object.
An id connects a label to an input, while name determines the submitted key. Check the request payload in your browser before debugging email delivery: an omitted field cannot appear downstream.
<form action="https://splitforms.com/api/submit" method="POST">
<input type="hidden" name="access_key" value="YOUR_ACCESS_KEY">
<label>Name <input name="name" autocomplete="name" required></label>
<label>Email <input type="email" name="email" required></label>
<label>Company <input name="company"></label>
<label>Message <textarea name="message" required></textarea></label>
<button type="submit">Send</button>
</form>References: MDN: Using FormData · SplitForms API reference
Repeated names, checkboxes and arrays
SplitForms collects repeated non-empty form values under the same key into an array. For example, two checked inputs named services can produce services: ["Support", "Sales"]. JSON callers can send an array directly. Use one consistent key across a checkbox group.
Unchecked checkboxes are absent from a native form submission. Decide what absence means in your own workflow. If your API needs an explicit boolean, construct a JSON object with true or false instead of assuming an unchecked input sends false. Disabled controls are also omitted by the browser.
References: MDN: Using FormData · MDN: Checkbox submission behavior
Keep control fields separate from answers
The endpoint reserves some names for routing, redirects and spam checks. These control values are not ordinary lead answers. Give a visitor’s business question a specific name, such as inquiry_subject, if it could conflict with a control field.
| Field | Purpose |
|---|---|
| access_key | Identifies the receiving form; not an account management token. |
| subject, from_name, replyto | Email controls; replyto identifies the visitor reply address. |
| redirect | Requested thank-you URL, checked by the endpoint’s redirect rules. |
| botcheck, form_loaded_at | Honeypot and timing controls; never ask a visitor to fill them. |
| g-recaptcha-response, cf-turnstile-response | Verification tokens from the configured CAPTCHA provider. |
References: SplitForms API reference
Send the file, then check whether it was stored
Add enctype="multipart/form-data" and a named file input. In JavaScript, pass a File object or the original FormData; input.value is a filename, not the file. SplitForms uploads require a paid plan and a connected Storage integration. The current per-submission limit is five files of 5 MB each.
A successful text submission can still have dropped files if storage is disconnected or full. Inspect the response’s note and files information, then open the submission in the dashboard and confirm each expected attachment. Treat this as a separate check from whether a notification email arrived.
References: SplitForms upload setup and storage limits · MDN: Using FormData
Frequently asked questions
Do I have to rename my existing fields?
No. Keep your visitor field names and add the routing key required by your chosen endpoint. Avoid reserved control names for ordinary answers.
Why is my checkbox missing?
An unchecked checkbox is normally omitted by the browser. Check the submitted request, then define how your application handles an absent value.