splitforms

https://splitforms.com/docs
Admin
splitforms is a hosted form backend that turns any HTML form into emails and a searchable dashboard....
Tokens:23,913
Snippets:166
Trust Score:3
Update:6 days ago
Show doc for...
Tokens:
Raw
### POST /api/submit

Source: https://splitforms.com/docs/submission-errors

Detailed documentation for the SplitForms public submission endpoint, including request format, success and error responses, and example JavaScript usage.

```APIDOC
## [POST] /api/submit

### Description
Submit a form to SplitForms with JSON response

### Method
POST

### Endpoint
https://splitforms.com/api/submit

### Parameters
#### Request Body
- FormData or JSON object - Required - Form fields including hidden access_key input

#### Query Parameters
- None

### Request Example
formData with fields

### Response
#### Success Response (200)
- **success** (boolean) - true if submitted
- **message** (string) - "Submission received"
- **note** (string) - Optional upload warning

#### Response Example
{"success":true,"message":"Submission received"}

#### Error Responses
- 400 - missing_access_key, invalid_body
- 404 - invalid_access_key
- 403 - inactive_form, origin_not_allowed, form_unavailable
- 413 - payload_too_large
- 415 - unsupported_content_type
- 429 - rate_limited, quota_reached
- 500 - profile_lookup_failed or general failure
```

--------------------------------

### JSON payload Make receives from splitforms

Source: https://splitforms.com/docs/make

Example of the full JSON body sent to the Make webhook when a submission is created. Fields are under submission.data with the exact name attributes from the HTML form. Headers include Content-Type, X-Splitforms-Event, X-Splitforms-Signature, and User-Agent. Delivery times out after 8 seconds and is not auto-retried.

```json
{
  "event": "submission.created",
  "submission": {
    "id": "3f9a2b7e-4c1d-4e9a-9b2f-7a6c1d3e4f5a",
    "form_name": "Contact",
    "data": {
      "name": "Ada Lovelace",
      "email": "ada@example.com",
      "message": "Hello."
    },
    "ip_address": "203.0.113.7",
    "referer": "https://yoursite.com/contact",
    "created_at": "2026-05-04T14:31:04.123Z"
  }
}
```

--------------------------------

### Verify webhook signature with Node.js crypto

Source: https://splitforms.com/docs

Node.js example using crypto.timingSafeEqual to verify the X-Splitforms-Signature header. The signature is HMAC-SHA256 of the raw body with the shared secret. Includes an Express route that reads the raw body and responds 401 on invalid signature.

```javascript
import crypto from "node:crypto";

function verify(rawBody, signatureHeader, secret) {
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", secret).update(rawBody, "utf8").digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader),
  );
}

// Express — read the RAW body, not the parsed JSON.
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const sig = req.header("X-Splitforms-Signature");
  if (!sig || !verify(req.body, sig, process.env.SPLITFORMS_WEBHOOK_SECRET)) {
    return res.status(401).end();
  }
  const { submission } = JSON.parse(req.body);
  // …do work with submission
  res.status(200).end();
});
```

--------------------------------

### Error response JSON example

Source: https://splitforms.com/docs

Shows the JSON error response shape with a machine-readable 'code' field for branching. The 'message' field contains a human-readable description.

```json
{
  "success": false,
  "message": "Missing access_key. Copy the form access key from your dashboard…",
  "code": "missing_access_key"
}
```

--------------------------------

### HTML form with access key and optional tracker

Source: https://splitforms.com/docs

Paste this form on any page, replacing YOUR_ACCESS_KEY with your key. The honeypot field is hidden from humans but bots may fill it. The optional script loads the tracker for drop-off analytics and partial-lead capture on paid plans; the form works without it.

```HTML
<form action="https://splitforms.com/api/submit" method="POST">
  <input type="hidden" name="access_key" value="YOUR_ACCESS_KEY" />

  <input type="text"  name="name"    placeholder="Your name"  required />
  <input type="email" name="email"   placeholder="Your email" required />
  <textarea           name="message" placeholder="Message"    required></textarea>

  <!-- honeypot: bots fill this, humans never see it -->
  <input type="checkbox" name="botcheck" style="display:none" tabindex="-1" />

  <button type="submit">Send</button>
</form>

<!-- one-line tracker: drop-off analytics + partial leads (paid) -->
<script src="https://splitforms.com/embed.js" async></script>
```

--------------------------------

### POST /

Source: https://splitforms.com/docs

Submits form data to the Splitforms backend. The endpoint expects a POST request with an access_key identifying the form, along with any additional form fields.

```APIDOC
## POST [Form submission endpoint]?
```

--------------------------------

### Lovable prompt for connecting contact form to Splitforms

Source: https://splitforms.com/docs

Paste this prompt into the Lovable chat to connect an existing contact form to Splitforms. It instructs the AI to use the provided endpoint and access key, add hidden fields, and avoid unnecessary backend services. Replace YOUR_ACCESS_KEY with your actual key or let the AI ask for it.

```text
Connect the contact form on my site to splitforms, a hosted form backend. The browser POSTs straight to splitforms, which stores every submission in my dashboard and emails it to me.

Endpoint: POST https://splitforms.com/api/submit
Access key: YOUR_ACCESS_KEY (public form ID, safe in client code). If it still reads YOUR_ACCESS_KEY, ask me for my key before writing code; a free one comes from https://splitforms.com/login?ref=ai-prompt.

This is a React + Vite app. Update the existing contact form component (or add one to the contact section if there is none) and keep its current design.
Do not connect Supabase, create a table, write an edge function, or use Resend for this form.

Requirements:
1. Give every input a name attribute (name, email, message…). Each name becomes a column in my splitforms dashboard, and the "email" field becomes the Reply-To of my notification.
2. Inside the <form>, add <input type="hidden" name="access_key" value="YOUR_ACCESS_KEY"> and a spam honeypot <input type="checkbox" name="botcheck" tabindex="-1" autocomplete="off" style="display:none"> that stays unchecked.
3. On submit: preventDefault, keep a reference to the form element before any await, disable the button, then
   const res = await fetch("https://splitforms.com/api/submit", { method: "POST", headers: { Accept: "application/json" }, body: new FormData(form) });
   const data = await res.json();
   Don't set Content-Type yourself and don't JSON.stringify the form.
4. If data.success is true, reset the form and show an inline thank-you message (no page change). Otherwise show data.message next to the button and keep what the visitor typed. On a network error, show "Couldn't send. Please try again."
5. Add <script src="https://splitforms.com/embed.js" async></script> once, in index.html, inside <head>. It adds a hidden sf_sid field for drop-off analytics; new FormData(form) sends it along.

Then tell me to send one test entry and check that it appears in my splitforms dashboard. Reference: https://splitforms.com/docs?ref=ai-prompt#ai-builders
```

--------------------------------

### Read submissions with curl using bearer token

Source: https://splitforms.com/docs

Sends a GET request to /api/submissions with an Authorization bearer header containing your account token. The token is found under Dashboard → MCP and scopes to your whole account.

```bash
curl https://splitforms.com/api/submissions \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

--------------------------------

### Bolt prompt for connecting contact form to Splitforms

Source: https://splitforms.com/docs

Paste this prompt into the Bolt.new chat to connect a contact form to Splitforms. It instructs the AI to use the provided endpoint and access key, add hidden fields, and avoid unnecessary backend services. Replace YOUR_ACCESS_KEY with your actual key or let the AI ask for it.

```text
Connect the contact form on my site to splitforms, a hosted form backend. The browser POSTs straight to splitforms, which stores every submission in my dashboard and emails it to me.


```

--------------------------------

### JSON success response

Source: https://splitforms.com/docs

Returned with HTTP 200 when the request sets Accept: application/json or Content-Type: application/json. Otherwise, a plain HTML form post gets a 302 redirect if configured, or a built-in success page.

```JSON
{
  "success": true,
  "message": "Submission received"
}
```

--------------------------------

### Astro form with environment variable access key

Source: https://splitforms.com/docs

Use this Astro component to create a form that posts to the splitforms endpoint. The access key is read from the PUBLIC_SPLITFORMS_KEY environment variable at build time. Includes a hidden botcheck field for spam prevention.

```astro
---
// src/pages/contact.astro
const ACCESS_KEY = import.meta.env.PUBLIC_SPLITFORMS_KEY;
---

<form action="https://splitforms.com/api/submit" method="POST">
  <input type="hidden" name="access_key" value={ACCESS_KEY} />
  <input type="text"  name="name"  required />
  <input type="email" name="email" required />
  <textarea           name="message" required />
  <input type="checkbox" name="botcheck" style="display:none" tabindex="-1" />
  <button type="submit">Send</button>
</form>
```

--------------------------------

### Next.js form page using server action (page.tsx)

Source: https://splitforms.com/docs

Client page component that uses the sendContact server action as the form action. Provides progressive enhancement and requires the actions.ts file to be present.

```tsx
// app/contact/page.tsx
import { sendContact } from "./actions";

export default function ContactPage() {
  return (
    <form action={sendContact}>
      <input name="name"  required />
      <input name="email" type="email" required />
      <textarea name="message" required />
      <button type="submit">Send</button>
    </form>
  );
}
```

--------------------------------

### POST file upload to /api/submit

Source: https://splitforms.com/docs

Submit files along with form data to the same /api/submit URL using multipart/form-data. Up to 5 files per submission and 5 MB per file. Requires a paid plan with Storage integration.

```APIDOC
## [POST] multipart/form-data file upload to /api/submit

### Description
Uploads files with your submission using multipart/form-data. Up to 5 files per submission and 5 MB per file. Requires a paid plan with Storage integration connected.
```

--------------------------------

### Next.js server action (actions.ts)

Source: https://splitforms.com/docs

Server action for Next.js App Router that keeps the access key on the server. Sends JSON to SplitForms with the key from SPLITFORMS_KEY, throws on non-OK response, and returns a success flag.

```typescript
// app/contact/actions.ts
"use server";

export async function sendContact(formData: FormData) {
  const res = await fetch("https://splitforms.com/api/submit", {
    method: "POST",
    headers: { "Content-Type": "application/json", Accept: "application/json" },
    body: JSON.stringify({
      access_key: process.env.SPLITFORMS_KEY!,
      name:    formData.get("name"),
      email:   formData.get("email"),
      message: formData.get("message"),
    }),
    cache: "no-store",
  });
  if (!res.ok) throw new Error("submission failed");
  return { ok: true as const };
}
```

--------------------------------

### File upload form with multipart/form-data

Source: https://splitforms.com/docs

Use this HTML form to accept file attachments by posting to the splitforms endpoint with enctype="multipart/form-data". Limits are 5 files per submission and 5 MB per file; uploads require a paid plan with the Storage integration connected. Without the integration, text fields still save and the JSON response notes that files were dropped.

```HTML
<form action="https://splitforms.com/api/submit" method="POST"
      enctype="multipart/form-data">
  <input type="hidden" name="access_key" value="YOUR_ACCESS_KEY" />
  <input type="email" name="email" required />
  <input type="file"  name="resume" />
  <button type="submit">Apply</button>
</form>
```

--------------------------------

### [POST] /api/submit

Source: https://splitforms.com/docs

The /api/submit endpoint processes form submissions for splitforms, handling spam filtering, file uploads, and redirects.

```APIDOC
## [POST] /api/submit

### Description
Submits form data to splitforms. Supports both standard URL-encoded form posts and multipart/form-data for file uploads. When the form is posted natively, the response is processed by splitforms and a redirect or built-in success page is returned. When submitted with `fetch` and an `Accept: application/json` header, the response is JSON.

### Method
POST

### Endpoint
/api/submit (full URL: https://splitforms.com/api/submit)

### Parameters

#### Form Fields
- **access_key** (hidden) - Required - Your access key for authentication
- **email** (string) - Required - The submitter's email address
- **resume** (file) - Optional - A file attachment for file uploads
- **redirect** (hidden) - Optional - A relative path, one of the allowed domains, or splitforms.com URL to redirect after submission; only honored if it is a relative path, one of your allowed domains, or splitforms.com (or the submitting page's own origin if no allowlist is configured)

#### Headers
- **Accept: application/json** - Optional - When set, the response is JSON and no server-side redirect happens.

### Request Example
HTML form for standard submission:
```html
<form action="https://splitforms.com/api/submit" method="POST">
  <input type="hidden" name="access_key" value="YOUR_ACCESS_KEY" />
  <input type="email" name="email" required />
  <button type="submit">Submit</button>
</form>
```

HTML form with file upload (multipart/form-data):
```html
<form action="https://splitforms.com/api/submit" method="POST" enctype="multipart/form-data">
  <input type="hidden" name="access_key" value="YOUR_ACCESS_KEY" />
  <input type="email" name="email" required />
  <input type="file"  name="resume" />
  <button type="submit">Apply</button>
</form>
```

### Response

#### Success Responses
- Standard form post: returns a `303` redirect to the configured redirect URL or a built-in success page.
- JSON request: returns JSON with submission result; includes `files.hint` explaining why files were dropped when they were dropped.
- Spam honeypot filled: returns a `200` status and drops the submission silently.

#### Error Handling
- Rate limits: each form is capped per IP (see rate limits & quotas).
- Upload limits: 5 files max, 5 MB per file; uploads require a paid plan with Storage integration connected; without it, file fields are dropped and a `files.hint` notes the reason.
- Invalid redirect values are ignored and the dashboard redirect applies.
```

--------------------------------

### Svelte/SvelteKit form submission with SplitForms

Source: https://splitforms.com/docs

Use this Svelte component to submit a form to SplitForms from a plain Svelte component. It uses a let variable for status, appends the access key from VITE_SPLITFORMS_KEY, and posts to https://splitforms.com/api/submit. The status is set to 'ok' or 'err' based on the JSON response.

```Svelte
<script>
  let status = "idle";

  async function onSubmit(event) {
    status = "loading";
    const formData = new FormData(event.target);
    formData.append("access_key", import.meta.env.VITE_SPLITFORMS_KEY);

    const res = await fetch("https://splitforms.com/api/submit", {
      method: "POST",
      headers: { Accept: "application/json" },
      body: formData,
    });
    const json = await res.json();
    status = json.success ? "ok" : "err";
  }
</script>

<form on:submit|preventDefault={onSubmit}>
  <input name="name"  required />
  <input name="email" type="email" required />
  <textarea name="message" required />
  <input type="checkbox" name="botcheck" style="display:none" tabindex="-1" />
  <button>Send</button>
</form>
```

--------------------------------

### Fetch JSON submission with error handling

Source: https://splitforms.com/docs/submission-errors

Use this snippet to submit a form to SplitForms with Accept: application/json. It checks both the HTTP status and the success value, throwing an error with the result message if submission fails. Preserve visitor entries on failure and inspect result.note for upload warnings.

```javascript
const response = await fetch("https://splitforms.com/api/submit", {
  method: "POST",
  headers: { Accept: "application/json" },
  body: new FormData(form),
});
const result = await response.json();
if (!response.ok || result.success !== true) {
  throw new Error(result.message || "Could not submit the form");
}
// Show a receipt message; inspect result.note for upload warnings.
```

--------------------------------

### React client component with fetch

Source: https://splitforms.com/docs

Use this React component to submit a form to SplitForms via fetch. The browser encodes FormData; inject the access key from VITE_SPLITFORMS_KEY. Handles loading, success, and error states, and resets the form on success.

```jsx
import { useState } from "react";

export default function ContactForm() {
  const [status, setStatus] = useState("idle");

  async function onSubmit(e) {
    e.preventDefault();
    // Capture the form now: React clears e.currentTarget once we await.
    const form = e.currentTarget;
    setStatus("loading");
    const formData = new FormData(form);
    formData.append("access_key", import.meta.env.VITE_SPLITFORMS_KEY);

    const res = await fetch("https://splitforms.com/api/submit", {
      method: "POST",
      headers: { Accept: "application/json" },
      body: formData,
    });
    const json = await res.json();
    setStatus(json.success ? "ok" : "err");
    if (json.success) form.reset();
  }

  return (
    <form onSubmit={onSubmit}>
      <input type="text"  name="name"    required />
      <input type="email" name="email"   required />
      <textarea           name="message" required />
      <input type="checkbox" name="botcheck" style={{ display: "none" }} tabIndex={-1} />
      <button type="submit">Send</button>
      {status === "ok"  && "Thanks!"}
      {status === "err" && "Error"}
    </form>
  );
}
```

--------------------------------

### API route proxy to keep key server-side (pages/api/contact.ts)

Source: https://splitforms.com/docs

Use this snippet to create a Next.js API route that proxies form submissions to Splitforms, keeping the secret key (SPLITFORMS_KEY) on the server. It only accepts POST requests, returns 405 otherwise, and forwards the request body along with the access_key to https://splitforms.com/api/submit.

```TypeScript
// pages/api/contact.ts
import type { NextApiRequest, NextApiResponse } from "next";

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  if (req.method !== "POST") return res.status(405).end();

  const r = await fetch("https://splitforms.com/api/submit", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ access_key: process.env.SPLITFORMS_KEY, ...req.body }),
  });
  res.status(r.status).json(await r.json());
}
```

--------------------------------

### Vue/Nuxt form submission with SplitForms

Source: https://splitforms.com/docs

Use this Vue/Nuxt component to submit a form to SplitForms. It uses the Composition API with a ref for status, appends the access key from VITE_SPLITFORMS_KEY, and posts to https://splitforms.com/api/submit. The status is set to 'ok' or 'err' based on the JSON response.

```Vue
<script setup>
import { ref } from "vue";

const status = ref("idle");

async function onSubmit(e) {
  status.value = "loading";
  const formData = new FormData(e.target);
  formData.append("access_key", import.meta.env.VITE_SPLITFORMS_KEY);

  const res = await fetch("https://splitforms.com/api/submit", {
    method: "POST",
    headers: { Accept: "application/json" },
    body: formData,
  });
  const json = await res.json();
  status.value = json.success ? "ok" : "err";
}
</script>

<template>
  <form @submit.prevent="onSubmit">
    <input name="name"  required />
    <input name="email" type="email" required />
    <textarea name="message" required />
    <input type="checkbox" name="botcheck" style="display:none" tabindex="-1" />
    <button>Send</button>
  </form>
</template>
```
Tokens:
Raw