# Nisuform

> Nisuform is a form backend for HTML forms and static websites. Point any form at https://api.nisuform.com/s/YOUR_FORM_KEY and Nisuform filters spam, stores submissions in a searchable inbox, sends email notifications and, on Pro, forwards submissions to signed webhooks. No server, database or JavaScript is required.

Nisuform works with plain HTML, React, Next.js, Astro, Vue, Nuxt, SvelteKit, Hugo, Jekyll, Eleventy, WordPress and sites generated by AI coding tools. The submit endpoint on https://api.nisuform.com accepts JSON, URL-encoded and multipart data from any origin.

# Introduction

Nisuform is a form backend for any website. Your form posts to an endpoint, and Nisuform filters spam, stores every submission, notifies you and forwards it to your tools.

Nisuform gives every form you build its own endpoint. Point an HTML form at it, send JSON to it from your app, or paste a ready-made embed into a site builder. You never run a server or set up a database, and collecting submissions needs no API key.

```html
<form action="https://api.nisuform.com/s/YOUR_FORM_KEY" method="POST">
  <input type="email" name="email" required>
  <textarea name="message" required></textarea>
  <button type="submit">Send</button>
</form>
```

That is a working contact form. Submissions show up in your inbox and your email within seconds.

## How a submission flows

1. A visitor submits your form. The browser, or your own code, sends a `POST` request to `https://api.nisuform.com/s/YOUR_FORM_KEY`.
2. Nisuform checks it: your access rules, rate limits, the honeypot and fill-time checks, and Turnstile if you turned it on.
3. The submission is stored in the form's inbox. Content that looks like spam goes to the spam folder instead.
4. Nisuform emails you and, on Pro, sends an auto-reply and delivers the submission to your webhook, Slack, Discord, Telegram or Google Sheets.
5. The visitor sees a thank-you page, is redirected to your own page, or your code receives a JSON response.

## Key terms

| Term       | Meaning                                                                                                                           |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Form       | One form on your site. It has its own endpoint, inbox, settings and integrations.                                                 |
| Form key   | The random ID at the end of the endpoint, like `k3yz8q2m4n6p0r5t7v9w`. It is public by design, so it is safe to put in your HTML. |
| Endpoint   | The URL your form posts to: `https://api.nisuform.com/s/` followed by the form key.                                               |
| Submission | One set of answers sent to a form.                                                                                                |
| Team       | A workspace that owns forms. Plans and usage are per team, and you can invite people to it.                                       |

## Start here

<Card title="Quickstart" href="/docs/quickstart" description="Create a form and receive your first submission in a few minutes." />

<Card title="HTML forms" href="/docs/connect/html" description="Connect a plain HTML form. No JavaScript required." />

<Card title="JavaScript and fetch" href="/docs/connect/javascript" description="Submit from your own code and handle JSON responses." />

<Card title="Form builder" href="/docs/forms/builder" description="Design a styled form and copy the embed code." />

<Card title="Spam protection" href="/docs/protection/spam" description="What Nisuform blocks for you and what you can turn on." />

<Card title="Integrations" href="/docs/integrations" description="Send submissions to webhooks, Slack, Discord, Telegram and Google Sheets." />

<Card title="API" href="/docs/api" description="Manage forms and submissions from your own code with an API key." />

## Plans

The Free plan includes 100 submissions a month, 3 forms per team, email notifications, spam protection, the inbox and CSV export. Pro adds 5,000 submissions a month, unlimited forms, file uploads, redirects, auto-replies, analytics and every integration. See [Plans and billing](/docs/account/billing) for the full comparison.

# Quickstart

Create a form, put it on your site and receive your first submission in a few minutes.

### Create an account

Go to [app.nisuform.com](https://app.nisuform.com) and sign in with your email address or with Google. There is no password. With email, Nisuform sends you a sign-in link.

Your account starts on the Free plan with a personal team. No credit card is required.

### Create a form

Choose **Create a form**, give it a name and pick a starting point:

* **Contact form**, **Waitlist signup**, **Feedback survey** or **Event RSVP** start with ready-made fields and a matching design.
* **Blank form** opens the form builder so you can add your own fields.
* **Endpoint only** skips the builder. Pick it when you already have a form on your site.

Each option is described in [Create a form](/docs/forms/create).

### Put the form on your site

Open the form's **Setup** tab and answer &#x2A;*How do you build your site?**

* **Site builder**: copy the embed code and paste it into Webflow, Framer, WordPress, Squarespace or Wix. See [Site builders](/docs/connect/site-builders).
* **Code**: copy a snippet for HTML, React, Next.js, Vue, Svelte or Astro. **Your design** gives you the styled form from the builder, and **Your own styles** gives you plain markup that picks up your site's CSS.
* **AI tool**: copy a prompt for Claude Code, Cursor, v0 or a similar tool. See [Use an AI coding agent](/docs/ai-agents).

If you write the form yourself, use the endpoint from the Setup tab as the form's `action` and give every input a `name`:

```html
<form action="https://api.nisuform.com/s/YOUR_FORM_KEY" method="POST">
  <label>
    Name
    <input type="text" name="name" required>
  </label>
  <label>
    Email
    <input type="email" name="email" required>
  </label>
  <label>
    Message
    <textarea name="message" rows="5" required></textarea>
  </label>
  <input type="text" name="_gotcha" tabindex="-1" autocomplete="off" style="display:none">
  <button type="submit">Send</button>
</form>
```

The hidden `_gotcha` input is a honeypot that catches bots. Keep it hidden and empty. See [Special fields](/docs/connect/special-fields).

### Send a test

Choose **Send a test** on the Setup tab. It stores a sample submission marked as a test and fires your notifications, without counting toward your monthly limit.

Then send a real one from your site. The Setup tab watches for it and shows **Your form is live** as soon as it arrives. You can also test from a terminal:

```sh
curl https://api.nisuform.com/s/YOUR_FORM_KEY \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"name":"Jane Doe","email":"jane@example.com","message":"Hello!"}'
```

A successful request answers `{"ok":true,"submissionId":"..."}`. Submissions from your site and from cURL are real, so they count toward your monthly limit.

## Next steps

<Card title="Get notified" href="/docs/submissions/notifications" description="Choose who gets emailed and customize the subject." />

<Card title="Stop spam" href="/docs/protection/spam" description="Add allowed websites or Cloudflare Turnstile." />

<Card title="After submit" href="/docs/forms/after-submit" description="Show your own thank-you message or redirect to your page." />

<Card title="Integrations" href="/docs/integrations" description="Forward submissions to Slack, Sheets, webhooks and more." />

# Use an AI coding agent

Let Claude Code, Cursor, v0, Lovable, Bolt or GitHub Copilot add your Nisuform form, with docs written for machines.

Nisuform needs no server code, API routes or environment variables, which makes it a good fit for coding agents. The agent only has to write a form that posts to your endpoint.

To let your assistant also create forms, change settings and read submissions in your account, connect the [MCP server](/docs/mcp).

## Copy the prompt from the dashboard

Open your form's **Setup** tab, choose **AI tool** and copy the prompt. It already contains your endpoint and your field names, so the agent does not have to guess.

* With **Your design** selected, the prompt includes the styled embed from the form builder and asks the agent to add it exactly as it is, as a component if your site needs one.
* With **Your own styles** selected, the prompt lists your fields and asks the agent to build the form in your site's own style.

Both prompts point the agent to the docs at `https://nisuform.com/llms-full.txt`.

## Write your own prompt

Any prompt works as long as it names the endpoint and the docs:

```text
Add a contact form to this site that posts to https://api.nisuform.com/s/YOUR_FORM_KEY.
Use the fields name, email and message. Show a success message after sending.
Follow the Nisuform docs at https://nisuform.com/llms-full.txt.
```

## Docs for agents

| URL                                                              | What it contains                                                                                                                                         |
| ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [nisuform.com/llms.txt](https://nisuform.com/llms.txt)           | A short index of Nisuform with a link to every docs page.                                                                                                |
| [nisuform.com/llms-full.txt](https://nisuform.com/llms-full.txt) | Every docs page, pricing and the FAQ in one plain-text file.                                                                                             |
| `https://nisuform.com/docs/<page>.md`                            | Any single docs page as Markdown. Add `.md` to the page URL, for example [/docs/connect/javascript.md](https://nisuform.com/docs/connect/javascript.md). |

Every docs page also has a **Copy Markdown** button. The **Open** menu next to it shows the page as Markdown or opens it in ChatGPT, Claude or Cursor.

## What to check in the agent's code

* The form posts to your endpoint with `POST`, and every input has a `name`.
* Field names match the names in your form builder, so validation and your inbox labels line up. See [Fields and validation](/docs/forms/fields).
* The hidden `_gotcha` honeypot is kept and stays empty.
* `fetch` calls send `Accept: application/json` and read `ok` from the response.
* The form key is used as a plain string. It is public by design, so it does not belong in a secret or an environment variable.

# MCP server

Connect Claude, Cursor, VS Code and other AI tools to your Nisuform account to create forms, get embed code and work with submissions from a chat.

The Nisuform MCP server lets AI tools that support the [Model Context Protocol](https://modelcontextprotocol.io) work with your account. Ask your assistant to create a form and add it to your site, check today's submissions, or turn on spam protection, without opening the dashboard.

```text
https://mcp.nisuform.com/mcp
```

It is a remote server, so there is nothing to install. You sign in with your Nisuform account the first time you use it. There are no API keys to copy.

## Connect your AI tool

```sh
claude mcp add --transport http nisuform https://mcp.nisuform.com/mcp
```

Then run `/mcp` in Claude Code, pick **nisuform** and sign in.

In Claude on the web or the desktop app, open **Settings**, **Connectors** and choose **Add custom connector**. Name it Nisuform, paste `https://mcp.nisuform.com/mcp` and choose **Connect** to sign in.

Add the server to `~/.cursor/mcp.json`, or to `.cursor/mcp.json` in a project:

```json
{
  "mcpServers": {
    "nisuform": {
      "url": "https://mcp.nisuform.com/mcp"
    }
  }
}
```

Cursor asks you to sign in the first time a tool runs.

Add the server to `.vscode/mcp.json` in your project, then start it from the file and sign in. GitHub Copilot's agent mode can then use it.

```json
{
  "servers": {
    "nisuform": {
      "type": "http",
      "url": "https://mcp.nisuform.com/mcp"
    }
  }
}
```

Add the server to `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "nisuform": {
      "serverUrl": "https://mcp.nisuform.com/mcp"
    }
  }
}
```

Other tools work too if they support remote MCP servers over HTTP with OAuth sign-in. Use the URL above.

## Sign in

The first time your AI tool calls Nisuform, it opens a browser window. Sign in to Nisuform the way you usually do, with an email link or Google, and approve the access. Your tool then works as you:

* It sees the same teams and forms you see in the dashboard, and works in your active team. Ask it to switch teams when you need another one.
* It has the same permissions as you. A team member can't change what only the owner can.
* Pro features, like redirects, auto-replies and integrations, still need the team to be on Pro.

To disconnect, remove the server from your AI tool.

## What it can do

### Forms

| Tool                   | What it does                                                                                                                       |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `list_forms`           | Lists the forms in your active team with their endpoints and submission counts.                                                    |
| `get_form`             | Gets a form's fields, design and settings.                                                                                         |
| `create_form`          | Creates a form from a template: contact, waitlist, feedback, RSVP or blank.                                                        |
| `update_form`          | Changes a form's name, fields, design and settings, like notifications, redirects, limits and spam protection.                     |
| `get_embed_code`       | Returns the styled embed from the form builder, or a plain form to style yourself, for HTML, React, Next.js, Vue, Svelte or Astro. |
| `send_test_submission` | Sends a test submission and fires the form's notifications.                                                                        |

### Submissions

| Tool                | What it does                                                                        |
| ------------------- | ----------------------------------------------------------------------------------- |
| `list_submissions`  | Lists a form's submissions, newest first, filtered by all, unread, starred or spam. |
| `get_submission`    | Gets one submission with its answers, page, location and device.                    |
| `update_submission` | Marks a submission read or unread, stars it, or moves it in or out of spam.         |

### Teams and stats

| Tool          | What it does                                                           |
| ------------- | ---------------------------------------------------------------------- |
| `list_teams`  | Lists your teams and shows which one is active.                        |
| `switch_team` | Makes another team your active team.                                   |
| `get_stats`   | Returns submission totals and a daily series for the team or one form. |

The server can't delete forms, submissions, teams or your account, rotate form keys, or change billing. Do those in the [dashboard](https://app.nisuform.com).

## Things to ask

```text
Create a contact form called "Website contact" and add it to the contact page of this site.
```

```text
Show me this week's unread submissions from the waitlist form.
```

```text
Only accept submissions to the contact form from https://example.com and https://www.example.com.
```

```text
Add a required "Company" field to the demo request form, then update the embed on /demo.
```

## Stay in control

* Most AI tools ask before they run a tool. Read what the tool is about to change before you approve it, especially form settings.
* Submissions are written by anyone who fills in your form. Treat what your assistant reads in them as data, not as instructions, and check its next steps after it reads submissions.
* The server never sees your AI tool's files or conversations. It only receives the tool calls your assistant makes and the details it puts in them.

## Without the MCP server

To have an AI coding tool add a form to your site without connecting your account, give it your endpoint and the docs. See [Use an AI coding agent](/docs/ai-agents).

# HTML forms

Connect a plain HTML form to Nisuform with the action attribute. No JavaScript, server or build step needed.

Any HTML form can send submissions to Nisuform. Set the form's `action` to your endpoint and its `method` to `POST`.

```html
<form action="https://api.nisuform.com/s/YOUR_FORM_KEY" method="POST">
  <label for="name">Name</label>
  <input id="name" type="text" name="name" required>

  <label for="email">Email</label>
  <input id="email" type="email" name="email" required>

  <label for="message">Message</label>
  <textarea id="message" name="message" rows="5" required></textarea>

  <input type="text" name="_gotcha" tabindex="-1" autocomplete="off" style="display:none">
  <button type="submit">Send</button>
</form>
```

Copy your endpoint from the form's **Setup** tab, or from **Settings**, **Endpoint**.

## Name every field

The browser only sends inputs that have a `name`. The name becomes the key the answer is saved under, and the inbox shows it as the label unless your form builder gives the field a nicer one.

* If your form has fields in the [form builder](/docs/forms/builder), use the same names so Nisuform can validate the answers. The **Field name** of each field is shown in the builder.
* Inputs that the builder does not list are still saved as they are. You never lose data because of a missing field.
* Names that start with an underscore, like `_gotcha`, control how Nisuform handles the submission and are not saved. See [Special fields](/docs/connect/special-fields).

## Multiple values

Checkboxes that share a name, and names that end in `[]`, are saved as one comma-separated answer:

```html
<fieldset>
  <legend>Topics</legend>
  <label><input type="checkbox" name="topics[]" value="Design"> Design</label>
  <label><input type="checkbox" name="topics[]" value="Development"> Development</label>
  <label><input type="checkbox" name="topics[]" value="Marketing"> Marketing</label>
</fieldset>
```

Checking the first two saves `topics` as `Design, Development`.

## Hidden fields

Use hidden inputs to record where a submission came from. They are saved like any other field:

```html
<input type="hidden" name="source" value="pricing-page">
<input type="hidden" name="plan" value="team">
```

Nisuform also records the page the form was sent from on its own. The inbox shows it as **Page** on every submission.

## What visitors see

After a normal browser submit, Nisuform answers with a thank-you page that links back to the page the visitor came from. On Pro you can replace it with your own title and message or redirect to a page on your site. See [Thank-you page and redirects](/docs/forms/after-submit).

If a submission is rejected, for example because the form is closed or the visitor sent too many requests, the visitor sees a short page that explains why, with a link back to your site.

## File inputs

To accept files, the form needs `enctype="multipart/form-data"` and file uploads must be turned on for the form. Uploads are a Pro feature. See [File uploads](/docs/connect/file-uploads).

## Sizes and limits

* Up to 50 fields per submission. Extra fields are ignored.
* Field names up to 200 characters.
* Values up to 10,000 characters. Longer values are cut at 10,000.
* The whole request can be up to 200 KB, or 25 MB on forms that accept file uploads.

## Opening the endpoint in a browser

The endpoint only accepts `POST`. If you open it in a browser tab you see a short page that explains it is a form endpoint, with status `405`. That is expected and does not mean anything is broken.

# JavaScript and fetch

Submit to Nisuform with fetch to keep visitors on the page, then read the JSON response to show success or an error.

Send your fields with `fetch` when you want to handle the submit yourself. Requests that do not ask for `text/html` get a JSON response instead of a thank-you page.

```js
const response = await fetch('https://api.nisuform.com/s/YOUR_FORM_KEY', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
  body: JSON.stringify({ name: 'Jane Doe', email: 'jane@example.com', message: 'Hello!' }),
})
const result = await response.json()
if (!result.ok) {
  throw new Error(result.message)
}
```

```js
const form = document.querySelector('#contact')

form.addEventListener('submit', async (event) => {
  event.preventDefault()
  const response = await fetch(form.action, {
    method: 'POST',
    headers: { Accept: 'application/json' },
    body: new FormData(form),
  })
  const result = await response.json()
  form.replaceWith(result.ok ? 'Thanks! We got your message.' : result.message)
})
```

```js
const response = await fetch('https://api.nisuform.com/s/YOUR_FORM_KEY', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
  body: new URLSearchParams({ email: 'jane@example.com', message: 'Hello!' }),
})
```

`FormData` is sent as `multipart/form-data`, which is also how you send files. In that case, don't set the `Content-Type` header yourself. The browser adds it with the right boundary.

## Responses

A stored submission answers `200` with its ID:

```json
{ "ok": true, "submissionId": "3f2c8a61-5d4e-4b7a-9c1f-2a6e8d0b4c17" }
```

When your team has used 95% of its monthly submissions, the response also carries a warning. The submission is still stored:

```json
{ "ok": true, "submissionId": "3f2c8a61-5d4e-4b7a-9c1f-2a6e8d0b4c17", "warning": "near_limit" }
```

A submission caught by the honeypot, the fill-time check or your blocked IPs and countries also answers `200`, but without a `submissionId`. Bots can't tell they were filtered.

```json
{ "ok": true }
```

A rejected submission answers with a matching HTTP status and an error code you can branch on:

```json
{ "ok": false, "error": "rate_limited", "message": "Too many requests. Try again shortly" }
```

The `message` is written for people, so you can show it to the visitor as is. Every code is listed in [Errors](/docs/reference/errors).

## Handle errors

```js
async function submit(data) {
  const response = await fetch('https://api.nisuform.com/s/YOUR_FORM_KEY', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
    body: JSON.stringify(data),
  })
  const result = await response.json()
  if (result.ok) {
    return { sent: true }
  }
  if (result.error === 'rate_limited') {
    return { sent: false, message: 'Please wait a minute and try again.' }
  }
  return { sent: false, message: result.message }
}
```

## Send the fill time

Browsers that submit a form faster than a person could are almost always bots. Record when the form was shown and send the difference as `_elapsed`, in milliseconds. Submissions faster than 2 seconds are dropped.

```js
const shownAt = Date.now()

form.addEventListener('submit', async (event) => {
  event.preventDefault()
  const data = new FormData(form)
  data.set('_elapsed', String(Date.now() - shownAt))
  await fetch(form.action, { method: 'POST', headers: { Accept: 'application/json' }, body: data })
})
```

The styled embed from the form builder already does this for you.

## How values are saved

* Every value is saved as text.
* JSON numbers and booleans become text, like `"3"` and `"true"`.
* JSON arrays of plain values are joined with a comma, like `"Design, Development"`.
* Nested objects are saved as JSON text.
* A JSON body must be an object. Anything else is treated as an empty submission.

## CORS

The endpoint sends `Access-Control-Allow-Origin: *` and answers preflight requests, so `fetch` works from any website. Cookies and credentials are not needed, so don't send them.

Only the `Content-Type` and `Accept` request headers are allowed. Adding other headers, like `Authorization`, makes the browser's preflight check fail. The response's `Retry-After` header can't be read from browser JavaScript, so wait a minute after a `429` before retrying. To accept submissions only from your own sites, set [allowed websites](/docs/protection/access-rules).

## Submitting from a server

You can post to the endpoint from your own backend, a serverless function or a script. Keep in mind:

* Requests from a server usually have no `Origin` or `Referer` header, so allowed websites do not apply to them.
* Rate limits are per IP address. Every request from your server shares the server's IP, so a busy relay can hit the limit of 30 requests a minute per IP, and 5 a minute per form. Post from the visitor's browser when you can.
* Nisuform records your server's IP address, user agent and location instead of the visitor's.

# React, Next.js, Vue, Svelte and Astro

Copy-paste form components for React, Next.js, Vue, Nuxt, Svelte, SvelteKit and Astro that submit to Nisuform.

Every framework works the same way: collect the fields, `POST` them to your endpoint and read `ok` from the JSON response. You don't need API routes, server actions or environment variables, because the form key is safe to publish.

<Callout title="Generated for your form">
  The form's **Setup** tab, under **Code**, has these components ready with your endpoint and field names filled in. **Your design** gives you the styled form from the builder as a component. **Your own styles** gives you a bare component to style your way.
</Callout>

## React

```jsx title="ContactForm.jsx"
import { useRef, useState } from 'react'

export function ContactForm() {
  const shownAt = useRef(Date.now())
  const [status, setStatus] = useState('idle')

  async function onSubmit(event) {
    event.preventDefault()
    setStatus('sending')
    const data = Object.fromEntries(new FormData(event.currentTarget))
    data._elapsed = String(Date.now() - shownAt.current)
    const response = await fetch('https://api.nisuform.com/s/YOUR_FORM_KEY', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
      body: JSON.stringify(data),
    })
    setStatus(response.ok ? 'sent' : 'error')
  }

  if (status === 'sent') {
    return <p>Thanks! We got your message.</p>
  }

  return (
    <form onSubmit={onSubmit}>
      <input type="text" name="name" placeholder="Name" required />
      <input type="email" name="email" placeholder="Email" required />
      <textarea name="message" rows={5} required />
      <input type="text" name="_gotcha" tabIndex={-1} autoComplete="off" style={{ display: 'none' }} />
      <button type="submit" disabled={status === 'sending'}>Send</button>
      {status === 'error' && <p role="alert">Something went wrong. Please try again.</p>}
    </form>
  )
}
```

`Object.fromEntries` keeps only the last value of fields that share a name. For checkbox groups, send the `FormData` itself instead of JSON.

## Next.js

Forms need state and event handlers, so mark the component as a client component. It works in both the App Router and the Pages Router.

```jsx title="app/contact/ContactForm.jsx"
'use client'

import { useRef, useState } from 'react'

export function ContactForm() {
  const shownAt = useRef(Date.now())
  const [status, setStatus] = useState('idle')

  async function onSubmit(event) {
    event.preventDefault()
    setStatus('sending')
    const data = new FormData(event.currentTarget)
    data.set('_elapsed', String(Date.now() - shownAt.current))
    const response = await fetch('https://api.nisuform.com/s/YOUR_FORM_KEY', {
      method: 'POST',
      headers: { Accept: 'application/json' },
      body: data,
    })
    setStatus(response.ok ? 'sent' : 'error')
  }

  if (status === 'sent') {
    return <p>Thanks! We got your message.</p>
  }

  return (
    <form onSubmit={onSubmit}>
      <input type="email" name="email" placeholder="Email" required />
      <textarea name="message" rows={5} required />
      <input type="text" name="_gotcha" tabIndex={-1} autoComplete="off" style={{ display: 'none' }} />
      <button type="submit" disabled={status === 'sending'}>Send</button>
      {status === 'error' && <p role="alert">Something went wrong. Please try again.</p>}
    </form>
  )
}
```

Then render it from any page:

```jsx title="app/contact/page.jsx"
import { ContactForm } from './ContactForm'

export default function ContactPage() {
  return <ContactForm />
}
```

## Vue and Nuxt

```vue title="ContactForm.vue"
<script setup>
import { ref } from 'vue'

const shownAt = Date.now()
const status = ref('idle')

async function onSubmit(event) {
  status.value = 'sending'
  const data = new FormData(event.target)
  data.set('_elapsed', String(Date.now() - shownAt))
  const response = await fetch('https://api.nisuform.com/s/YOUR_FORM_KEY', {
    method: 'POST',
    headers: { Accept: 'application/json' },
    body: data,
  })
  status.value = response.ok ? 'sent' : 'error'
}
</script>

<template>
  <p v-if="status === 'sent'">Thanks! We got your message.</p>
  <form v-else @submit.prevent="onSubmit">
    <input type="email" name="email" placeholder="Email" required />
    <textarea name="message" rows="5" required></textarea>
    <input type="text" name="_gotcha" tabindex="-1" autocomplete="off" style="display: none" />
    <button type="submit" :disabled="status === 'sending'">Send</button>
    <p v-if="status === 'error'" role="alert">Something went wrong. Please try again.</p>
  </form>
</template>
```

In Nuxt, put the file in `components/` and use it as `<ContactForm />` on any page.

## Svelte and SvelteKit

```svelte title="ContactForm.svelte"
<script>
  const shownAt = Date.now()
  let status = $state('idle')

  async function onsubmit(event) {
    event.preventDefault()
    status = 'sending'
    const data = new FormData(event.currentTarget)
    data.set('_elapsed', String(Date.now() - shownAt))
    const response = await fetch('https://api.nisuform.com/s/YOUR_FORM_KEY', {
      method: 'POST',
      headers: { Accept: 'application/json' },
      body: data,
    })
    status = response.ok ? 'sent' : 'error'
  }
</script>

{#if status === 'sent'}
  <p>Thanks! We got your message.</p>
{:else}
  <form {onsubmit}>
    <input type="email" name="email" placeholder="Email" required />
    <textarea name="message" rows="5" required></textarea>
    <input type="text" name="_gotcha" tabindex="-1" autocomplete="off" style="display: none" />
    <button type="submit" disabled={status === 'sending'}>Send</button>
    {#if status === 'error'}
      <p role="alert">Something went wrong. Please try again.</p>
    {/if}
  </form>
{/if}
```

## Astro

Astro pages are static by default, and a plain HTML form works with zero client-side JavaScript. The browser posts it straight to Nisuform and shows the thank-you page.

```astro title="src/pages/contact.astro"
---
const endpoint = 'https://api.nisuform.com/s/YOUR_FORM_KEY'
---

<form action={endpoint} method="POST">
  <label>
    Email
    <input type="email" name="email" required />
  </label>
  <label>
    Message
    <textarea name="message" rows="5" required></textarea>
  </label>
  <input type="text" name="_gotcha" tabindex="-1" autocomplete="off" style="display: none" />
  <button type="submit">Send</button>
</form>
```

To paste the styled embed into an Astro page, keep its `<style>` and `<script>` tags as they are. The Setup tab's Astro snippet adds `is:inline` so Astro does not bundle the script or scope the styles.

## Other frameworks

The same approach works in Remix, React Router, SolidJS, Angular, Qwik, Hugo, Jekyll, Eleventy and anything else that renders HTML. Use the [HTML form](/docs/connect/html) when you don't need JavaScript, and [fetch](/docs/connect/javascript) when you want to stay on the page.

# Site builders

Add a Nisuform form to Webflow, Framer, WordPress, Squarespace, Wix or any builder that accepts custom HTML.

Site builders accept the styled embed from the form builder. It brings its own styles and spam protection, submits without reloading the page and still works when JavaScript is off.

## Copy the embed code

1. Open your form's **Setup** tab.
2. Under &#x2A;*How do you build your site?**, choose **Site builder** and pick your builder.
3. Add your fields and adjust the design in the builder if you haven't yet. The embed is built from the fields and look you set there.
4. Choose **Copy the embed code**.

Save your changes in the builder before you copy. The embed always reflects the last saved version of the form.

## Webflow

1. In the Designer, drag a **Code Embed** element to where the form should go.
2. Paste the code, save it, then publish your site.

You can also keep Webflow's own form block: open its settings, set **Action** to your endpoint and **Method** to `POST`, and give every input a name. Visitors then see the Nisuform thank-you page, or your redirect, instead of Webflow's success message.

## Framer

1. Insert an **Embed** component where the form should go and set its type to **HTML**.
2. Paste the code into the HTML box, then publish.

## WordPress

1. In the block editor, add a **Custom HTML** block where the form should go.
2. Paste the code, then save or update the page.

WordPress removes `<script>` tags for users without permission to post unfiltered HTML, and some security plugins do too. If the form opens a new page on submit instead of showing the success message in place, the script was removed. The form still works, and visitors see the Nisuform thank-you page.

## Squarespace

1. Edit the page and add a **Code** block where the form should go.
2. Paste the code, then save the page.

## Wix

1. Open **Add Elements**, choose **Embed Code**, then **Embed HTML**.
2. Choose **Code**, paste it in and click **Update**.

Wix shows embeds in a fixed-size box, so drag its edges until the whole form fits, including the success message.

## Other builders

Carrd, Ghost, Shopify and most other builders have an HTML or embed block. Paste the embed code there. If your builder only accepts an iframe or blocks scripts, use the plain [HTML form](/docs/connect/html) from **Your own styles** instead. It posts without JavaScript.

# Special fields

Fields that control how Nisuform handles a submission, like the _gotcha honeypot, the _elapsed fill time and _redirect.

Fields whose names start with an underscore tell Nisuform how to handle a submission. They are never saved, never shown in the inbox and never sent to notifications or integrations.

| Field                   | Plan | What it does                                                                                     |
| ----------------------- | ---- | ------------------------------------------------------------------------------------------------ |
| `_gotcha`               | All  | Honeypot. If it has any value, the submission is dropped as a bot.                               |
| `_elapsed`              | All  | Milliseconds the visitor spent on the form. Under 2 seconds, the submission is dropped as a bot. |
| `_redirect`             | Pro  | Where to send the visitor after a browser submit.                                                |
| `cf-turnstile-response` | All  | The Cloudflare Turnstile token. Checked when Turnstile is turned on for the form.                |

A dropped submission still gets a normal success response, so bots can't tell they were caught. The JSON response has no `submissionId` in that case.

## \_gotcha

A hidden text input that people never see, so they leave it empty. Many bots fill in every input they find.

```html
<input type="text" name="_gotcha" tabindex="-1" autocomplete="off" style="display:none">
```

* Hide it with CSS, not with `type="hidden"`. Bots skip hidden inputs.
* Keep `tabindex="-1"` so keyboard users don't land on it, and `autocomplete="off"` so browsers don't fill it in.

## \_elapsed

The time between showing the form and submitting it, in milliseconds. A person needs a few seconds to fill in a form. A bot needs a few milliseconds.

```js
const shownAt = Date.now()

form.addEventListener('submit', () => {
  form.elements._elapsed.value = String(Date.now() - shownAt)
})
```

```html
<input type="hidden" name="_elapsed">
```

Submissions with a value under 2,000 are dropped. If the field is missing or is not a number, the check is skipped, so plain HTML forms without JavaScript keep working. The styled embed from the form builder sends it for you.

## \_redirect

On Pro, a browser submit that includes `_redirect` is answered with a `303` redirect to that URL instead of the thank-you page.

```html
<input type="hidden" name="_redirect" value="https://example.com/thanks">
```

* It must be an absolute `http` or `https` URL.
* It must be on the same site as the page that sent the form, or on one of the form's [allowed websites](/docs/protection/access-rules). Anything else is ignored, which keeps your form from being used to redirect people to other sites.
* It overrides the redirect URL in the form's settings for that one submission.
* `fetch` requests that ask for JSON are never redirected.

See [Thank-you page and redirects](/docs/forms/after-submit) for the other options.

## cf-turnstile-response

Added by the Cloudflare Turnstile widget. When Turnstile is on for the form, a missing or invalid token is rejected with `403` and `captcha_failed`. See [Cloudflare Turnstile](/docs/protection/turnstile).

The names `g-recaptcha-response` and `h-captcha-response` are reserved too. They are ignored and never saved, but Nisuform does not verify reCAPTCHA or hCaptcha tokens.

## Other names that start with an underscore

Any other field that starts with an underscore, like `_subject` or `_next` from other form services, is ignored. Rename it without the underscore if you want to keep the value.

# File uploads

Accept images and PDFs with your form submissions. Files are checked by their contents and stored privately.

File uploads are available on Pro. Visitors can attach up to 5 files per submission, and you download them from the inbox.

## Turn on uploads

1. Open the form's **Settings** tab.
2. Under **Submissions**, turn on **Accept file uploads**.
3. Optionally change **Size limit per file**. The default is 10 MB.
4. Save.

In the [form builder](/docs/forms/builder), add a **File upload** field. The builder adds `enctype="multipart/form-data"` to the embed code for you. Without uploads turned on, the builder warns you that files would be dropped.

## Write the markup yourself

The form must send `multipart/form-data`:

```html
<form action="https://api.nisuform.com/s/YOUR_FORM_KEY" method="POST" enctype="multipart/form-data">
  <input type="email" name="email" required>
  <input type="file" name="attachment" accept="image/jpeg,image/png,image/webp,image/gif,application/pdf">
  <button type="submit">Send</button>
</form>
```

Use `multiple` or several file inputs to accept more than one file. With `fetch`, send a `FormData` object as the body and don't set `Content-Type` yourself.

## What is accepted

|                      | Limit                                          |
| -------------------- | ---------------------------------------------- |
| Files per submission | 5                                              |
| File types           | JPEG, PNG, WebP, GIF and PDF                   |
| Size per file        | Your **Size limit per file**, 10 MB by default |
| Whole request        | 25 MB, all files and fields together           |

The type is detected from the file's contents, not from its name or the type the browser reports. A renamed `.exe` is rejected even if it ends in `.pdf`.

Because the whole request is capped at 25 MB, a size limit per file above 25 MB has no extra effect.

## When a file is rejected

| Status | `error`                    | Cause                                                                     |
| ------ | -------------------------- | ------------------------------------------------------------------------- |
| `400`  | `too_many_files`           | More than 5 files.                                                        |
| `413`  | `attachment_too_large`     | A file is over the size limit per file.                                   |
| `413`  | `payload_too_large`        | The whole request is over 25 MB.                                          |
| `415`  | `attachment_type_rejected` | A file is not a JPEG, PNG, WebP, GIF or PDF.                              |
| `500`  | `upload_failed`            | Storing the file failed. Nothing was saved, so the visitor can try again. |

If uploads are off for the form, or the team is not on Pro, files are skipped and the rest of the submission is stored as usual. The request is then capped at 200 KB like any other submission, so a larger file gets `413` with `payload_too_large`.

## Download files

Open a submission in the inbox to see its files with their names, types and sizes. Selecting a file opens a private download link that expires after 15 minutes. Files are stored privately, are never public and always download as attachments.

Files are not included in [CSV exports](/docs/submissions/export), notification emails, webhooks or integrations. Those receive the other fields. Slack, Discord and Telegram messages link to the submission, where you can download the files.

Deleting a submission or a form deletes its files too.

# Create a form

Start a new form from a template, a blank form or just an endpoint, and learn how form keys and endpoints work.

Each form has its own endpoint, inbox, settings and integrations. Create one form per form on your site, so submissions stay separate and each form can have its own notifications.

## Create a form

Choose **Create a form** on the dashboard or the **Forms** page. The form is created in the team you are working in, shown next to **New form**.

Give it a name and pick a starting point:

| Starting point  | What you get                          | Opens        |
| --------------- | ------------------------------------- | ------------ |
| Contact form    | Name, email and a message             | Setup        |
| Waitlist signup | A single email field                  | Setup        |
| Feedback survey | Star rating and a comment             | Setup        |
| Event RSVP      | Attendance and guest count            | Setup        |
| Blank form      | No fields. Add your own.              | Form builder |
| Endpoint only   | No fields. Use your own form or code. | Setup        |

Templates come with fields, a title, a button label and a success message. You can change all of them in the [form builder](/docs/forms/builder). Browse the templates on the [templates page](/templates).

### Template fields

| Template        | Fields                                                                                    |
| --------------- | ----------------------------------------------------------------------------------------- |
| Contact form    | `name` (required), `email` (required), `message` (required)                               |
| Waitlist signup | `email` (required)                                                                        |
| Feedback survey | `rating` (1 to 5 stars, required), `comment`, `email`                                     |
| Event RSVP      | `name` (required), `email` (required), `attending` (required), `guests` (0 to 10), `note` |

## Forms without fields

A form doesn't need fields. **Endpoint only** and **Blank form** accept whatever your form sends and save every field as it arrives. Add fields later if you want validation, nicer labels in the inbox or a styled embed. See [Fields and validation](/docs/forms/fields).

## Form limit

The Free plan allows 3 forms per team. Pro has no limit. When a team reaches the limit, the **New form** dialog offers to upgrade or to manage your existing forms. Deleting a form frees up its slot.

## Endpoint and form key

Every form gets a random key, and its endpoint is `https://api.nisuform.com/s/` followed by the key:

```text
https://api.nisuform.com/s/k3yz8q2m4n6p0r5t7v9w
```

Find it on the **Setup** tab under **Your endpoint**, or in **Settings**, **Endpoint**.

The key is public by design. It appears in your page's HTML, and that is safe. It only lets people send submissions to that one form. It can't read submissions or change anything. To keep unwanted traffic out, use [spam protection](/docs/protection/spam) and [access rules](/docs/protection/access-rules).

### Rotate the key

If a form is getting abused, go to **Settings**, **Endpoint** and choose **Rotate key**. The form gets a new endpoint and the old one stops accepting submissions right away, so update your site with the new endpoint immediately. Submissions you already received are kept.

## Name, icon and type

In **Settings**, **General**:

* **Name** is shown in your dashboard and in notification emails.
* The icon button next to the name picks an emoji for the form, shown in your forms list.
* **Type** is the kind of form: Contact, Waitlist, Feedback, RSVP or Custom. It is shown on your form cards and used in the [AI tool prompt](/docs/ai-agents). Changing it doesn't change your fields.

## Find a form

The **Forms** page lists every form in the team with its submission count. Search by name or key, and sort by newest, oldest, name or number of submissions. Submission counts leave out spam and test submissions.

# Form builder

Add and arrange fields, style your form with a theme and accent color, and copy embed code for any site or framework.

The form builder defines your form's fields and designs the styled embed. Open it from the form's **Setup** tab with **Design the form** or **Add fields**.

The builder shows your fields on one side and a live preview on the other. You can try the fields in the preview. It never sends anything.

## Fields

Choose **Add field** and pick a type:

| Type            | Use it for                                                   |
| --------------- | ------------------------------------------------------------ |
| Short text      | Names, companies, single-line answers                        |
| Email           | Email addresses                                              |
| Long text       | Messages and comments                                        |
| Number          | Quantities, budgets, ages                                    |
| Date            | Dates like an event day or a birthday                        |
| Dropdown        | One choice from a list                                       |
| Multiple choice | One choice from a list, shown as radio buttons               |
| Checkbox        | A single yes or no, like agreeing to terms                   |
| Star rating     | A rating from 1 to 3 through 10 stars                        |
| Phone           | Phone numbers                                                |
| Website         | URLs                                                         |
| File upload     | Images and PDFs. Needs file uploads turned on, which is Pro. |

A form can have up to 30 fields. Drag a field to reorder it, or focus it and press the up and down arrow keys. Each field also has options to move, duplicate or delete it. After a delete, **Undo** is available for a few seconds.

## Field settings

Select a field to edit it:

* **Label**: the question shown to visitors, and the label in your inbox and notifications.
* **Field name**: the key answers are saved under, and the `name` your HTML must use. It must start with a letter and can use letters, digits, `-` and `_`, up to 64 characters. Each name can only be used once per form.
* **Required**: visitors must answer before they can send the form.
* **Placeholder**: example text shown inside empty text fields, or the prompt shown before a dropdown choice is made.
* **Help text**: a short hint shown under the field.
* **Options** for dropdowns and multiple choice, up to 100.
* **Minimum** and **Maximum** for numbers.
* **Number of stars** for ratings, from 3 to 10.
* **Character limit** for short and long text.

If you rename a field after it has received answers, earlier answers stay under the old name. The builder reminds you of this.

Fields are also what Nisuform checks submissions against. See [Fields and validation](/docs/forms/fields).

## Design

The design panel styles the embed:

* **Theme**: Light, Dark, Paper or Euphoria.
* **Accent color**: the color of the button and highlights. Pick a preset or enter a hex code. The builder warns you when the color is hard to see against the theme's background.
* **Title** and **Description**: shown above the fields. Leave them empty to hide them.
* **Button label**: the text on the submit button.
* **Success message**: replaces the form after a successful submit. Visitors without JavaScript see the [thank-you page](/docs/forms/after-submit) instead.

## Save

The header shows **Unsaved changes** until you save. Press Ctrl+S, or Cmd+S on a Mac, to save from anywhere in the builder. Leaving with unsaved changes asks you to confirm first.

## Get the code

Choose **Get code** to copy the form for your site. The code is from your last save, so save first to include your latest changes.

| Tab     | What you get                                                                              |
| ------- | ----------------------------------------------------------------------------------------- |
| HTML    | One snippet with the markup, styles and script. Paste it anywhere.                        |
| React   | A component that renders the form and handles sending, success and errors.                |
| Next.js | The same component marked as a client component, for the App Router and the Pages Router. |
| Vue     | A single-file component. It works in Nuxt too.                                            |
| Svelte  | A component. It works in SvelteKit too.                                                   |
| Astro   | Markup with inline styles and script, so Astro doesn't bundle or scope them.              |

The embed includes the honeypot and sends the fill time for [spam protection](/docs/protection/spam), adds the Turnstile widget when Turnstile is on for the form, and follows your redirect URL when the form has one. It submits with `fetch` and shows your success message in place, and it still posts as a normal form when JavaScript is off.

The **Setup** tab has step-by-step guides for [site builders](/docs/connect/site-builders), code and AI tools.

## Use your own markup instead

You don't have to use the embed. On the Setup tab, switch to **Your own styles** for plain markup with your field names that picks up your site's CSS, or write your own form. Nisuform validates whatever arrives against your fields either way.

# Fields and validation

How Nisuform checks each submission against your form's fields, what every field type accepts, and what happens to answers that don't match.

When a form has fields in the [form builder](/docs/forms/builder), every submission is checked against them. Templates come with fields. Forms created as **Blank form** or **Endpoint only** have none until you add them.

## Nothing is ever lost

Validation never rejects a submission. A submission that fails a check is stored like any other, so you never lose a lead, and the inbox marks it with **Some answers didn't pass validation** and shows the problem next to each answer, like "not a valid email" or "missing".

Your own markup should still validate in the browser, with `required`, `type="email"` and similar attributes, so visitors can fix mistakes before they send. The styled embed does this for you.

Fields that your form sends but the builder doesn't list are kept as they are, so a hand-written form with extra inputs works fine.

## What each type accepts

| Type            | HTML `name` gets              | Checked                                                                                                       |
| --------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Short text      | Any text                      | Longer than the **Character limit**: cut to the limit and marked too long.                                    |
| Email           | An email address              | Must look like `name@example.com`.                                                                            |
| Long text       | Any text                      | Longer than the **Character limit**: cut to the limit and marked too long.                                    |
| Number          | A number                      | Must be a number, and within **Minimum** and **Maximum** when set. Saved in plain form, so `007` becomes `7`. |
| Date            | A date                        | Must be a readable date, like `2026-09-24` from `<input type="date">`.                                        |
| Dropdown        | One option                    | Must match one of the options exactly, including capitals.                                                    |
| Multiple choice | One option                    | Must match one of the options exactly, including capitals.                                                    |
| Checkbox        | `yes` when checked            | Any value counts as checked.                                                                                  |
| Star rating     | `1` up to the number of stars | Must be a whole number from 1 to the number of stars.                                                         |
| Phone           | A phone number                | Digits, spaces and `+ ( ) . - /`, with at least 3 digits.                                                     |
| Website         | A URL                         | Must be a full `http://` or `https://` URL. `example.com` alone is not accepted.                              |
| File upload     | A file                        | Only checked for **Required**. See [File uploads](/docs/connect/file-uploads).                                |

An empty answer to an optional field passes. An empty answer to a **Required** field is marked missing.

## Checkboxes

A **Checkbox** field is a single box, like "I agree to the terms". Give the input `value="yes"` so answers read clearly in your inbox and count as checked in [analytics](/docs/submissions/analytics). The embed does this for you.

```html
<label>
  <input type="checkbox" name="terms" value="yes" required>
  I agree to the terms
</label>
```

The builder has no field type for picking several options. To let people pick more than one, use a group of checkboxes that share a name in your own markup, and don't add a builder field with that name. The choices are saved as one comma-separated answer. See [Multiple values](/docs/connect/html#multiple-values).

## Field names

Answers are saved under the field's **Field name**, which is also the `name` attribute in your HTML.

* Must start with a letter and use only letters, digits, `-` and `_`.
* Up to 64 characters, and each name only once per form.
* Can't be `cf-turnstile-response`, `g-recaptcha-response` or `h-captcha-response`.

Renaming a field doesn't move old answers. Earlier submissions keep the old name, and new ones use the new name.

## Labels

The inbox, notification emails and integrations show each field's **Label** instead of its name, like "Your rating" instead of `rating`. Fields the builder doesn't list are shown by their name.

# Thank-you page and redirects

Choose what visitors see after they submit, from the default thank-you page to your own message or a redirect to your site.

What visitors see depends on how the form was sent.

| How the form was sent                             | What happens after a successful submit                                                                      |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Plain HTML form, or the embed with JavaScript off | The browser shows the Nisuform thank-you page, your own message, or goes to your redirect URL.              |
| The styled embed                                  | The form is replaced by its **Success message** from the builder, or the browser goes to your redirect URL. |
| Your own `fetch` code                             | Your code gets JSON and decides what to show. It is never redirected.                                       |

## Choose what happens after submit

Open **Settings**, **Submissions**, **After submit**:

* **Thank-you page**: the default Nisuform page. It says "Thanks!" and "Your submission has been received." and links back to the page the visitor came from. On the Free plan it also shows a small Nisuform banner at the bottom.
* **Custom message** (Pro): the same page with your own **Title** and **Message**.
* **Redirect** (Pro): the browser goes straight to your **Redirect URL**, such as `https://example.com/thanks`, with a `303` redirect.

A redirect URL must be a full `http://` or `https://` URL. Many sites use it to show their own thank-you page, count conversions in analytics, or run a tracking pixel.

## Redirect per submission

On Pro, a form can choose its destination on each submit with a `_redirect` field. It overrides the form's setting for that submission:

```html
<input type="hidden" name="_redirect" value="https://example.com/thanks?plan=team">
```

The URL must be on the same site as the page that sent the form, or on one of the form's allowed websites. See [Special fields](/docs/connect/special-fields#_redirect).

## Errors and closed forms

When a browser submit is rejected, the visitor sees a short page with the reason and a link back to your site. When the form is closed, the page says "This form is closed". On Pro you can write your own text for it. See [Pause and close a form](/docs/forms/closing).

## When the team is not on Pro

Custom messages, redirects and `_redirect` only apply while the team is on Pro. If the team moves back to Free, browser submits get the default thank-you page again, and your settings are kept for when you upgrade.

# Pause and close a form

Stop accepting submissions by hand, after a maximum number of submissions, or on a set date.

A form can stop accepting submissions in three ways. While it is closed, new submissions are rejected with status `423`, and everything you already received stays in the inbox.

## Pause a form

Open **Settings**, **General** and choose **Pause form**. The status changes from **Accepting submissions** to **Paused**. Choose **Resume form** to open it again.

Rejected submissions get the error `form_closed_manual`.

## Close after a number of submissions

Open **Settings**, **Submissions**, **Limits** and set **Maximum submissions**. The form closes once it has received that many. Leave it empty for no limit.

Spam and test submissions don't count toward the maximum. Once the form is full, new submissions get `form_max_submissions`.

This works well for limited signups, like an event with 50 seats or a beta with 200 spots. To reopen the form, raise the maximum or clear it.

## Close on a date

In the same section, set **Close on** to a date and time, shown in your own time zone. From that moment, new submissions get `form_auto_close`. Clear the date, or move it later, to reopen the form.

## What visitors see

* Browser submits show a page titled **This form is closed** with a message and a link back to your site.
* `fetch` requests get JSON with `ok: false`, the error code and a message.

The default message is "This form is closed and not accepting submissions". On Pro, write your own in **Closed message**, for example "Registration has closed. See you next year!". It is used for all three ways of closing.

```json
{ "ok": false, "error": "form_closed_manual", "message": "Registration has closed. See you next year!" }
```

The styled embed shows the same message inside the form, next to the button.

# Form settings

Every setting on a form's Settings tab, what it does and which plan it needs.

Each form has its own settings. Open the form and choose the **Settings** tab. Every section has its own save bar, so changes apply only after you save them.

## General

| Setting    | What it does                                                                                          | Plan |
| ---------- | ----------------------------------------------------------------------------------------------------- | ---- |
| Name       | Shown in your dashboard and in notification emails.                                                   | All  |
| Icon       | An emoji shown next to the form in your lists.                                                        | All  |
| Type       | The kind of form, like Contact or Waitlist. Your fields stay the same.                                | All  |
| Pause form | Rejects new submissions until you resume the form. See [Pause and close a form](/docs/forms/closing). | All  |

## Endpoint

| Setting      | What it does                                                                                                                      | Plan |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------- | ---- |
| Endpoint URL | The URL your form posts to. Copy it into your form's `action` or your `fetch` call.                                               | All  |
| Rotate key   | Gives the form a new endpoint. The current one stops working right away. See [Rotate the key](/docs/forms/create#rotate-the-key). | All  |

## Email

| Setting                  | What it does                                                        | Plan |
| ------------------------ | ------------------------------------------------------------------- | ---- |
| Email me new submissions | Sends an email for every new submission. On by default.             | All  |
| Send to                  | Where notifications go. Empty means the team owner's account email. | Pro  |
| Sender name              | The name notifications come from.                                   | Pro  |
| Subject                  | The notification subject, with placeholders.                        | All  |
| Auto-reply to submitters | Sends a confirmation to the person who filled in the form.          | Pro  |

Details are in [Email notifications](/docs/submissions/notifications) and [Auto-replies](/docs/submissions/auto-replies).

## Submissions

| Setting             | What it does                                                                                              | Plan                                |
| ------------------- | --------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| After submit        | Thank-you page, custom message or redirect. See [Thank-you page and redirects](/docs/forms/after-submit). | Custom message and redirect are Pro |
| Maximum submissions | Closes the form after this many submissions.                                                              | All                                 |
| Close on            | Closes the form at a date and time.                                                                       | All                                 |
| Closed message      | Shown when the form is paused, full or past its close date.                                               | Pro                                 |
| Accept file uploads | Lets the form receive up to 5 files per submission. See [File uploads](/docs/connect/file-uploads).       | Pro                                 |
| Size limit per file | The largest file the form accepts, 10 MB by default.                                                      | Pro                                 |

## Spam protection

| Setting                      | What it does                                                                                                 | Plan |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------ | ---- |
| Require Cloudflare Turnstile | Rejects submissions without a valid Turnstile token. See [Cloudflare Turnstile](/docs/protection/turnstile). | All  |
| Allowed websites             | Accepts submissions only from these sites.                                                                   | All  |
| Blocked IP addresses         | Drops submissions from these IP addresses.                                                                   | All  |
| Blocked countries            | Drops submissions from these countries.                                                                      | All  |
| Store IP addresses           | Saves the sender's IP address with each submission. On by default.                                           | All  |

Details are in [Access rules](/docs/protection/access-rules) and [Privacy and data](/docs/account/privacy).

## Delete form

**Delete form** at the bottom of the page permanently deletes the form, all of its submissions and uploaded files, and its integrations. It can't be undone. Export your submissions first if you want to keep them. See [Export submissions](/docs/submissions/export).

## Settings that need Pro

If a team moves from Pro back to Free, its Pro settings are kept but stop applying: notifications go to the owner's account email with the default sender name, auto-replies and integrations pause, uploads are skipped, and visitors see the default thank-you and closed pages. Everything comes back when the team upgrades again.

# Inbox

Read, star, flag and delete submissions one at a time or many at once, see where each one came from, and download uploaded files.

Every form has its own inbox. Open a form and it lands on the **Inbox** tab, with the newest submissions first.

## Filters

| Filter  | Shows                                              |
| ------- | -------------------------------------------------- |
| All     | Every submission except spam.                      |
| Unread  | Submissions you haven't opened yet, except spam.   |
| Starred | Submissions you starred.                           |
| Spam    | Submissions that Nisuform, or you, marked as spam. |

Unread submissions are highlighted in the list. The inbox shows 15 submissions per page.

## Read a submission

Select a submission to open it. Opening it marks it as read. You see:

* Every answer, labeled with the field's **Label** from the form builder. Fields your form sent that the builder doesn't list are shown by their name.
* Validation problems, if some answers didn't match your fields. See [Fields and validation](/docs/forms/fields).
* Uploaded files, with their names and sizes. Select one to download it.
* **Received**: the date and time.
* **Page**: the page the form was sent from.
* **Location**: the country the request came from.
* **Device**: desktop, mobile, tablet or bot, and the browser.
* **IP address**: unless you turned off **Store IP addresses** for the form.
* **Submission ID**: the same ID the endpoint returned, and the one webhooks and integrations use. Select it to copy.

Press the up and down arrow keys to move to the newer or older submission, across pages too. Test submissions sent from the dashboard have a **Test** badge.

Links in notification emails and integrations open the submission straight away, on the page of the inbox it belongs to. If it has been moved to spam since, the inbox switches to the spam folder.

## Star, flag and delete

The actions at the top of an open submission:

* **Mark unread** or **Mark read**.
* **Star** to find the submission later under **Starred**.
* **Flag spam** moves the submission to the spam folder. **Not spam** moves it back to your inbox. Moving a submission doesn't send notifications.
* **Delete** removes the submission and its uploaded files for good. It can't be undone.

## Select several

Select a submission's avatar, or its checkbox when you point at it, to select it. Then use the bar at the bottom of the screen to mark the selection read or unread, star it, flag it as spam or delete it.

* Hold **Shift** and select another submission to select everything in between.
* Use the checkbox above the list to select the whole page. To select every submission in the current filter, not just this page, choose **Select all** in the note that appears.
* Your selection stays when you move between pages, so you can pick submissions from several pages. It clears when you switch filters.
* With a submission focused, press **X** to select it. Press **Esc** to clear the selection.

Deleting asks you to confirm first, and tells you when some of the selected submissions are on other pages. Selecting every submission in a filter only includes the ones that had arrived when you selected them, so a submission that comes in while you work is never changed or deleted by accident.

## Spam folder

Submissions that look like spam, such as messages full of links or exact repeats, go to the spam folder instead of your inbox. They don't send notifications, don't reach your integrations and don't count toward your monthly limit. Check the folder now and then, and choose **Not spam** for anything that belongs in your inbox. See [How spam filtering works](/docs/protection/spam).

Bots caught by the honeypot or the fill-time check are dropped before anything is stored, so they never appear in the spam folder.

## Dashboard overview

The **Dashboard** page summarizes your team: submissions, spam blocked, unread submissions and the last submission for the last 7, 30 or 90 days, with a chart per day. Filter it by form, jump to your recent forms, and watch your monthly usage against your plan's limit.

## Export

Choose **Export CSV** in the inbox to download the submissions in the current filter. See [Export submissions](/docs/submissions/export).

# Email notifications

Get an email for every new submission, choose who receives it, and customize the subject and sender name.

Every form emails you when a new submission arrives. It is on by default for new forms. Configure it in the form's **Settings**, **Email** section.

## What the email contains

* The subject, which is `New submission: {{form.name}}` unless you change it.
* Every answer, labeled with the field's **Label** from the form builder.
* A **View in nisuform** link that opens the submission in your inbox.
* The time it was received.

When the submission includes an email address, the notification's **Reply-To** is set to it. Press reply in your email app to answer the person who filled in the form. Nisuform uses the form's first **Email** field, or the first answer that looks like an email address when the form has no email field.

Uploaded files are not attached. Open the submission to download them.

## Who receives it

By default, notifications go to the account email of the team's owner. On Pro, enter any address in **Send to**, such as a shared inbox like `team@example.com`. Leave it empty to go back to the owner's email.

To reach several people, use a group address or forward from your email app, or connect [Slack, Discord or Telegram](/docs/integrations) so the whole team sees each submission.

## Sender name

Notifications come from Nisuform's sending address with the sender name `nisuform`. On Pro, change **Sender name** to something like `Acme Website` so notifications are easy to spot and filter. The sending address itself doesn't change.

## Subject

Change **Subject** on any plan. Two kinds of placeholders are filled in for each submission:

| Placeholder       | Becomes                                                    |
| ----------------- | ---------------------------------------------------------- |
| `{{form.name}}`   | The form's name.                                           |
| `{{field.email}}` | The answer to the field named `email`. Use any field name. |

The dashboard shows the available placeholders as chips under the Subject box. Select one to insert it. For example:

```text
{{form.name}}: {{field.name}} ({{field.email}})
```

A placeholder for a field that wasn't answered is left as it is. Line breaks are removed and the subject is cut at 250 characters.

## When notifications are sent

| Submission                                                    | Email notification |
| ------------------------------------------------------------- | ------------------ |
| Accepted submission                                           | Sent               |
| Test submission from the dashboard                            | Sent               |
| Spam folder                                                   | Not sent           |
| Dropped as a bot, blocked, rejected or over the monthly limit | Not sent           |

Moving a submission out of the spam folder doesn't send a notification.

Emails usually arrive within seconds. If sending fails for a temporary reason, Nisuform keeps retrying for about two hours.

## Turn notifications off

Turn off **Email me new submissions** to stop emails for one form. Submissions are still stored, and integrations still run.

## Emails about your account

Nisuform also sends two summaries to team owners:

* **Weekly digest**: every Monday at 09:00 UTC, the number of submissions your forms received in the past week. It is only sent when there were submissions.
* **Missed leads**: on the first of each month, Free teams that hit their monthly limit get the number of submissions their forms turned away.

## Not getting emails?

* Check your spam or junk folder, and add Nisuform's sending address to your contacts.
* Check that **Email me new submissions** is on and **Send to** is the address you expect.
* Check the form's **Spam** folder in the inbox. Spam doesn't send notifications.
* Send a test from the **Setup** tab. If the test arrives, the problem is with the submissions from your site. See [Troubleshooting](/docs/reference/troubleshooting).

# Auto-replies

Send an automatic confirmation email to the people who fill in your form, with their own answers in the text.

Auto-replies are available on Pro. When someone submits your form, Nisuform emails them a confirmation, so they know their message arrived.

## Turn on auto-replies

1. Make sure the form has an **Email** field in the [form builder](/docs/forms/builder). The auto-reply goes to that address.
2. Open **Settings**, **Email** and turn on **Auto-reply to submitters**.
3. Write a **Subject** and **Message**, or leave both empty to send the default text.
4. Save.

The default subject is "We received your message", and the default message is "Thanks for reaching out. We got your message and will get back to you soon."

## Use answers in the text

Insert an answer with the field's name in double braces, and a field's label with `.label`:

| Placeholder      | Becomes                                                |
| ---------------- | ------------------------------------------------------ |
| `{{name}}`       | The answer to the field named `name`.                  |
| `{{name.label}}` | The label of the field named `name`, like "Your name". |

```text
Hi {{name}},

Thanks for getting in touch. We read every message and will reply to {{email}} within one business day.

The Acme team
```

The dashboard shows the available fields as chips under the Message box. Select one to insert it. Up to 5 different fields are filled in per email, and a placeholder for a field that wasn't answered is left as it is.

## Who receives it

The auto-reply goes to the answer of the form's first **Email** field. If the form has no Email field, Nisuform uses the first answer that looks like an email address. The dashboard warns you when the form has no Email field.

No auto-reply is sent when:

* the address is missing or isn't a valid email address,
* the same address already got an auto-reply from this form in the last 24 hours, so one person submitting twice gets one reply,
* the submission went to the spam folder, or
* it is a test submission from the dashboard.

## How it looks

Auto-replies are plain text emails from Nisuform's sending address with the sender name `nisuform`. Keep them short and useful, and don't use them for marketing. Recipients didn't sign up for a newsletter by filling in your form.

## On the Free plan

The switch shows a Pro badge on the Free plan, and auto-replies are not sent. If a Pro team moves back to Free, auto-replies stop until it upgrades again, and your text is kept.

# Analytics

See how each form performs over time, where submissions come from and how people answered your choice, rating and number fields.

The **Analytics** tab is available on Pro. On the Free plan it shows a preview with sample data. Spam and test submissions are always left out.

## Overview

Pick the last 7, 30 or 90 days:

* **Submissions per day**: a chart of accepted submissions, with the total and the spam caught in the same period.
* **Top pages**: the pages people submitted the form from. Submissions without a known page are grouped as "Direct or unknown".
* **Countries**: where submissions came from, based on the request's location.
* **Devices**: desktop, mobile, tablet or bot.
* **Busiest hours**: a heatmap of submissions by weekday and hour.

## Answers

Below the overview, Nisuform summarizes every submission the form has received for these field types:

| Field type                   | Summary                                                           |
| ---------------------------- | ----------------------------------------------------------------- |
| Dropdown and Multiple choice | How many people picked each option.                               |
| Checkbox                     | How many checked it and how many didn't.                          |
| Star rating                  | The average rating and how many people gave each number of stars. |
| Number                       | The total and the average of all answers.                         |

Answers are matched to your fields by field name, so they only appear for forms with fields in the [form builder](/docs/forms/builder). A form without choice, rating or number fields has nothing to summarize.

## Dashboard stats on every plan

The **Dashboard** page shows submissions, spam blocked, unread submissions and a daily chart for all your forms on every plan. See [Inbox](/docs/submissions/inbox#dashboard-overview).

# Export submissions

Download a form's submissions as a CSV file that opens in Excel, Numbers and Google Sheets.

Every plan can export submissions. Exports are CSV files, and your submissions stay in your account after you export them.

## Export

1. Open the form's **Inbox**.
2. Pick a filter: **All**, **Unread**, **Starred** or **Spam**. The export contains the submissions in that filter.
3. Choose **Export CSV**.

The file is named after the form, like `contact-form-submissions.csv`, and downloads right away, even with thousands of submissions.

## Columns

| Column               | Contains                                                       |
| -------------------- | -------------------------------------------------------------- |
| `id`                 | The submission ID.                                             |
| `created_at`         | When it was received, in UTC, like `2026-09-24T10:00:00.000Z`. |
| `read`               | `true` or `false`.                                             |
| `starred`            | `true` or `false`.                                             |
| `is_spam`            | `true` or `false`.                                             |
| `is_test`            | `true` for test submissions sent from the dashboard.           |
| One column per field | The answers, in alphabetical order of field name.              |

Rows are sorted newest first. A field that a submission didn't include is left empty.

## Opening the file

* The file is UTF-8 with a byte order mark, so Excel shows accents, emoji and non-Latin scripts correctly.
* Answers that start with `=`, `+`, `-`, `@`, a tab or a carriage return get a leading apostrophe, so a spreadsheet never runs them as formulas.
* Uploaded files are not included. Download them from each submission.

## Keep a live copy instead

To get every new submission in a spreadsheet as it arrives, connect [Google Sheets](/docs/integrations/google-sheets). For other tools, use a [webhook](/docs/integrations/webhooks) or [Zapier and Make](/docs/integrations/zapier-make).

# How spam filtering works

The checks every submission goes through, what happens to bots and spam, and what you can turn on for extra protection.

Spam protection is built in on every plan and needs no setup. Every submission goes through the same checks, in this order.

| Check                     | Catches                                        | What happens              |
| ------------------------- | ---------------------------------------------- | ------------------------- |
| Blocked IPs and countries | Addresses and countries you blocked            | Dropped without notice    |
| Allowed websites          | Submissions from sites you didn't allow        | Rejected with `403`       |
| Rate limits               | Floods from one client or at one form          | Rejected with `429`       |
| Honeypot                  | Bots that fill in the hidden `_gotcha` field   | Dropped without notice    |
| Fill time                 | Bots that submit in under 2 seconds            | Dropped without notice    |
| Cloudflare Turnstile      | Bots that can't solve the challenge            | Rejected with `403`       |
| Links and link markup     | Link spam                                      | Stored in the spam folder |
| Duplicates                | The same submission sent again within 24 hours | Stored in the spam folder |

Blocked IPs, blocked countries, allowed websites and Turnstile are optional and set per form. Everything else is always on.

## Dropped without notice

Submissions caught by the honeypot, the fill-time check or your block lists are never stored and never counted. They still get a normal success response, so bots can't learn what gave them away. The JSON response has no `submissionId` in that case.

* **Honeypot**: the hidden `_gotcha` input. People never see it, so they leave it empty. See [Special fields](/docs/connect/special-fields#_gotcha).
* **Fill time**: the `_elapsed` field, in milliseconds. The styled embed sends it for you. Forms without it skip this check.

## Rate limits

| Limit                                                         | Retry after |
| ------------------------------------------------------------- | ----------- |
| 30 submissions a minute from one IP address, across all forms | 60 seconds  |
| 5 submissions a minute from one IP address to one form        | 60 seconds  |
| 200 submissions an hour to one form, from everyone            | 5 minutes   |

Requests over a limit get `429` with a `Retry-After` header. People filling in a form by hand never come close to these limits.

## The spam folder

Some submissions look like spam but could be real. Those are stored in the form's **Spam** folder instead of being dropped:

* **Links**: more than 5 links in total across all answers. Both `https://` addresses and `www.` addresses count.
* **Link markup**: forum-style link code like `[url=...]` or `[link=...]`, or an HTML link like `<a href="...">`.
* **Duplicates**: exactly the same answers as a submission the form received in the last 24 hours, ignoring capitals and surrounding spaces. Only submissions with an email address, or an answer of at least 20 characters, are compared, so identical short answers like a 5-star rating are never flagged.

Spam never sends notifications or auto-replies, never reaches your integrations and doesn't count toward your monthly limit. Open the **Spam** filter in the inbox to review it, and choose **Not spam** to move a submission back. See [Inbox](/docs/submissions/inbox#spam-folder).

## Add more protection

If spam still gets through, turn on more checks for the form in **Settings**, **Spam protection**:

<Card title="Allowed websites" href="/docs/protection/access-rules#allowed-websites" description="Accept submissions only from your own domains." />

<Card title="Cloudflare Turnstile" href="/docs/protection/turnstile" description="Add an invisible challenge that stops automated submissions." />

<Card title="Block IPs and countries" href="/docs/protection/access-rules#blocked-ip-addresses" description="Drop submissions from specific addresses or countries." />

<Card title="Rotate the key" href="/docs/forms/create#rotate-the-key" description="Give the form a new endpoint when the old one is being abused." />

## Tips

* Keep the `_gotcha` honeypot in every form you write yourself, and send `_elapsed` when you submit with JavaScript.
* Use the styled embed from the form builder. It includes both checks.
* Turn on Turnstile for forms that attract a lot of spam, like public signup forms.

# Access rules

Accept submissions only from your own websites, and block IP addresses and countries.

Access rules limit where a form's submissions can come from. Set them in the form's **Settings**, **Spam protection**, **Access rules**.

## Allowed websites

Enter the sites that are allowed to send submissions, one per line:

```text
https://example.com
https://www.example.com
https://staging.example.com
```

Once the list has at least one site, Nisuform compares the site in each request's `Origin` header, or its `Referer` header when there is no `Origin`, with the list. Submissions from any other site are rejected with `403` and `origin_not_allowed`. Leave the list empty to accept submissions from any website.

* Only the scheme, host and port count. A full URL like `https://example.com/contact` is saved as `https://example.com`.
* `https://example.com` and `https://www.example.com` are different sites. Add both if your site answers on both.
* Add `http://localhost:3000`, or whatever your dev server uses, to test locally.
* Up to 50 sites per form.

Allowed websites also decide where a [`_redirect`](/docs/connect/special-fields#_redirect) may send visitors.

<Callout title="Browsers only" type="warn">
  Browsers always send `Origin` or `Referer`, and pages can't fake them. Scripts and servers can send any headers, or none. Requests without either header are allowed, so allowed websites stop other sites from embedding your form, but they don't stop a determined bot. Combine them with [Cloudflare Turnstile](/docs/protection/turnstile) for that.
</Callout>

## Blocked IP addresses

Enter IP addresses to block, one per line or separated by commas. Both IPv4 and IPv6 addresses work, and each must match exactly. Ranges are not supported. Up to 1,000 addresses per form.

Find a sender's address on any submission in the inbox, under **IP address**.

## Blocked countries

Pick countries to block. The country comes from where the request reaches Nisuform, based on the sender's IP address. VPNs and proxies change it.

## What blocked senders see

Submissions from a blocked IP address or country are dropped without notice. The sender gets a normal success response, without a `submissionId`, so they have no reason to try another way. Nothing is stored, and nothing counts toward your limits.

## Store IP addresses

**Store IP addresses** is on by default and saves each sender's IP address with the submission, so you can block it later. Turn it off for forms that don't need it. New submissions are then stored without an IP address. Blocking and rate limits still work, because they check the address while the request is handled. See [Privacy and data](/docs/account/privacy).

# Cloudflare Turnstile

Require a Cloudflare Turnstile challenge on your form so automated submissions are rejected before they are stored.

[Cloudflare Turnstile](https://www.cloudflare.com/products/turnstile/) is a free, privacy-friendly alternative to CAPTCHAs. Most visitors never see a puzzle. You use your own Turnstile widget, and Nisuform verifies its token on every submission. It works on every plan.

## Set it up

### Create a Turnstile widget

In the Cloudflare dashboard, open **Turnstile** and add a widget. Add every hostname your form is on, like `example.com` and `www.example.com`. Copy the **site key** and the **secret key**.

### Add the keys to your form

Open the form's **Settings**, **Spam protection**. Turn on **Require Cloudflare Turnstile**, paste the **Site key** and the **Secret key**, and save.

The secret key is write only. Once saved, it is never shown again. Paste a new one to replace it.

### Add the widget to your form

If you use the styled embed, copy it again from **Get code** in the builder or from the **Setup** tab. It includes the widget once Turnstile is on.

For your own markup, load the Turnstile script and place the widget inside the form:

```html
<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>

<form action="https://api.nisuform.com/s/YOUR_FORM_KEY" method="POST">
  <input type="email" name="email" required>
  <textarea name="message" required></textarea>
  <div class="cf-turnstile" data-sitekey="YOUR_TURNSTILE_SITE_KEY"></div>
  <button type="submit">Send</button>
</form>
```

The widget adds a hidden `cf-turnstile-response` field to the form. Nisuform checks it, and never stores it.

<Callout type="warn">
  Add the widget to your site before you turn Turnstile on, or right after. While Turnstile is on, every submission without a valid token is rejected.
</Callout>

## With fetch

When you submit with JavaScript, send the token along with your fields. `FormData` picks it up from the form:

```js
const response = await fetch(form.action, {
  method: 'POST',
  headers: { Accept: 'application/json' },
  body: new FormData(form),
})
const result = await response.json()
if (result.error === 'captcha_failed') {
  turnstile.reset()
}
```

A token can only be used once. Reset the widget after a failed submit so the visitor gets a fresh token.

## When the check fails

A missing, expired, reused or invalid token is rejected with `403` and `captcha_failed`, and the message "Captcha verification failed. Complete the captcha and try again". Nothing is stored, so the visitor can solve the challenge and send again.

If every submission fails:

* Check that the site key in your page and the keys in your form settings belong to the same widget.
* Check that your site's hostname is in the widget's hostname list in Cloudflare.
* Check that the widget is inside the `<form>` element, so its field is sent.

# Integrations overview

Send every new submission to Slack, Discord, Telegram, Google Sheets or a webhook, with retries and delivery status.

Integrations are available on Pro. Each one gets every new submission as it arrives, alongside your email notification.

<Card title="Webhooks" href="/docs/integrations/webhooks" description="Signed JSON to your own server, Zapier, Make or n8n." />

<Card title="Slack" href="/docs/integrations/slack" description="Post each submission to a channel." />

<Card title="Discord" href="/docs/integrations/discord" description="Send each submission to a channel." />

<Card title="Telegram" href="/docs/integrations/telegram" description="Get a message from the Nisuform bot." />

<Card title="Google Sheets" href="/docs/integrations/google-sheets" description="Add each submission as a row." />

<Card title="Zapier, Make and n8n" href="/docs/integrations/zapier-make" description="Connect thousands of other apps through a webhook." />

## Connect an integration

Open the form's **Integrations** tab, pick a destination under **Add a destination** and follow the steps in the dialog. Each form can have one integration of each kind, and integrations are set per form.

## What gets delivered

* Every accepted submission, as soon as it is stored.
* Test submissions sent from the **Setup** tab, marked as tests.
* Never spam, and never submissions that were dropped, blocked or rejected.

Slack, Discord and Telegram messages list each answer by its label and link to the submission in your inbox. Uploaded files are not sent. Open the submission to download them.

## Send a test

Choose **Send test** on a connected integration to deliver a sample submission right away. It uses your form's fields with sample answers, is marked as a test, and isn't stored in your inbox. If the delivery fails, the dashboard shows why.

## Delivery status and retries

The Integrations tab shows whether each destination is delivering:

* **Failing**: the last delivery failed. The reason and time are shown, like "Slack answered 404. The webhook was probably removed." It clears after the next successful delivery.
* **Paused**: you turned it off. New submissions are not sent while it is paused, and they are not sent later when you turn it back on.
* **Needs Pro**: the team is on the Free plan, so the integration is paused until the team upgrades.

When a destination is down or busy, Nisuform retries. Timeouts, network errors, `408`, `429` and `5xx` responses are retried with growing delays, from 30 seconds up to one hour between attempts, for about two hours. Other responses, like `404` or `403`, mean the destination was removed or no longer accepts messages, so Nisuform stops and marks the integration as failing.

## Pause and disconnect

* Turn off the switch next to a connected integration to pause it. Deliveries stop without losing the setup. Turn it back on to send new submissions again.
* Choose **Disconnect** from the integration's menu to remove it. New submissions stop going there. For webhooks, the signing secret is deleted too, so reconnecting issues a new one.

## Need a file instead?

[Export submissions as CSV](/docs/submissions/export) from the inbox on any plan.

# Webhooks

Receive a signed submission.created event on your own HTTPS endpoint for every new submission, and verify it with any Standard Webhooks library.

Webhooks are available on Pro. Nisuform sends a `POST` request with a JSON body to your URL for every new submission. Each delivery is signed following the [Standard Webhooks](https://www.standardwebhooks.com) spec, so you can prove it came from Nisuform.

## Connect a webhook

1. Build an endpoint that accepts a `POST` with a JSON body and answers with any `2xx` status.
2. Open the form's **Integrations** tab and choose **Webhook**.
3. Paste your endpoint's URL. It must start with `https://`.
4. Copy the **Signing secret** that appears. It starts with `whsec_`. Store it on your server, for example as `NISUFORM_WEBHOOK_SECRET`.
5. Choose **Send test** to check that your endpoint receives and verifies it.

You can find the secret again under **Signing secret and payload** on the webhook. Changing the URL later keeps the same secret.

## The request

```http
POST /webhooks/nisuform HTTP/1.1
Content-Type: application/json
User-Agent: nisuform-webhooks/1
webhook-id: msg_3f2c8a61-5d4e-4b7a-9c1f-2a6e8d0b4c17
webhook-timestamp: 1790244001
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
```

```json
{
  "type": "submission.created",
  "timestamp": "2026-09-24T10:00:01.000Z",
  "data": {
    "formId": "8d7e6f5a-4b3c-4d2e-9f1a-0b9c8d7e6f5a",
    "submissionId": "3f2c8a61-5d4e-4b7a-9c1f-2a6e8d0b4c17",
    "submittedAt": "2026-09-24T10:00:00.000Z",
    "test": false,
    "fields": {
      "name": "Jane Doe",
      "email": "jane@example.com",
      "message": "Hello!"
    }
  }
}
```

| Field               | Meaning                                                                                        |
| ------------------- | ---------------------------------------------------------------------------------------------- |
| `type`              | Always `submission.created`.                                                                   |
| `timestamp`         | When this delivery was sent.                                                                   |
| `data.formId`       | The form's ID.                                                                                 |
| `data.submissionId` | The submission's ID, the same one the submit endpoint returned.                                |
| `data.submittedAt`  | When the submission was received.                                                              |
| `data.test`         | `true` for test submissions sent from the dashboard.                                           |
| `data.fields`       | The answers by field name. Every value is a string. Special fields and files are not included. |

The dashboard shows a sample payload with your form's own fields under **Signing secret and payload**.

## Verify the signature

Always verify deliveries before you trust them. Use a [Standard Webhooks library](https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries) for your language with the `whsec_` secret. It checks the signature and rejects deliveries older than 5 minutes, which stops replays.

```js
import { Webhook } from 'standardwebhooks'

const webhook = new Webhook(process.env.NISUFORM_WEBHOOK_SECRET)

export async function POST(request) {
  const payload = await request.text()
  let event
  try {
    event = webhook.verify(payload, Object.fromEntries(request.headers))
  } catch {
    return new Response('Invalid signature', { status: 400 })
  }
  console.log(event.data.fields)
  return new Response(null, { status: 204 })
}
```

```python
import os
from standardwebhooks.webhooks import Webhook

webhook = Webhook(os.environ["NISUFORM_WEBHOOK_SECRET"])

def handle(body: bytes, headers: dict) -> int:
    try:
        event = webhook.verify(body, headers)
    except Exception:
        return 400
    print(event["data"]["fields"])
    return 204
```

Verify the raw body exactly as it arrived. Parsing the JSON and serializing it again changes the bytes and breaks the signature.

### Verify without a library

The signature is an HMAC-SHA256 of `{webhook-id}.{webhook-timestamp}.{body}`, keyed with the secret after removing the `whsec_` prefix and base64-decoding it. The header holds `v1,` followed by the base64 digest.

```js
import { createHmac, timingSafeEqual } from 'node:crypto'

function verify(secret, headers, body) {
  const id = headers.get('webhook-id')
  const timestamp = headers.get('webhook-timestamp')
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
    return false
  }
  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64')
  const expected = createHmac('sha256', key).update(`${id}.${timestamp}.${body}`).digest('base64')
  return headers
    .get('webhook-signature')
    .split(' ')
    .some((part) => {
      const [version, signature] = part.split(',')
      return version === 'v1' && signature.length === expected.length &&
        timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
    })
}
```

## Respond quickly

* Answer with any `2xx` status within 10 seconds. The body is ignored.
* Do slow work, like sending emails or calling other APIs, after you respond or in a background job.
* Redirects are not followed. A `3xx` response counts as a failure, so use the final URL.

## Retries and duplicates

Timeouts, network errors, `408`, `429` and `5xx` responses are retried with growing delays for about two hours. Other responses, like `400`, `401` or `404`, are not retried and mark the webhook as failing on the Integrations tab. See [Delivery status and retries](/docs/integrations#delivery-status-and-retries).

Every attempt for the same submission carries the same `webhook-id`, so your endpoint may receive a submission more than once. Store the ID, or the `submissionId`, and skip events you have already handled.

## Rotate the secret

If the secret leaks, choose **Rotate secret** under **Signing secret and payload**. Deliveries are signed with the new secret right away, and your server rejects them until you update it there. Disconnecting the webhook deletes its secret, so reconnecting always issues a new one.

# Slack

Post every new form submission to a Slack channel with an incoming webhook.

The Slack integration is available on Pro. Each submission arrives in the channel you pick, with every answer and a button that opens it in Nisuform.

## Connect Slack

### Create a Slack app

Go to [api.slack.com/apps](https://api.slack.com/apps), choose **Create New App**, then **From scratch**. Name it something like "Website forms" and pick your workspace.

### Add an incoming webhook

Open **Incoming Webhooks** and turn it on. Choose **Add New Webhook** and pick the channel. Copy the webhook URL. It starts with `https://hooks.slack.com/`.

### Paste it into Nisuform

Open the form's **Integrations** tab, choose **Slack** and paste the URL. Then choose **Send test** and check the channel.

URLs from Slack Workflow Builder triggers, which start with `https://hooks.slack.com/triggers/` or `https://hooks.slack.com/workflows/`, work too.

## The message

* A header with &#x2A;*New submission:** and the form name.
* One section per answer, with the field's label in bold. Empty answers show as *Empty*.
* An **Open in nisuform** button that opens the submission in your inbox.
* Test submissions say "Test submission sent from the nisuform dashboard".

Very long answers are shortened, and forms with many fields show the first ones and a note like "3 more fields in nisuform".

## Troubleshooting

| Error                         | Fix                                                                                          |
| ----------------------------- | -------------------------------------------------------------------------------------------- |
| Slack answered 404 or 410     | The webhook or the app was removed. Create a new webhook and paste its URL.                  |
| Slack answered 403            | The app was uninstalled or lost access to the channel. Reinstall it or create a new webhook. |
| Slack answered a `3xx` status | The URL isn't a Slack webhook URL. Copy it again from **Incoming Webhooks**.                 |

To post to a different channel, add a new webhook for that channel in your Slack app and paste its URL.

# Discord

Send every new form submission to a Discord channel with a channel webhook.

The Discord integration is available on Pro. Each submission arrives in the channel as an embed with every answer and a link to it in Nisuform.

## Connect Discord

### Create a webhook

In Discord, open the settings of the channel you want submissions in. Go to **Integrations**, then **Webhooks**, and choose **New Webhook**. You need the Manage Webhooks permission on the server.

### Copy its URL

Choose **Copy Webhook URL**. It starts with `https://discord.com/api/webhooks/`.

### Paste it into Nisuform

Open the form's **Integrations** tab, choose **Discord** and paste the URL. Then choose **Send test** and check the channel.

## The message

* The title &#x2A;*New submission:** with the form name, linked to the submission in your inbox.
* One field per answer, with its label. Empty answers show as "(empty)".
* The time it was received, and a footer that says "Test submission" for tests.

Messages are posted as **nisuform** and never mention `@everyone`, `@here`, roles or users, even if an answer contains them. Very long answers are shortened, and forms with more than 25 fields show the first ones and a note with how many more are in Nisuform.

## Troubleshooting

| Error                       | Fix                                                                             |
| --------------------------- | ------------------------------------------------------------------------------- |
| Discord answered 404        | The webhook or the channel was deleted. Create a new webhook and paste its URL. |
| Discord answered 401 or 403 | The webhook's token changed. Copy the URL again from the channel settings.      |
| Discord answered 429        | Discord is rate limiting the webhook. Nisuform retries on its own.              |

# Telegram

Get a Telegram message from the Nisuform bot for every new form submission, in a private chat or a group.

The Telegram integration is available on Pro. The Nisuform bot sends each submission to a private chat with you or to a group. There is no bot or token to set up on your side.

## Connect Telegram

1. Open the form's **Integrations** tab and choose **Telegram**.
2. Pick where messages should go:
   * **Open chat with the bot** opens a private chat. Press **Start**.
   * **Add to a group** lets you pick a group and adds the bot to it.
3. Back in Nisuform, the dialog shows **Connected** as soon as Telegram confirms. The bot also replies in the chat with "Connected. New submissions to *your form* will show up here."

The links work for 30 minutes. If one expired, close the dialog and open it again for new links. If the dialog keeps saying it is waiting, make sure you pressed **Start** in Telegram, then choose **Check again**.

Each form connects to one chat. Connecting another chat replaces the previous one.

## The message

* **New submission:** and the form name in bold, with *Test submission* for tests.
* Each answer under its label. Empty answers show as "(empty)".
* An **Open in nisuform** button that opens the submission in your inbox.

Link previews are turned off, and very long submissions are shortened to fit Telegram's message limit with a note like "2 more fields in nisuform".

## Troubleshooting

| Error                                                                | Fix                                                               |
| -------------------------------------------------------------------- | ----------------------------------------------------------------- |
| Telegram answered 403. The bot was removed from the chat or blocked. | Unblock the bot, or add it back to the group, then connect again. |
| Telegram could not find the chat.                                    | The chat was deleted. Connect again.                              |

When a group is upgraded to a supergroup, Telegram gives it a new ID. Nisuform follows the change on its own.

# Google Sheets

Add every new form submission as a row in a Google Sheet with a short Apps Script that Nisuform generates for you.

The Google Sheets integration is available on Pro. Nisuform gives you a small Apps Script to paste into your spreadsheet. The script adds one row per submission and only accepts requests from your form.

## Connect Google Sheets

### Open the Apps Script editor

Open the Google Sheet you want submissions in. Choose **Extensions**, then **Apps Script**.

### Paste the script

In Nisuform, open the form's **Integrations** tab and choose **Google Sheets**. Copy the script from the dialog, replace the code in the Apps Script editor with it, and save.

### Deploy it as a web app

Choose **Deploy**, then **New deployment**, and pick the type **Web app**. Set **Execute as** to **Me** and **Who has access** to **Anyone**. Deploy, and allow access when Google asks.

### Paste the web app URL

Copy the web app URL. It starts with `https://script.google.com/` and ends with `/exec`. Paste it into the dialog in Nisuform, then choose **Send test** and check the sheet.

"Anyone" only means the script can receive requests without a Google sign-in. It doesn't share your spreadsheet. The script contains a token that belongs to your form and ignores every request without it.

## How rows are written

* Rows go to the first sheet in the spreadsheet.
* The first row holds the column headers. The script creates them and makes them bold.
* Every row starts with **Submitted at**, **Submission ID** and **Test**, which says `yes` for test submissions.
* Each answer goes in a column named after the field's label. When a new field shows up, the script adds a column for it at the end.
* Answers that start with `=`, `+`, `-` or `@` get a leading apostrophe, so the sheet never runs them as formulas.

You can rename the sheet, reorder columns and add your own columns next to them. Keep the header names the script uses, or it creates new columns.

## Troubleshooting

| Error                                 | Fix                                                                                                                           |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Google Sheets did not run the script. | The web app doesn't allow anonymous access. Deploy it again with **Who has access** set to **Anyone**, and paste the new URL. |
| The Apps Script rejected the request. | The script in the sheet doesn't match this form. Copy the latest script from Nisuform, paste it, and deploy again.            |

After you edit the script, choose **Deploy**, **Manage deployments**, and deploy a new version of the same deployment, so the URL stays the same. A new deployment gets a new URL, which you then have to paste into Nisuform.

# Zapier, Make and n8n

Connect form submissions to thousands of apps, like HubSpot, Notion, Airtable and Mailchimp, through Zapier, Make or n8n.

Zapier, Make and n8n receive submissions through a [webhook](/docs/integrations/webhooks), which is available on Pro. From there you can send them to a CRM, a database, a mailing list or any other app.

## Zapier

1. In Zapier, create a Zap and pick **Webhooks by Zapier** as the trigger.
2. Choose **Catch Hook** and copy the webhook URL Zapier gives you.
3. In Nisuform, open the form's **Integrations** tab, choose **Webhook** and paste the URL.
4. Choose **Send test**, so Zapier can see your fields. Then choose **Test trigger** in Zapier.
5. Add actions that use the fields, like **Data Fields Email** or **Data Fields Message**.

## Make

1. In Make, create a scenario and add the **Webhooks** module, **Custom webhook**.
2. Choose **Add**, name the webhook, then copy its address.
3. In Nisuform, open the form's **Integrations** tab, choose **Webhook** and paste the address.
4. Choose **Send test**, so Make can learn the data structure.
5. Add modules that use `data.fields`.

## n8n

1. Add a **Webhook** node with the HTTP method `POST` and copy its production URL.
2. Paste it into a Nisuform webhook and choose **Send test** while the workflow is listening.
3. Read the answers from `body.data.fields` in the next nodes.

To check that requests really come from Nisuform, add a Code node that verifies the `webhook-signature` header. See [Verify the signature](/docs/integrations/webhooks#verify-the-signature).

## Tips

* Every value in `data.fields` is a string. Convert numbers and dates in your automation if the next app needs them.
* Filter out tests with a condition on `data.test` being `false`.
* The same submission can arrive twice after a retry. Use `data.submissionId` as a unique key where your app supports one.

# API overview

Create forms, change their settings and work with submissions from your own code with the Nisuform REST API and an API key.

The Nisuform API lets your code do what you do on a form's pages in the dashboard: create and configure forms, page through submissions, mark them read, starred or spam, delete them, download their files and export them as CSV.

You don't need the API to collect submissions. Forms post to the [submit endpoint](/docs/reference/submit-endpoint), which is public and needs no key. Use the API when a script, a server or an automation needs to manage forms or read what came in.

```text
https://api.nisuform.com/v1
```

## Quick start

### Create an API key

In the dashboard, open **Account** from the menu under your picture, go to **API keys** and choose **Create key**. Copy the key. It starts with `nfa_` and is only shown once. See [API keys](/docs/api/keys).

### Check that it works

```sh
curl https://api.nisuform.com/v1/me \
  -H "Authorization: Bearer $NISUFORM_API_KEY"
```

The response shows your account and the team the key works in.

### List your forms and their submissions

```sh
curl https://api.nisuform.com/v1/forms \
  -H "Authorization: Bearer $NISUFORM_API_KEY"

curl "https://api.nisuform.com/v1/forms/FORM_ID/submissions?filter=unread" \
  -H "Authorization: Bearer $NISUFORM_API_KEY"
```

## Authentication

Send the key in the `Authorization` header of every request:

```http
Authorization: Bearer nfa_...
```

A missing, unknown or revoked key gets `401`. API keys are secrets: call the API from a server, a script or an automation tool, never from code that runs in a visitor's browser. The API doesn't accept browser requests from other websites.

## Teams

Every key belongs to one team, picked when you create it. Everything the key does happens in that team:

* `GET /v1/forms` lists that team's forms, and new forms are created there.
* Forms in your other teams answer `404`, as if they didn't exist.
* Plan limits and Pro features follow that team's plan.

Switching teams in the dashboard doesn't change which team a key works in.

## Endpoints

API keys can use these endpoints:

| Method   | Path                                                                                         | Does                                     |
| -------- | -------------------------------------------------------------------------------------------- | ---------------------------------------- |
| `GET`    | [`/v1/me`](/docs/api/account)                                                                | Get your account and the key's team      |
| `GET`    | [`/v1/forms`](/docs/api/forms#list-forms)                                                    | List forms                               |
| `POST`   | [`/v1/forms`](/docs/api/forms#create-a-form)                                                 | Create a form                            |
| `GET`    | [`/v1/forms/{id}`](/docs/api/forms#get-a-form)                                               | Get a form                               |
| `PATCH`  | [`/v1/forms/{id}`](/docs/api/forms#update-a-form)                                            | Update a form                            |
| `DELETE` | [`/v1/forms/{id}`](/docs/api/forms#delete-a-form)                                            | Delete a form and its submissions        |
| `POST`   | [`/v1/forms/{id}/duplicate`](/docs/api/forms#duplicate-a-form)                               | Copy a form                              |
| `POST`   | [`/v1/forms/{id}/rotate-key`](/docs/api/forms#rotate-the-form-key)                           | Give a form a new key                    |
| `POST`   | [`/v1/forms/{id}/test-submissions`](/docs/api/forms#send-a-test-submission)                  | Send a test submission                   |
| `GET`    | [`/v1/forms/{formId}/submissions`](/docs/api/submissions#list-submissions)                   | List submissions                         |
| `GET`    | [`/v1/forms/{formId}/submissions/{id}`](/docs/api/submissions#get-a-submission)              | Get a submission                         |
| `PATCH`  | [`/v1/forms/{formId}/submissions`](/docs/api/submissions#update-submissions)                 | Mark submissions read, starred or spam   |
| `DELETE` | [`/v1/forms/{formId}/submissions`](/docs/api/submissions#delete-submissions)                 | Delete submissions                       |
| `GET`    | [`/v1/forms/{formId}/submissions/{id}/files/{index}`](/docs/api/submissions#download-a-file) | Get a download link for an uploaded file |
| `GET`    | [`/v1/forms/{formId}/export.csv`](/docs/api/submissions#export-as-csv)                       | Export submissions as CSV                |

Everything else stays in the dashboard: teams and members, billing, integrations, analytics, your profile and API keys themselves. API keys get `403` there.

## Requests and responses

* Send request bodies as JSON with `Content-Type: application/json`. `GET` requests take query parameters.
* Responses are JSON, except the CSV export.
* IDs are UUIDs. Times are ISO 8601 strings in UTC, like `2026-09-29T10:00:00.000Z`.
* Every response has an `x-request-id` header. Include it when you contact support about a request.
* New fields can be added to responses at any time, so ignore fields your code doesn't know.

## Errors

Errors answer with a `4xx` or `5xx` status and a JSON body:

```json
{
  "defined": true,
  "code": "NOT_FOUND",
  "status": 404,
  "message": "Form not found"
}
```

Branch on `code`. `message` is written for people and can change.

| Status | Code                    | When                                                                                  |
| ------ | ----------------------- | ------------------------------------------------------------------------------------- |
| `400`  | `BAD_REQUEST`           | The input is invalid. `data.issues` lists each problem with its `path` and `message`. |
| `401`  | `UNAUTHORIZED`          | The key is missing, unknown or revoked.                                               |
| `402`  | `PAYMENT_REQUIRED`      | The change needs the Pro plan, or the team reached its form limit.                    |
| `403`  | `FORBIDDEN`             | API keys can't use this endpoint.                                                     |
| `404`  | `NOT_FOUND`             | The form or submission doesn't exist, or it is in another team.                       |
| `429`  | `TOO_MANY_REQUESTS`     | The key sent too many requests. Wait for the seconds in `Retry-After`.                |
| `500`  | `INTERNAL_SERVER_ERROR` | Something went wrong on our side. Retry later.                                        |

A validation error looks like this:

```json
{
  "defined": true,
  "code": "BAD_REQUEST",
  "status": 400,
  "message": "Input validation failed",
  "data": {
    "issues": [{ "path": ["name"], "message": "Too small: expected string to have >=1 characters" }]
  }
}
```

## Rate limits

Each key can send 120 requests a minute. Past that, requests get `429` with a `Retry-After` header until the minute is over. To pull many submissions, ask for up to 100 per page or use the [CSV export](/docs/api/submissions#export-as-csv).

Rate limits on the submit endpoint are separate. See [Limits](/docs/reference/limits).

## Get new submissions as they arrive

The API is the right tool for reading and managing submissions on demand. To react to each new submission, use a [webhook](/docs/integrations/webhooks) on Pro instead of asking the API every few seconds.

# API keys

Create, store and revoke the API keys that let your code use the Nisuform API, and what each key is allowed to do.

An API key lets your code use the [Nisuform API](/docs/api) as you, in one of your teams.

## Create a key

1. Open **Account** from the menu under your picture.
2. In **API keys**, choose **Create key**.
3. Give it a name you'll recognize later, like `Production server` or `Zapier`.
4. If you belong to more than one team, pick the team the key works in.
5. Choose **Create key** and copy it.

The key is shown once. Nisuform only stores a hash of it, so nobody can show it to you again. If you lose it, revoke it and create a new one.

Keys start with `nfa_`. The dashboard shows the first 12 characters of each key so you can tell them apart.

## Keep keys secret

Anyone who has a key can read, change and delete the forms and submissions in its team.

* Store it in an environment variable or a secret manager, like `NISUFORM_API_KEY`.
* Use it only on servers and in scripts. Never put it in website code, a mobile app or a public repository.
* Create one key per app or server, so you can revoke one without touching the others.

A form key and an API key are different things:

|            | Form key                          | API key                                    |
| ---------- | --------------------------------- | ------------------------------------------ |
| Looks like | `k3yz8q2m4n6p0r5t7v9w`            | `nfa_` and 40 more characters              |
| Used in    | Your form's endpoint, `/s/{key}`  | The `Authorization` header of API requests |
| Public     | Yes, it is in your website's code | No, keep it secret                         |
| Can        | Send submissions to one form      | Manage every form and submission in a team |

## What a key can do

A key can use the [account, forms and submissions endpoints](/docs/api#endpoints) in its team, including deleting forms and submissions.

It can't:

* manage teams, members or invites,
* change billing or plans,
* connect, change or test integrations,
* read analytics,
* create, list or revoke API keys,
* change your profile or delete your account.

Those stay in the dashboard, where you are signed in.

## Keys and teams

A key works in the team you picked when you created it, no matter which team is open in the dashboard.

* If you leave a team or are removed from it, your keys for that team are deleted and stop working.
* If a team is deleted, every key for it is deleted too.
* If you delete your account, all your keys are deleted.

To use the API in two teams, create a key in each.

## Revoke a key

In **Account**, find the key under **API keys** and choose **Revoke**. It stops working right away, and requests that use it get `401`.

Revoke a key as soon as you think someone else has seen it.

## Last used

Each key shows when it was last used, which helps you find keys that nothing uses anymore. The time is updated at most once an hour, so a key that is in use can show a time up to an hour old.

## Limits

| Limit            | Value          |
| ---------------- | -------------- |
| Keys per account | 25             |
| Requests per key | 120 a minute   |
| Key name         | 100 characters |

# Account API

Check an API key and read the account, team, plan and monthly usage it works with through GET /v1/me.

```http
GET https://api.nisuform.com/v1/me
```

Returns the account that owns the key and the team the key works in. Call it to check that a key is valid, or to read the team's usage before a big job.

```sh
curl https://api.nisuform.com/v1/me \
  -H "Authorization: Bearer $NISUFORM_API_KEY"
```

```json
{
  "id": "5b1e0c7a-2f64-4d3b-9a1e-8c7d6f5e4b3a",
  "email": "jane@example.com",
  "username": "jane",
  "avatarUrl": null,
  "createdAt": "2026-09-01T08:00:00.000Z",
  "plan": "pro",
  "usage": { "used": 1240, "limit": 5000 },
  "formLimit": null,
  "activeTeamId": "2f6b7c1e-9a4d-4c3e-8b21-7d5e6f4a3b2c",
  "teams": [
    {
      "id": "2f6b7c1e-9a4d-4c3e-8b21-7d5e6f4a3b2c",
      "name": "Acme",
      "role": "owner",
      "plan": "pro",
      "isPersonal": false,
      "avatarUrl": null
    }
  ]
}
```

## Fields

| Field          | Type            | Description                                                                                                          |
| -------------- | --------------- | -------------------------------------------------------------------------------------------------------------------- |
| `id`           | string          | Your user ID.                                                                                                        |
| `email`        | string          | Your email address.                                                                                                  |
| `username`     | string or null  | Your username.                                                                                                       |
| `avatarUrl`    | string or null  | Your profile picture.                                                                                                |
| `createdAt`    | string          | When you signed up.                                                                                                  |
| `plan`         | `free` or `pro` | The plan of the key's team.                                                                                          |
| `usage.used`   | number          | Submissions the team received this month, across its forms.                                                          |
| `usage.limit`  | number          | The team's monthly submission limit.                                                                                 |
| `formLimit`    | number or null  | How many forms the team can have, or `null` for no limit on Pro.                                                     |
| `activeTeamId` | string          | The team the key works in.                                                                                           |
| `teams`        | array           | Only the key's team, with its `id`, `name`, your `role` (`owner` or `member`), `plan`, `isPersonal` and `avatarUrl`. |

Usage resets on the first day of each month in UTC. See [Limits](/docs/reference/limits) for the numbers on each plan.

# Forms API

List, create, update, duplicate and delete forms, rotate form keys and send test submissions with the Nisuform API.

Every request needs an [API key](/docs/api/keys) and works in the key's team.

## The form object

```json
{
  "id": "2f6b7c1e-9a4d-4c3e-8b21-7d5e6f4a3b2c",
  "name": "Website contact",
  "type": "contact",
  "emoji": "✉️",
  "key": "k3yz8q2m4n6p0r5t7v9w",
  "endpoint": "https://api.nisuform.com/s/k3yz8q2m4n6p0r5t7v9w",
  "status": "active",
  "closedReason": null,
  "notifyEnabled": true,
  "notifyEmail": null,
  "fields": [
    { "id": "name", "type": "text", "label": "Name", "required": true },
    { "id": "email", "type": "email", "label": "Email", "required": true },
    { "id": "message", "type": "textarea", "label": "Message", "required": true }
  ],
  "createdAt": "2026-09-29T10:00:00.000Z",
  "updatedAt": "2026-09-29T10:00:00.000Z"
}
```

The example is shortened. A form has these fields:

| Field                                  | Description                                                                                                                                                    |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                                   | The form ID, used in API paths.                                                                                                                                |
| `name`                                 | The name shown in the dashboard and in notification emails.                                                                                                    |
| `type`                                 | `contact`, `waitlist`, `feedback`, `rsvp` or `custom`. Picks the analytics summary.                                                                            |
| `emoji`                                | The form's icon in the dashboard, or `null`.                                                                                                                   |
| `key`                                  | The public form key.                                                                                                                                           |
| `endpoint`                             | The URL your form posts to, `https://api.nisuform.com/s/{key}`.                                                                                                |
| `status`                               | `active` or `paused`.                                                                                                                                          |
| `closedReason`                         | Why the form stopped taking submissions: `manual`, `max_submissions`, `auto_close_date`, or `null` while it is open.                                           |
| `maxSubmissions`                       | Close after this many submissions, or `null`.                                                                                                                  |
| `autoCloseAt`                          | Close at this time, or `null`.                                                                                                                                 |
| `closedMessage`                        | Pro. Shown to visitors after the form closed, or `null` for the default.                                                                                       |
| `notifyEnabled`                        | Whether new submissions are emailed.                                                                                                                           |
| `notifyEmail`                          | Pro. Where notifications go, or `null` for the team owner's email.                                                                                             |
| `notifySubject`                        | Subject of notification emails. Supports [placeholders](/docs/submissions/notifications).                                                                      |
| `notifyFromName`                       | Sender name of notification emails.                                                                                                                            |
| `autoreplyEnabled`                     | Pro. Whether people who submit get an [auto-reply](/docs/submissions/auto-replies).                                                                            |
| `autoreplySubject`, `autoreplyBody`    | Pro. The auto-reply email, or `null`.                                                                                                                          |
| `completionMode`                       | What browser posts see after submitting: `default`, `message` or `redirect`. See [After submit](/docs/forms/after-submit).                                     |
| `completionTitle`, `completionMessage` | Pro. Your thank-you page text, or `null`.                                                                                                                      |
| `redirectUrl`                          | Pro. Where browser posts are sent after submitting, or `null`.                                                                                                 |
| `fields`                               | The form's fields, used to validate answers and label them. `null` accepts any fields. See [Fields and validation](/docs/forms/fields).                        |
| `design`                               | Look and copy of the styled embed from the [form builder](/docs/forms/builder): `theme`, `accent`, `title`, `description`, `submitLabel` and `successMessage`. |
| `allowedOrigins`                       | Websites allowed to submit. Empty allows every website. See [Access rules](/docs/protection/access-rules).                                                     |
| `blockedIps`                           | IP addresses whose submissions are dropped.                                                                                                                    |
| `blockedCountries`                     | Two-letter country codes whose submissions are dropped.                                                                                                        |
| `captchaEnabled`                       | Whether a [Turnstile](/docs/protection/turnstile) token is required.                                                                                           |
| `captchaProvider`                      | `turnstile` or `null`.                                                                                                                                         |
| `captchaSiteKey`                       | Your Turnstile site key, or `null`.                                                                                                                            |
| `captchaSecretKeySet`                  | Whether a Turnstile secret key is saved. The secret itself is never returned.                                                                                  |
| `dontStoreIp`                          | Whether visitors' IP addresses are left out of submissions.                                                                                                    |
| `allowUploads`                         | Pro. Whether the form accepts [file uploads](/docs/connect/file-uploads).                                                                                      |
| `uploadLimitMb`                        | Largest file size in MB.                                                                                                                                       |
| `userId`                               | Who created the form.                                                                                                                                          |
| `createdAt`, `updatedAt`               | When the form was created and last changed.                                                                                                                    |

## List forms

```http
GET /v1/forms
```

Returns the team's forms, newest first, in a shorter shape.

```json
{
  "forms": [
    {
      "id": "2f6b7c1e-9a4d-4c3e-8b21-7d5e6f4a3b2c",
      "name": "Website contact",
      "type": "contact",
      "emoji": "✉️",
      "status": "active",
      "key": "k3yz8q2m4n6p0r5t7v9w",
      "endpoint": "https://api.nisuform.com/s/k3yz8q2m4n6p0r5t7v9w",
      "createdAt": "2026-09-29T10:00:00.000Z",
      "submissionCount": 42
    }
  ]
}
```

`submissionCount` leaves out spam and test submissions.

## Create a form

```http
POST /v1/forms
```

| Body field | Required | Description                                                                                                                                |
| ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `name`     | Yes      | 1 to 200 characters.                                                                                                                       |
| `type`     | No       | `contact` (default), `waitlist`, `feedback`, `rsvp` or `custom`. Sets the starter fields and embed design. `custom` starts with no fields. |

```sh
curl https://api.nisuform.com/v1/forms \
  -H "Authorization: Bearer $NISUFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Beta waitlist","type":"waitlist"}'
```

Answers `201` with the new form. Point your form at its `endpoint`. On the Free plan, a team that already has 3 forms gets `402`.

## Get a form

```http
GET /v1/forms/{id}
```

Returns the full form object, or `404`.

## Update a form

```http
PATCH /v1/forms/{id}
```

Send only the fields you want to change. Leaving a field out keeps it as it is, and `null` clears it. Answers with the updated form.

```sh
curl -X PATCH https://api.nisuform.com/v1/forms/FORM_ID \
  -H "Authorization: Bearer $NISUFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"paused","notifySubject":"New lead: {{field.name}}"}'
```

| Body field          | Accepts                                                                                                            |
| ------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `name`              | 1 to 200 characters.                                                                                               |
| `type`              | `contact`, `waitlist`, `feedback`, `rsvp` or `custom`. Changing it keeps your fields.                              |
| `status`            | `active` or `paused`. Resuming a form clears `closedReason`.                                                       |
| `emoji`             | Up to 32 characters, or `null`.                                                                                    |
| `maxSubmissions`    | 1 to 1,000,000, or `null`.                                                                                         |
| `autoCloseAt`       | An ISO 8601 time, or `null`.                                                                                       |
| `closedMessage`     | Pro. 1 to 500 characters, or `null`.                                                                               |
| `notifyEnabled`     | `true` or `false`.                                                                                                 |
| `notifyEmail`       | Pro. An email address, or `null`.                                                                                  |
| `notifySubject`     | 1 to 500 characters.                                                                                               |
| `notifyFromName`    | 1 to 100 characters. Pro to change it from the default.                                                            |
| `autoreplyEnabled`  | `true` or `false`. Pro to turn it on.                                                                              |
| `autoreplySubject`  | Pro. 1 to 500 characters, or `null`.                                                                               |
| `autoreplyBody`     | Pro. 1 to 5,000 characters, or `null`.                                                                             |
| `completionMode`    | `default`, `message` or `redirect`.                                                                                |
| `completionTitle`   | Pro. 1 to 200 characters, or `null`.                                                                               |
| `completionMessage` | Pro. 1 to 2,000 characters, or `null`.                                                                             |
| `redirectUrl`       | Pro. An `http` or `https` URL. `null` or `""` removes it.                                                          |
| `fields`            | Up to 30 fields, or `null`. Replaces every field.                                                                  |
| `design`            | The whole design object. Replaces the current design.                                                              |
| `allowedOrigins`    | Up to 50 website addresses. Paths are dropped, so `https://example.com/contact` is saved as `https://example.com`. |
| `blockedIps`        | Up to 1,000 IP addresses.                                                                                          |
| `blockedCountries`  | Up to 300 two-letter country codes.                                                                                |
| `captchaSiteKey`    | Your Turnstile site key, or `null`.                                                                                |
| `captchaSecretKey`  | Your Turnstile secret key, or `null`. Write only.                                                                  |
| `captchaEnabled`    | `true` or `false`. Turning it on needs a site key and a secret key, saved before or in the same request.           |
| `dontStoreIp`       | `true` or `false`.                                                                                                 |
| `allowUploads`      | `true` or `false`. Pro to turn it on.                                                                              |
| `uploadLimitMb`     | 1 to 100. Pro to change it from 10.                                                                                |

A Pro setting on a Free team answers `402` and nothing is saved.

### Fields

Each field has an `id`, which is the `name` your form sends, a `type`, a `label` and `required`. Types are `text`, `email`, `textarea`, `number`, `date`, `select`, `radio`, `checkbox`, `rating`, `tel`, `url` and `file`.

```json
{
  "fields": [
    { "id": "email", "type": "email", "label": "Email", "required": true },
    { "id": "plan", "type": "select", "label": "Plan", "required": false, "options": ["Starter", "Team"] },
    { "id": "score", "type": "rating", "label": "How likely are you to recommend us?", "required": true, "max": 10 }
  ]
}
```

| Field option             | Types             | Description                                  |
| ------------------------ | ----------------- | -------------------------------------------- |
| `placeholder`            | All               | Up to 200 characters.                        |
| `helpText`               | All               | Up to 500 characters.                        |
| `minLength`, `maxLength` | `text`            | Answer length. `textarea` takes `maxLength`. |
| `pattern`                | `text`            | A regular expression the answer must match.  |
| `min`, `max`             | `number`          | Smallest and largest allowed value.          |
| `options`                | `select`, `radio` | 1 to 100 choices.                            |
| `max`                    | `rating`          | Number of stars, 3 to 10. Defaults to 5.     |

Field IDs start with a letter and use letters, digits, `-` or `_`, up to 64 characters, and must be unique. See [Fields and validation](/docs/forms/fields) for how answers are checked.

## Delete a form

```http
DELETE /v1/forms/{id}
```

Deletes the form with all its submissions and uploaded files, and answers `{ "ok": true }`. Its endpoint stops accepting submissions right away. This can't be undone.

## Duplicate a form

```http
POST /v1/forms/{id}/duplicate
```

| Body field   | Required | Description                                      |
| ------------ | -------- | ------------------------------------------------ |
| `nameSuffix` | No       | Added to the copy's name. Defaults to `" copy"`. |

Copies the form's settings, fields, design and integrations into a new form with a new key. Google Sheets isn't copied, and a copied webhook gets its own signing secret. The copy starts open, without a submission limit or close date, and without submissions. Answers `201` with the copy. It counts toward the Free plan's form limit.

## Rotate the form key

```http
POST /v1/forms/{id}/rotate-key
```

Gives the form a new key and answers with the updated form. The old endpoint stops accepting submissions right away, so update your website with the new `endpoint` first.

## Send a test submission

```http
POST /v1/forms/{id}/test-submissions
```

Stores a sample submission marked as a test and runs the form's notifications and integrations, so you can check your setup. Answers `201` with `{ "submissionId": "..." }`. Test submissions don't count toward your monthly limit.

# Submissions API

Page through submissions, mark them read, starred or spam, delete them, download uploaded files and export CSV with the Nisuform API.

Every request needs an [API key](/docs/api/keys), and the form must be in the key's team. Otherwise the API answers `404`.

## The submission object

```json
{
  "id": "8d0f5a4e-3b9c-4f7a-9e21-6c4d2b1a0f93",
  "formId": "2f6b7c1e-9a4d-4c3e-8b21-7d5e6f4a3b2c",
  "data": {
    "name": "Jane Doe",
    "email": "jane@example.com",
    "message": "Hello!"
  },
  "meta": {
    "ip": "203.0.113.7",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...",
    "referrer": "https://example.com/contact",
    "country": "DE",
    "deviceClass": "desktop"
  },
  "read": false,
  "starred": false,
  "isSpam": false,
  "isTest": false,
  "createdAt": "2026-09-29T09:29:59.412Z"
}
```

| Field              | Description                                                                                          |
| ------------------ | ---------------------------------------------------------------------------------------------------- |
| `id`               | The submission ID.                                                                                   |
| `formId`           | The form it was sent to.                                                                             |
| `data`             | The answers, as field name and text value pairs. Special fields like `_gotcha` are never stored.     |
| `meta.ip`          | The visitor's IP address. Left out when the form doesn't store IP addresses.                         |
| `meta.userAgent`   | The visitor's browser.                                                                               |
| `meta.referrer`    | The page the form was sent from, or an empty string.                                                 |
| `meta.country`     | Two-letter country code, when known.                                                                 |
| `meta.deviceClass` | `mobile`, `desktop`, `tablet` or `bot`, when known.                                                  |
| `meta.files`       | Uploaded files, each with `name`, `mime` and `size` in bytes. Only present when files were attached. |
| `read`             | Whether it was opened or marked read.                                                                |
| `starred`          | Whether it is starred.                                                                               |
| `isSpam`           | Whether it is in the spam folder.                                                                    |
| `isTest`           | Whether it is a test submission sent from the dashboard or the API.                                  |
| `createdAt`        | When it was received.                                                                                |

When answers don't pass your form's [field checks](/docs/forms/fields), the submission is still stored, arrives unread and has an extra `data._invalid` value: a JSON string that lists each problem, like `[{"fieldId":"email","reason":"invalid_email"}]`.

## List submissions

```http
GET /v1/forms/{formId}/submissions
```

| Query parameter | Default | Description                                                                                    |
| --------------- | ------- | ---------------------------------------------------------------------------------------------- |
| `filter`        | `all`   | `all` (everything except spam), `unread` (unread and not spam), `starred` or `spam`.           |
| `page`          | `1`     | The page to return.                                                                            |
| `pageSize`      | `15`    | Submissions per page, 1 to 100.                                                                |
| `around`        |         | A submission ID. Returns the page that holds it instead of `page`, when it matches the filter. |

```sh
curl "https://api.nisuform.com/v1/forms/FORM_ID/submissions?filter=unread&pageSize=100" \
  -H "Authorization: Bearer $NISUFORM_API_KEY"
```

Submissions come newest first. Each item is a submission object with a `preview`, the longest answer cut to a short snippet.

```json
{
  "items": [
    {
      "id": "8d0f5a4e-3b9c-4f7a-9e21-6c4d2b1a0f93",
      "preview": "Hello!",
      "data": { "name": "Jane Doe", "email": "jane@example.com", "message": "Hello!" },
      "read": false
    }
  ],
  "page": 1,
  "pageSize": 100,
  "pageCount": 1,
  "total": 1,
  "unreadCount": 1,
  "asOf": "2026-09-29T10:00:00.000Z"
}
```

| Field         | Description                                                                                                  |
| ------------- | ------------------------------------------------------------------------------------------------------------ |
| `items`       | The submissions on this page.                                                                                |
| `page`        | The page you got. Asking for a page past the end returns the last page.                                      |
| `pageSize`    | Submissions per page.                                                                                        |
| `pageCount`   | Number of pages, at least 1.                                                                                 |
| `total`       | Submissions that match the filter.                                                                           |
| `unreadCount` | Unread submissions in the form, whatever the filter.                                                         |
| `asOf`        | When the list was read. Pass it to [update](#update-submissions) or [delete](#delete-submissions) by filter. |

### Page through every submission

```js
const API = 'https://api.nisuform.com/v1'
const headers = { Authorization: `Bearer ${process.env.NISUFORM_API_KEY}` }

async function allSubmissions(formId) {
  const seen = new Map()
  for (let page = 1; ; page++) {
    const response = await fetch(`${API}/forms/${formId}/submissions?page=${page}&pageSize=100`, { headers })
    if (!response.ok) throw new Error(`Nisuform answered ${response.status}`)
    const body = await response.json()
    for (const item of body.items) seen.set(item.id, item)
    if (page >= body.pageCount) return [...seen.values()]
  }
}
```

Submissions that arrive while you page move older ones back, so the same submission can show up on two pages. Keep them by `id`, as above. For a complete copy in one request, use the [CSV export](#export-as-csv).

## Get a submission

```http
GET /v1/forms/{formId}/submissions/{id}
```

Returns one submission object, or `404`. Getting a submission doesn't mark it read.

## Update submissions

```http
PATCH /v1/forms/{formId}/submissions
```

Sets `read`, `starred` or `isSpam` on many submissions at once. Pass at least one of them, and a `target`.

| Body field | Description                                                                                                                                                                         |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `target`   | Either `{ "ids": [...] }` with 1 to 1,000 submission IDs, or `{ "filter": "...", "asOf": "..." }` to act on every submission that matches the filter and was received up to `asOf`. |
| `read`     | `true` or `false`.                                                                                                                                                                  |
| `starred`  | `true` or `false`.                                                                                                                                                                  |
| `isSpam`   | `true` moves them to spam, `false` moves them back.                                                                                                                                 |

```sh
curl -X PATCH https://api.nisuform.com/v1/forms/FORM_ID/submissions \
  -H "Authorization: Bearer $NISUFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target":{"ids":["8d0f5a4e-3b9c-4f7a-9e21-6c4d2b1a0f93"]},"read":true}'
```

Answers `{ "count": 1 }` with the number of submissions that changed. Submissions that already had the value aren't counted. IDs from other forms are ignored.

To mark everything read that you just fetched, pass the list's `asOf`, so submissions that arrived in the meantime stay unread:

```json
{ "target": { "filter": "unread", "asOf": "2026-09-29T10:00:00.000Z" }, "read": true }
```

## Delete submissions

```http
DELETE /v1/forms/{formId}/submissions
```

Takes a JSON body with the same `target` as [update](#update-submissions), and deletes the submissions with their uploaded files. Answers `{ "count": 3 }` with the number deleted. This can't be undone.

```sh
curl -X DELETE https://api.nisuform.com/v1/forms/FORM_ID/submissions \
  -H "Authorization: Bearer $NISUFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target":{"filter":"spam","asOf":"2026-09-29T10:00:00.000Z"}}'
```

Deleted submissions still count toward this month's usage.

## Download a file

```http
GET /v1/forms/{formId}/submissions/{id}/files/{index}
```

`index` is the file's position in `meta.files`, starting at 0. Answers with a signed link:

```json
{
  "url": "https://api.nisuform.com/attachments/...",
  "name": "brief.pdf",
  "mime": "application/pdf",
  "expiresAt": "2026-09-29T10:15:00.000Z"
}
```

The link works without an API key and expires after 15 minutes. Ask for a new one each time you need the file.

## Export as CSV

```http
GET /v1/forms/{formId}/export.csv
```

| Query parameter | Default | Description                           |
| --------------- | ------- | ------------------------------------- |
| `filter`        | `all`   | `all`, `unread`, `starred` or `spam`. |

```sh
curl "https://api.nisuform.com/v1/forms/FORM_ID/export.csv" \
  -H "Authorization: Bearer $NISUFORM_API_KEY" \
  -o submissions.csv
```

Streams every matching submission as a CSV file, newest first, with the same columns as the [dashboard export](/docs/submissions/export). It counts as one request toward the rate limit, however many rows it has.

# Teams

Share forms with the people you work with, keep clients separate, and manage members and invites.

Forms belong to teams. Everyone on a team sees and manages the same forms, and each team has its own plan and monthly usage.

## Your personal team

Every account starts with a personal team. You own it, and it can't be deleted. If you work alone, it is all you need.

## Create more teams

Additional teams are a Pro feature. Once one of the teams you own is on Pro, you can create as many teams as you like, for example one per client or project. Open the team switcher in the dashboard and choose **Add team**.

Each new team starts on the Free plan. Plans are per team, so upgrade the teams that need Pro.

## Switch teams

Use the team switcher at the top of the dashboard. The dashboard, your forms and **New form** always work in the team you picked.

## Roles

|                                        | Owner | Member |
| -------------------------------------- | ----- | ------ |
| Create, edit and delete forms          | Yes   | Yes    |
| Read, export and delete submissions    | Yes   | Yes    |
| Connect integrations                   | Yes   | Yes    |
| Rename the team and change its picture | Yes   | No     |
| Invite and remove members              | Yes   | No     |
| Upgrade, change or cancel the plan     | Yes   | No     |
| Delete the team                        | Yes   | No     |

Each team has one owner, the person who created it. Email notifications go to the owner's account email unless a form sets its own address.

## Invite people

1. Open **Team settings** and find **Add members**.
2. Enter the person's email address.
3. Copy the invite link and send it to them yourself, by email or chat.

The link only works for that email address. The person signs in to Nisuform with that address and joins the team as a member. A team can have up to 50 pending invites, and you can revoke an invite at any time before it is accepted.

## Remove members

In **Team settings**, owners can remove any member. The member loses access to the team's forms right away. Forms and submissions stay with the team.

## Rename or delete a team

Owners can change the team's name and picture in **Team settings**. The picture can be a PNG, JPEG or WebP image up to 400 KB.

**Delete team** permanently deletes the team with all of its forms, submissions and files. If the team is on Pro, its subscription is canceled right away. To confirm, you type the team's name. It can't be undone.

# Plans and billing

Compare the Free and Pro plans, see how submissions are counted each month, and upgrade, change or cancel a plan.

Nisuform has two plans. Plans are per team, so each team has its own plan, its own monthly usage and its own subscription.

## Compare plans

|                                                      | Free               | Pro                        |
| ---------------------------------------------------- | ------------------ | -------------------------- |
| Price                                                | $0                 | $10 a month, or $84 a year |
| Submissions per month                                | 100                | 5,000                      |
| Forms                                                | 3 per team         | Unlimited                  |
| Teams                                                | Your personal team | Unlimited                  |
| Inbox, spam folder and CSV export                    | Yes                | Yes                        |
| Email notifications with a custom subject            | Yes                | Yes                        |
| Spam protection, Turnstile and access rules          | Yes                | Yes                        |
| Form builder and styled embed                        | Yes                | Yes                        |
| Notifications to any address                         | No                 | Yes                        |
| Custom sender name                                   | No                 | Yes                        |
| Auto-replies                                         | No                 | Yes                        |
| Custom thank-you message and redirects               | No                 | Yes                        |
| Custom closed message                                | No                 | Yes                        |
| File uploads                                         | No                 | Yes                        |
| Analytics                                            | No                 | Yes                        |
| Webhooks, Slack, Discord, Telegram and Google Sheets | No                 | Yes                        |

Prices are in US dollars. See the [pricing page](/pricing) for the latest prices.

## How submissions are counted

* Usage is counted per team, across all of its forms.
* It resets at the start of each calendar month, in UTC.
* Only accepted submissions count. Spam, bots, blocked senders, rejected submissions and test submissions from the dashboard don't.
* Deleting submissions doesn't give usage back.

The **Dashboard** and **Team settings** show how much of this month's usage the team has used.

## Near the limit

When a team reaches 95% of its monthly submissions, successful JSON responses include `"warning": "near_limit"`. See [Responses](/docs/connect/javascript#responses).

## Over the limit

When a team reaches its limit, new submissions are rejected with `402` and `quota_exceeded` until the next month starts. Nothing is lost silently: visitors see that the form couldn't accept their submission, and your code gets the error.

On the first of each month, Free teams that turned submissions away get an email with how many they missed. Pro teams get a small buffer above 5,000, so a busy day doesn't cut a form off right at the limit.

## Upgrade

Only the team's owner can upgrade. Choose **Upgrade to Pro** in **Team settings** or anywhere the dashboard offers it, and pay with the secure checkout. Payments are handled by [Polar](https://polar.sh), our merchant of record, which takes care of invoices and sales tax.

Pro features turn on as soon as the payment goes through. If the dashboard still shows Free after a minute, reload the page.

## Manage or cancel

In **Team settings**, **Plan & usage**, the owner can open the billing portal to update the payment method, download invoices, and change or cancel the subscription.

When you cancel, the team keeps Pro until the end of the period you paid for, then moves to Free.

## What happens on the Free plan

When a team moves from Pro to Free, nothing is deleted. Your forms, submissions, integrations and settings are kept, and Pro features stop applying:

* Forms above the Free limit keep working. You just can't create new forms until the team is under the limit.
* Integrations and auto-replies pause.
* Notifications go to the owner's account email with the default sender name.
* File uploads are skipped, and visitors see the default thank-you and closed pages.
* The monthly limit goes back to 100.

Upgrading again brings everything back as it was.

## Deleting a team or account

Deleting a Pro team, or an account that owns one, cancels the subscription right away. You won't be charged again, and the rest of the current period isn't refunded.

# Your account

Sign in, update your profile and email address, and delete your account.

## Sign in

Sign in at [app.nisuform.com](https://app.nisuform.com) with **Continue with email** or **Continue with Google**. There are no passwords.

With email, Nisuform sends you a sign-in link. Open it on the same device and browser, and you are signed in. If it doesn't arrive within a minute, check your spam folder or choose **Use a different email** to try again.

Your first sign-in creates your account and your personal team on the Free plan.

## Profile

Open **Account** from the menu under your picture:

* **Profile picture**: a PNG, JPEG or WebP image, cropped to a square.
* **Username**: 3 to 30 lowercase letters, numbers or hyphens. Teammates see it in member lists.

## Change your email address

In **Account**, choose **Edit profile** and enter the new address. Nisuform sends a confirmation link to it, and your email changes after you confirm. Until then, you keep signing in with the old address.

Your email address is where notifications go for forms in teams you own, unless a form sets its own address. See [Email notifications](/docs/submissions/notifications).

## API keys

API keys let your own code use the [Nisuform API](/docs/api) to manage forms and submissions. Create and revoke them in **Account**, under **API keys**. Each key works in one of your teams. See [API keys](/docs/api/keys).

## Billing

Billing is per team, not per account. Each team has its own plan and subscription. See [Plans and billing](/docs/account/billing).

## Delete your account

In **Account**, choose **Delete account** and type your email address to confirm. This permanently deletes:

* your profile,
* your API keys,
* every team you own, with all of their forms, submissions and uploaded files.

Members of those teams lose access. Forms in other people's teams that you worked on stay with those teams. Pro subscriptions of the teams you own are canceled right away. You won't be charged again, and the rest of the current billing period isn't refunded.

Export anything you want to keep first. See [Export submissions](/docs/submissions/export).

# Privacy and data

What Nisuform stores with each submission, how to limit it, how long data is kept and how deletion works.

You decide what your forms collect. Nisuform stores the answers your form sends and a few details about each request, and gives you settings to collect less.

## What is stored with a submission

| Data                        | Stored              | Why                                                                 |
| --------------------------- | ------------------- | ------------------------------------------------------------------- |
| The answers your form sends | Always              | This is the submission.                                             |
| Uploaded files              | When uploads are on | Stored privately, see [File uploads](/docs/connect/file-uploads).   |
| Page the form was sent from | Always              | Shows where submissions come from.                                  |
| Browser and device type     | Always              | Helps spot bots and shows devices in analytics.                     |
| Country                     | Always              | Derived from the request, used for analytics and blocked countries. |
| IP address                  | Unless turned off   | Lets you block abusive senders.                                     |

Special fields like `_gotcha`, `_elapsed` and the Turnstile token are never stored. Submissions dropped as bots or blocked are not stored at all.

## Stop storing IP addresses

Turn off **Store IP addresses** in the form's **Settings**, **Spam protection**. New submissions are stored without an IP address. Rate limits and IP blocking keep working, because they check the address while the request is handled without saving it.

## Collect only what you need

* Ask only for the fields you use. Every field you add is data you are responsible for.
* Link to your privacy policy from the form, and add a **Checkbox** field for consent where the law requires one.
* Don't collect passwords, card numbers or other highly sensitive data through forms.

## Security

* Data is encrypted in transit and at rest.
* Uploaded files are checked by their contents, stored privately and only shared through links that expire after 15 minutes.
* Webhooks are signed, so your server can reject anything that didn't come from Nisuform.
* Form keys only allow sending submissions. They can't read data.

## Retention and deletion

Submissions are kept until you delete them. There is no automatic expiry.

| You delete   | What is removed                                                   |
| ------------ | ----------------------------------------------------------------- |
| A submission | The submission and its files.                                     |
| A form       | The form, all of its submissions and files, and its integrations. |
| A team       | All of its forms, submissions and files.                          |
| Your account | Your profile and every team you own.                              |

Deleted data is removed within 30 days and purged from encrypted backups within a further 90 days. Export anything you want to keep first.

## Data Processing Agreement

If you collect personal data from people in the EU or UK, Nisuform processes it on your behalf. The [Data Processing Agreement](/dpa) is included with every account. It lists our subprocessors and security measures. See also the [Privacy Policy](/privacy).

## Requests from the people who filled in your form

When someone asks you to see or delete their data, find their submissions in the inbox or in a [CSV export](/docs/submissions/export), then send them a copy or delete them. Contact [support@nisuform.com](mailto:support@nisuform.com) if you need help.

# Submit endpoint

Full reference for POST /s/{key}, the one public endpoint every Nisuform form posts to, with request formats, responses and headers.

```http
POST https://api.nisuform.com/s/{key}
```

This is the only endpoint your forms need. It is public, needs no API key and accepts requests from any website.

## Path

| Parameter | Description                                                                                                          |
| --------- | -------------------------------------------------------------------------------------------------------------------- |
| `key`     | The form key. Letters, digits and hyphens, starting with a letter or digit, up to 64 characters. Not case sensitive. |

## Request body

| Content type                        | Use it for                                                                           |
| ----------------------------------- | ------------------------------------------------------------------------------------ |
| `application/x-www-form-urlencoded` | Plain HTML forms. The browser's default.                                             |
| `multipart/form-data`               | HTML forms with `enctype="multipart/form-data"`, `FormData` bodies and file uploads. |
| `application/json`                  | `fetch` and server-side requests. The body must be a JSON object.                    |

Any other content type, or JSON that can't be parsed, is rejected with `415` and `unsupported_media_type`.

Fields are name and value pairs:

* Up to 50 fields. Extra fields are ignored.
* Names up to 200 characters. A name ending in `[]` is saved without the brackets.
* Values up to 10,000 characters. Longer values are cut.
* Repeated names are joined into one comma-separated value, and so are JSON arrays.
* Up to 200 KB per request, or 25 MB on Pro forms with file uploads turned on.

Names that start with an underscore, and the captcha token names, are [special fields](/docs/connect/special-fields). They change how the submission is handled and are never stored.

## Response format

The response depends on the request's `Accept` header:

| `Accept` includes `text/html`          | Response                          |
| -------------------------------------- | --------------------------------- |
| Yes, like a normal browser form submit | An HTML page, or a `303` redirect |
| No, like `fetch`, cURL or a server     | JSON                              |

Send `Accept: application/json` from your code to always get JSON.

## JSON responses

```ts
type SubmitSuccess = {
  ok: true
  submissionId?: string
  warning?: 'near_limit'
}

type SubmitFailure = {
  ok: false
  error: string
  message: string
}
```

| Status       | Body                                                             | When                                                                              |
| ------------ | ---------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `200`        | `{ "ok": true, "submissionId": "..." }`                          | The submission was stored.                                                        |
| `200`        | `{ "ok": true, "submissionId": "...", "warning": "near_limit" }` | Stored, and the team has used 95% of its monthly submissions.                     |
| `200`        | `{ "ok": true }`                                                 | Dropped by the honeypot, the fill-time check or a block list. Nothing was stored. |
| `4xx`, `5xx` | `{ "ok": false, "error": "...", "message": "..." }`              | Rejected. See [Errors](/docs/reference/errors).                                   |

Submissions that went to the spam folder answer like stored submissions, with a `submissionId`.

## HTML responses

| Status       | Page                                                                      |
| ------------ | ------------------------------------------------------------------------- |
| `200`        | The thank-you page, or your custom message on Pro.                        |
| `303`        | Redirect to your redirect URL or to `_redirect`, on Pro.                  |
| `4xx`, `5xx` | A page with the reason and a link back to the page the visitor came from. |

## Headers

| Header                           | Sent                                                                    |
| -------------------------------- | ----------------------------------------------------------------------- |
| `Access-Control-Allow-Origin: *` | On every response, so browsers can read it from any website.            |
| `Retry-After`                    | On `429`, with the number of seconds to wait.                           |
| `Location`                       | On `303`, with the redirect URL.                                        |
| `x-request-id`                   | On every response. Include it when you contact support about a request. |

`OPTIONS` requests get `204` with the CORS headers, so preflight requests from `fetch` succeed. Browsers may send the `Content-Type` and `Accept` request headers. The response headers above, other than `Content-Type`, are only readable outside the browser, like from a server or cURL.

## Other methods

`GET` and other methods answer `405` with `method_not_allowed`. Browsers that open the endpoint see a short page explaining that it is a form endpoint.

## Processing order

1. Find the form by its key, or answer `404`.
2. Drop submissions from blocked IP addresses and countries.
3. Check allowed websites, or answer `403`.
4. Check rate limits, or answer `429`.
5. Read and parse the body, or answer `413` or `415`.
6. Drop bots caught by the honeypot or the fill-time check.
7. Reject empty submissions with `422`, and invalid files with `400`, `413` or `415`.
8. Reject submissions to closed forms with `423`.
9. Verify the Turnstile token, or answer `403`.
10. Mark link spam and duplicates as spam.
11. Check the monthly limit, or answer `402`.
12. Validate answers against the form's fields, store the submission and its files, and queue notifications.

## Examples

```sh
curl https://api.nisuform.com/s/YOUR_FORM_KEY \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"email":"jane@example.com","message":"Hello!"}'
```

```sh
curl https://api.nisuform.com/s/YOUR_FORM_KEY \
  -H 'Accept: application/json' \
  --data-urlencode 'email=jane@example.com' \
  --data-urlencode 'message=Hello!'
```

```sh
curl https://api.nisuform.com/s/YOUR_FORM_KEY \
  -H 'Accept: application/json' \
  -F 'email=jane@example.com' \
  -F 'attachment=@brief.pdf'
```

# Errors

Every error code the submit endpoint returns, what causes it and how to fix it.

Rejected submissions answer with an HTTP status and, for JSON requests, a body like this:

```json
{ "ok": false, "error": "rate_limited", "message": "Too many requests. Try again shortly" }
```

Branch on `error`, which never changes. `message` is written for the people filling in your form, so you can show it to them as is. Browser form posts get the same outcome as a page with a link back to your site.

Errors from the API that manages forms and submissions look different. See [API errors](/docs/api#errors).

## Error codes

| Status | `error`                    | Message                                                         | What to do                                                                                                                            |
| ------ | -------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `too_many_files`           | Too many files attached                                         | Send at most 5 files per submission.                                                                                                  |
| `402`  | `quota_exceeded`           | This form has reached its monthly submission limit              | The team used its monthly submissions. [Upgrade](/docs/account/billing) or wait for next month.                                       |
| `403`  | `origin_not_allowed`       | This form does not accept submissions from this website         | Add the site to the form's [allowed websites](/docs/protection/access-rules).                                                         |
| `403`  | `captcha_failed`           | Captcha verification failed. Complete the captcha and try again | Send a valid Turnstile token. See [Cloudflare Turnstile](/docs/protection/turnstile).                                                 |
| `404`  | `form_not_found`           | Form not found                                                  | Check the key in your endpoint. It may have been rotated or the form deleted.                                                         |
| `405`  | `method_not_allowed`       | This is a nisuform form endpoint...                             | Send a `POST` request.                                                                                                                |
| `413`  | `payload_too_large`        | Submission too large                                            | Keep the request under 200 KB, or 25 MB with file uploads.                                                                            |
| `413`  | `attachment_too_large`     | A file exceeds the upload size limit                            | Send smaller files, or raise **Size limit per file**.                                                                                 |
| `415`  | `unsupported_media_type`   | Unsupported content type                                        | Send JSON, URL-encoded or multipart data, and valid JSON.                                                                             |
| `415`  | `attachment_type_rejected` | A file type is not allowed                                      | Send JPEG, PNG, WebP, GIF or PDF files.                                                                                               |
| `422`  | `empty_submission`         | The submission is empty. Fill in the form and try again         | Send at least one non-empty field or a file.                                                                                          |
| `423`  | `form_closed_manual`       | This form is closed and not accepting submissions               | The form is paused. Resume it in **Settings**, **General**.                                                                           |
| `423`  | `form_max_submissions`     | This form has reached its maximum number of submissions         | Raise or clear **Maximum submissions**.                                                                                               |
| `423`  | `form_auto_close`          | This form closed automatically on its scheduled date            | Clear or move the **Close on** date.                                                                                                  |
| `429`  | `rate_limited`             | Too many requests. Try again shortly                            | Wait a minute, or the seconds in the `Retry-After` header when you can read it. See [rate limits](/docs/protection/spam#rate-limits). |
| `500`  | `upload_failed`            | Uploading your attachment failed. Please try again              | Nothing was stored. Try again.                                                                                                        |
| `500`  | `internal_error`           | Something went wrong                                            | Try again. If it keeps happening, contact support with the `x-request-id` header.                                                     |

On Pro, the three `423` errors use your own **Closed message** when you set one. See [Pause and close a form](/docs/forms/closing).

## Errors that look like success

Some submissions are dropped on purpose but still answer `200` with `{ "ok": true }` and no `submissionId`, so bots can't tell they were caught:

* The `_gotcha` honeypot had a value.
* `_elapsed` was under 2 seconds.
* The sender's IP address or country is blocked for the form.

If your own test submissions are missing from the inbox, check these first. See [Troubleshooting](/docs/reference/troubleshooting).

## Validation problems are not errors

Answers that don't match your form's fields don't cause an error. The submission is stored and marked in the inbox. See [Fields and validation](/docs/forms/fields).

# Limits

Every limit in Nisuform in one place, from monthly submissions and rate limits to field counts and file sizes.

## Plans

|                                 | Free               | Pro       |
| ------------------------------- | ------------------ | --------- |
| Submissions per month, per team | 100                | 5,000     |
| Forms per team                  | 3                  | Unlimited |
| Teams                           | Your personal team | Unlimited |
| File uploads                    | No                 | Yes       |

See [Plans and billing](/docs/account/billing) for everything else that differs.

## Submissions

| Limit                          | Value                          |
| ------------------------------ | ------------------------------ |
| Request size                   | 200 KB                         |
| Request size with file uploads | 25 MB                          |
| Fields per submission          | 50                             |
| Field name length              | 200 characters                 |
| Value length                   | 10,000 characters              |
| Files per submission           | 5                              |
| Size per file                  | 10 MB by default, set per form |
| File types                     | JPEG, PNG, WebP, GIF, PDF      |

## Rate limits

| Limit                                 | Value       |
| ------------------------------------- | ----------- |
| From one IP address, across all forms | 30 a minute |
| From one IP address, to one form      | 5 a minute  |
| To one form, from everyone            | 200 an hour |
| Fastest fill time                     | 2 seconds   |

## Forms

| Limit                                         | Value          |
| --------------------------------------------- | -------------- |
| Fields in the form builder                    | 30             |
| Options per dropdown or multiple choice field | 100            |
| Stars in a rating field                       | 3 to 10        |
| Field name length                             | 64 characters  |
| Allowed websites                              | 50             |
| Blocked IP addresses                          | 1,000          |
| Maximum submissions setting                   | 1 to 1,000,000 |

## Email

| Limit                                      | Value                                           |
| ------------------------------------------ | ----------------------------------------------- |
| Notification subject                       | 250 characters after placeholders are filled in |
| Auto-reply message                         | 5,000 characters                                |
| Placeholders filled in per auto-reply      | 5 fields                                        |
| Auto-replies to the same address, per form | 1 every 24 hours                                |

## Teams and account

| Limit                     | Value                                         |
| ------------------------- | --------------------------------------------- |
| Pending invites per team  | 50                                            |
| Team and profile pictures | PNG, JPEG or WebP, up to 400 KB               |
| Username                  | 3 to 30 lowercase letters, numbers or hyphens |

## API

| Limit                                  | Value        |
| -------------------------------------- | ------------ |
| Requests per API key                   | 120 a minute |
| API keys per account                   | 25           |
| Submissions per page                   | 100          |
| Submissions per update or delete by ID | 1,000        |

See [API overview](/docs/api) for how the API works.

## Links and deliveries

| Limit                                 | Value                                    |
| ------------------------------------- | ---------------------------------------- |
| File download links                   | Expire after 15 minutes                  |
| Telegram connect links                | Expire after 30 minutes                  |
| Webhook and integration response time | 10 seconds, 20 seconds for Google Sheets |
| Delivery retries                      | About 2 hours                            |
| Duplicate detection window            | 24 hours                                 |

# Troubleshooting

Fixes for the most common problems, from missing submissions and emails to CORS errors, closed forms and failing integrations.

Start with **Send a test** on the form's **Setup** tab. If the test shows up in your inbox and your email, Nisuform is working, and the problem is in how your site sends the form.

<Accordion title="My submission isn't in the inbox">
  * Check the **Spam** filter in the inbox. Messages with many links and exact repeats land there.
  * Check the response. `{ "ok": true }` without a `submissionId` means the submission was dropped on purpose: the hidden `_gotcha` field had a value, `_elapsed` was under 2 seconds, or your IP address or country is blocked for the form. Browser autofill and password managers sometimes fill in a honeypot that isn't hidden with CSS. See [Special fields](/docs/connect/special-fields#_gotcha).
  * Check that you are looking at the right form and the right team. The endpoint in your HTML must match the one on the form's **Setup** tab.
  * Check the response status. Anything other than `200` means it was rejected, and the error says why. See [Errors](/docs/reference/errors).
</Accordion>

<Accordion title="Submissions arrive but some answers are missing">
  * Every input needs a `name` attribute. Inputs without one are never sent by the browser.
  * Disabled inputs are never sent either. Use `readonly` if the visitor shouldn't edit a value.
  * Names that start with an underscore are not stored. Rename the field.
  * File inputs need `enctype="multipart/form-data"` on the form, and uploads turned on for the form, which is Pro.
</Accordion>

<Accordion title="I don't get email notifications">
  * Check your spam or junk folder, and mark the email as not spam.
  * In **Settings**, **Email**, check that **Email me new submissions** is on and **Send to** is right. On the Free plan, emails go to the team owner's account email.
  * Spam submissions never send notifications.
  * See [Email notifications](/docs/submissions/notifications).
</Accordion>

<Accordion title="The browser console shows a CORS error">
  * Send only the `Content-Type` and `Accept` headers. Other headers, like `Authorization` or custom `X-` headers, fail the preflight check.
  * Don't send credentials. Leave `credentials` at its default.
  * Check the URL. A typo in the path answers `404`, which the browser may report as a CORS error.
  * A `403` with `origin_not_allowed` means the site isn't in the form's allowed websites.
</Accordion>

<Accordion title="My form shows This form is closed">
  The form is paused, reached its **Maximum submissions**, or passed its **Close on** date. Check the notice in **Settings**, **Submissions**, **Limits** and in **General**. See [Pause and close a form](/docs/forms/closing).
</Accordion>

<Accordion title="Visitors get 402 or quota_exceeded">
  The team used all of this month's submissions. Usage resets on the first of the month in UTC, or you can [upgrade to Pro](/docs/account/billing) for 5,000 a month.
</Accordion>

<Accordion title="Visitors get 429 or rate_limited">
  Someone sent more than 5 submissions a minute to the form from one IP address, more than 30 a minute to your forms, or the form received more than 200 in an hour. Real visitors rarely hit these limits. If you post from your own server, every request shares your server's IP address. See [Submitting from a server](/docs/connect/javascript#submitting-from-a-server).
</Accordion>

<Accordion title="Every submission fails with captcha_failed">
  * The Turnstile widget must be inside the `<form>` element.
  * The site key in your page and the keys in the form's settings must belong to the same widget.
  * Your site's hostname must be in the widget's hostname list in Cloudflare.
  * With `fetch`, send the whole `FormData`, or add the `cf-turnstile-response` value yourself.

  See [Cloudflare Turnstile](/docs/protection/turnstile).
</Accordion>

<Accordion title="The page shows a 405 error">
  You opened the endpoint in the browser, or the form uses `method="GET"`. The endpoint only accepts `POST`. Set `method="POST"` on the form.
</Accordion>

<Accordion title="The redirect doesn't happen">
  * Redirects are a Pro feature.
  * `fetch` requests that ask for JSON are never redirected. Redirect in your own code after `ok` is `true`.
  * A `_redirect` URL must be on the site that sent the form or on one of its allowed websites. Otherwise it is ignored.
</Accordion>

<Accordion title="An integration shows Failing">
  The Integrations tab shows the reason, like "Slack answered 404". Usually the webhook was deleted, the bot was removed or the URL changed. Fix it on the other side, or reconnect, and choose **Send test**. The status clears after the next successful delivery. See the page for [each integration](/docs/integrations).
</Accordion>

<Accordion title="I changed the form but my site shows the old one">
  The embed code is a copy of the form at the time you copied it. After you change fields or the design in the builder, save, copy the code again and replace it on your site. Copy it again after turning Turnstile on or changing the redirect URL too, because both are part of the embed. Other settings, like notifications, spam protection and integrations, apply right away without new code.
</Accordion>

## Still stuck?

Email [support@nisuform.com](mailto:support@nisuform.com) with the form's name, what you expected and what happened. Include the `x-request-id` response header from your browser's network tab if you have it. A person replies within one business day, usually much faster.

# How to Handle HTML Forms Without a Backend

An HTML form needs a URL that accepts its POST request. Here are four ways to get one on a static site, with working code, spam protection and a checklist.

Published 2026-09-30.

**Short answer:** set your form's `action` to a form backend endpoint and its `method` to `POST`. The service receives each submission, filters spam, stores it and emails you. There is no server code to write or host, and the form works without JavaScript.

```html title="contact.html"
<form action="https://api.nisuform.com/s/YOUR_FORM_KEY" method="POST">
  <label for="email">Email</label>
  <input id="email" type="email" name="email" required>

  <label for="message">Message</label>
  <textarea id="message" name="message" required></textarea>

  <input type="text" name="_gotcha" tabindex="-1" autocomplete="off" style="display:none">
  <button type="submit">Send</button>
</form>
```

With [Nisuform](https://nisuform.com), that is the whole setup. The rest of this guide explains what happens when a form is submitted, compares the four common ways to handle it, and covers spam, validation and what visitors see afterwards.

## Why does an HTML form need a backend?

When someone presses submit, the browser collects every field that has a `name` and sends them to the URL in the form's `action`, usually as a `POST` request. Something at that URL has to accept the request and do something useful with it.

A static host like GitHub Pages, Netlify, Vercel or Cloudflare Pages is built to serve files. Unless you add something, nothing on it is listening for your form's `POST`, so the submission goes nowhere.

Whatever receives the submission also has to:

* check the fields and reject anything malformed
* filter out bots and spam
* store the submission, so nothing is lost if an email bounces
* tell you about it, usually by email
* show the visitor a thank-you page

That list is the backend. The only question is who runs it.

## Four ways to handle a form without your own server

| Approach                     | Setup time    | Spam protection    | Where submissions go          | Upkeep                                       |
| ---------------------------- | ------------- | ------------------ | ----------------------------- | -------------------------------------------- |
| `mailto:` action             | Seconds       | None               | The visitor's email app       | None, but many submissions never arrive      |
| Embedded form builder        | Minutes       | Built in           | The builder's dashboard       | Low, but it is their form, not yours         |
| Your own serverless function | Hours to days | Whatever you build | Wherever your code sends them | You own the code, email setup and spam rules |
| Form backend service         | Minutes       | Built in           | Inbox, email and webhooks     | None                                         |

### 1. A mailto: action

`<form action="mailto:you@example.com">` looks like the easy way out. On submit, the browser tries to open the visitor's email app with the answers pasted into a new message. Visitors who only use webmail, or who are on a shared computer, get an error or nothing at all. You never find out the message was lost, and your address sits in the page source for scrapers to collect.

### 2. An embedded form builder

Google Forms, Typeform and Tally host the entire form. You paste an embed code or share a link, and they take care of submissions. It is quick, but the form is theirs: it looks like their product, loads their scripts, and ignores your own markup and CSS.

### 3. A serverless function you write yourself

Most hosts can run small functions, so you can write the backend yourself. A minimal Cloudflare Worker that accepts the form looks like this:

```js title="worker.js"
export default {
  async fetch(request) {
    if (request.method !== 'POST') {
      return new Response('Method not allowed', { status: 405 })
    }
    const data = Object.fromEntries(await request.formData())
    await sendEmail(data)
    return Response.redirect('https://example.com/thanks', 303)
  },
}
```

The function is short. Everything around it is not. `sendEmail` needs an email provider, a verified sending domain and SPF and DKIM records. You still have to add spam filtering and rate limits, keep submissions somewhere when an email fails, handle CORS for `fetch` requests and build a way to read old submissions. That is worth it when forms are core to your product. For a contact form, it is a lot of code to own.

### 4. A form backend service

A form backend gives you a URL that already does all of the above. You keep your own HTML and CSS and change one attribute. Nisuform is a form backend, and the examples below use it, but the same ideas apply to any service you pick.



## Set up a form backend in four steps

### Create a form and copy its endpoint

Sign in at [app.nisuform.com](https://app.nisuform.com) and choose **Create a form**. Pick **Endpoint only** if your site already has a form. The endpoint is on the form's **Setup** tab and looks like `https://api.nisuform.com/s/YOUR_FORM_KEY`.

### Point your form at it

Set the form's `action` to your endpoint and its `method` to `POST`. Give every input a `name`, because the browser only sends fields that have one. The name is also the label you see in your inbox.

```html title="contact.html"
<form action="https://api.nisuform.com/s/YOUR_FORM_KEY" method="POST">
  <label for="name">Name</label>
  <input id="name" type="text" name="name" required>

  <label for="email">Email</label>
  <input id="email" type="email" name="email" required>

  <label for="message">Message</label>
  <textarea id="message" name="message" rows="5" required></textarea>

  <input type="text" name="_gotcha" tabindex="-1" autocomplete="off" style="display:none">
  <button type="submit">Send</button>
</form>
```

### Keep the honeypot field

The hidden `_gotcha` input is a trap for bots. People never see it, so they leave it empty, while many bots fill in every field they find. Submissions with a value in it are dropped. Hide it with CSS as shown, not with `type="hidden"`, because bots skip hidden inputs.

### Send a real test

Open your live site, fill in the form and press submit. You land on a thank-you page with a link back to your site, the submission appears in your inbox, and a notification email arrives within seconds.

## Keep visitors on the page with fetch

A plain form takes the visitor to a thank-you page after submit. To stay on your page and show your own message, send the form with `fetch` and ask for JSON:

```js title="contact.js"
const form = document.querySelector('form')
const status = document.querySelector('#status')
const shownAt = Date.now()

form.addEventListener('submit', async (event) => {
  event.preventDefault()
  const data = new FormData(form)
  data.set('_elapsed', String(Date.now() - shownAt))

  const response = await fetch(form.action, {
    method: 'POST',
    headers: { Accept: 'application/json' },
    body: data,
  })
  const result = await response.json()

  status.textContent = result.ok ? 'Thanks! We got your message.' : result.message
  if (result.ok) form.reset()
})
```

Add an empty `<p id="status" role="status"></p>` below the form so screen readers announce the result.

Three details make this script better than most:

* The form keeps its `action` and `method`, so it still works if the script fails to load.
* `_elapsed` tells Nisuform how long the visitor spent on the form. Anything under 2 seconds is treated as a bot and dropped.
* Error responses include a `message` written for people, like "Too many requests. Try again shortly", so you can show it as is.

## Stop spam without a CAPTCHA

Every public form finds bots eventually. Stack cheap, invisible checks before you make people solve a puzzle:

* **Honeypot.** The hidden `_gotcha` field from step 3.
* **Fill time.** The `_elapsed` value from the script above. A person needs a few seconds, a bot a few milliseconds.
* **Allowed websites.** List your domains in the form's settings, and posts from any other site are rejected.
* **Rate limits and link checks.** Floods from one visitor are rejected, and submissions stuffed with links go to a spam folder instead of your inbox.
* **Cloudflare Turnstile.** For a form that still gets hit, add a Turnstile widget. Most visitors never see a challenge.

Bots caught by the honeypot or the fill-time check still get a normal success response, so they can't tell what gave them away. [How spam filtering works](/docs/protection/spam) lists every check in the order it runs.

## Checklist before you ship

1. Every field has a unique `name`, except checkboxes that belong to one group.
2. Every field has a `<label>`, so the form works with screen readers and tapping a label focuses its field.
3. Email fields use `type="email"` and required fields use `required`, so the browser catches mistakes before sending.
4. The form uses `method="POST"`. A `GET` form puts every answer in the URL.
5. The honeypot is hidden with CSS, not with `type="hidden"`.
6. You sent a test from the live site. If you set allowed websites, add `http://localhost:3000`, or whatever your dev server uses, to test locally.
7. You know where visitors land after submit. On Pro, you can [redirect them to your own thank-you page](/docs/forms/after-submit).

## The takeaway

A static site doesn't need a server to take form submissions. It needs a URL that accepts them. Point your form's `action` at a form backend, keep the honeypot, and spend the time you saved on the site itself. When you're ready to go further, the [HTML forms guide](/docs/connect/html) covers file uploads, hidden fields and every limit.

## Frequently asked questions

### Can an HTML form send an email without a backend?

Not on its own. A form can only send its fields to a URL. With a mailto action, the browser opens the visitor's email app instead of sending anything, and many visitors have none set up. To get an email for every submission, point the form at a service that receives the request and sends the email for you.

### Is it safe to put a form endpoint in public HTML?

Yes. The endpoint only accepts new submissions, and nobody can read your submissions through it. They are only visible in your dashboard. To stop other sites from posting to it, add your domains to the form's allowed websites, and rotate the key if it is ever abused.

### Does this work on GitHub Pages, Netlify, Vercel and Cloudflare Pages?

Yes. The form posts straight to the form backend, so it works on any host that serves HTML, including GitHub Pages, Netlify, Vercel, Cloudflare Pages and Amazon S3, and on site builders like Webflow and Framer.

### Do I need JavaScript to handle a form without a backend?

No. A form with an action URL and method POST works in every browser, even with JavaScript turned off. You only need JavaScript to keep visitors on the page and show your own success message.

### How much does a form backend cost?

Nisuform's Free plan includes 3 forms and 100 submissions a month with spam filtering, email notifications and CSV export, and needs no credit card. Pro is $10 a month for 5,000 submissions, unlimited forms, file uploads and webhooks.

## Pricing

- Free: $0 forever. 100 submissions per month, up to 3 forms, email notifications, spam protection, submission inbox and CSV export.
- Pro: $10 per month, or $84 per year. 5,000 submissions per month, unlimited forms, file uploads, webhooks, custom redirects and thank-you messages, auto-replies, custom sender name and notifications to any address.

More at https://nisuform.com/pricing.

## Frequently asked questions

### What is Nisuform?

Nisuform is a form backend for any website. Point your form at a Nisuform endpoint and it filters out spam, stores every submission in your dashboard and emails you when a new one arrives, so you do not need a server or database of your own.

### How do I connect my form?

Create a form in your dashboard and copy its endpoint. Use it as your form action, or send your own request to it from any framework. New submissions then appear in your inbox and arrive by email within seconds. The docs have copy-paste examples for HTML, JavaScript and React.

### Will Nisuform work with my website?

Yes, on any website that can send a request: hand-written HTML, WordPress, a JavaScript framework or a page from a site builder.

### What do visitors see after submitting a form?

By default, a thank-you page with a link back to your website. On the Pro plan, you can replace that message with your own or redirect visitors to a page of your choice.

### How does Nisuform protect against spam?

Every submission is screened automatically, with nothing to set up. A hidden honeypot field, a fill-time check and rate limits stop most bots. Submissions with too many links, or duplicates of an earlier one, go to the spam folder, where they never send a notification or count toward your monthly limit. You can also limit a form to submissions from your own domains.

### How will I be notified of new submissions?

You get an email as soon as a submission arrives, and every submission is saved in your inbox. On the Pro plan, notifications can also go to any email address, or to Slack, Discord or Telegram.

### Is there a free plan?

Yes. The Free plan includes 3 forms and 100 submissions per month, with email notifications, spam protection, full submission history and CSV export. No credit card is required.

### How much does Pro cost?

Pro costs $10 per month, or $84 per year, which works out to $7 per month. It includes unlimited forms, 5,000 submissions per month, file uploads, auto-replies, custom redirects and thank-you messages, plus notifications to Slack, Discord, Telegram and Google Sheets.

### Can visitors upload files through my form?

On the Pro plan, each submission can include up to 5 files, such as images or PDFs, up to 25 MB per request. Files are stored privately and shared only through signed links that expire after 15 minutes.

### Can I send submissions to other apps?

On the Pro plan, submissions can go straight to Slack, Discord, Telegram or Google Sheets, and to most other tools through webhooks, Zapier or Make.

### Can I export my submissions?

Yes, on every plan. Exports are CSV files that open in Excel and Google Sheets, and your submissions stay in your account until you delete them.

### How is my data protected?

Submissions are encrypted in transit and at rest, and are used only to provide the service. IP address collection can be turned off for each form, and deleted submissions are removed within 30 days. A Data Processing Agreement is included with every account.