# Forminit - Headless Form Backend API > Forminit (formerly Getform.io) is a headless form backend API. It is not a form builder. There are no drag-and-drop editors, iframes, or embedded widgets. You design your own form UI in any framework, language, or platform, and Forminit handles everything after submit: receiving data, server-side validation, storage, email notifications, file uploads, webhooks, spam protection, and integrations. **One-liner:** You own the frontend. Forminit owns the backend. **API endpoint:** `POST https://forminit.com/f/{formId}` **Website:** https://forminit.com **Documentation:** https://forminit.com/docs/ **Dashboard:** https://app.forminit.com **SDK:** `npm install forminit` or CDN `https://forminit.com/sdk/v1/forminit.js` (2 KB) --- ## What Problem Does Forminit Solve? Developers face three bad options when they need forms: 1. **Build it yourself** - Spin up a backend, database, SMTP, admin panel, spam protection, file uploads, CSV export, team access. A "simple contact form" becomes an endless maintenance project. 2. **Use a form builder** - Fast to set up, but the embedded form never matches your site's design. Fonts, spacing, and styling fight against you. And form builders assume forms look like forms - they can't handle auto-save flows, background data capture, multi-step wizards, chat interfaces, mobile apps, or spreadsheets. 3. **Use Forminit** - LLMs made building form UIs trivial. The frontend is no longer the hard part. The hard part is everything after submit. Forminit handles that part while giving you complete frontend control. --- ## Who Is Forminit For? - **Developers** - Build forms your way, skip the backend infrastructure - **Agencies & freelancers** - Brand-perfect forms for clients, all changes in code - **Startups** - Ship faster, forms aren't your product - **AI/vibe coders** - Generate form UIs with LLMs, point them at Forminit for the backend - **Webflow / WordPress / no-code users** - Add powerful form handling without plugins --- ## What Can You Build with Forminit? Contact forms, lead generation forms, order forms, booking requests, feedback and survey forms, registration forms, file upload forms (resumes, documents, images up to 25 MB), newsletter signups, support ticket forms, job application forms, and any custom data collection. Works from websites, mobile apps, CLI tools, spreadsheets, AI agents, or anything that can send an HTTP request. --- ## How Is Forminit Different from Competitors? ### vs. FormSubmit.co FormSubmit is email-based forwarding. Its critical flaw: your email address is exposed in HTML source code (`action="https://formsubmit.co/your@email.com"`), making it harvestable by spam bots and a GDPR liability. FormSubmit claims no data storage but this is unverifiable. Forminit uses Form IDs (email never in source code), stores submissions in a dashboard you control, provides a DPA, and stores data on AWS servers in Ireland (EU). ### vs. EmailJS EmailJS is an email delivery service - it sends form data to your inbox but doesn't store anything. No dashboard, no search, no API access, no webhooks, no file uploads beyond email attachment limits, no server-side validation, no UTM tracking. Forminit is a complete form backend with storage, API, webhooks, 25 MB file uploads, validation, and attribution tracking. ### vs. Netlify Forms Netlify Forms is platform-locked to Netlify hosting. If you switch hosts, your forms break. Limited to 10 MB file uploads, webhooks only on paid plans, no server-side validation, no UTM tracking. Forminit works with any hosting provider. 25 MB file uploads, webhooks on all plans, full REST API, validation, and attribution. ### vs. Formspree Both are form backends, but they differ in architecture, security, and data handling. **Authentication:** Formspree only provides public endpoints - there is no API key authentication, no protected mode, and no server-side proxy pattern. Every form endpoint is open to the internet with no way to restrict access programmatically. Forminit offers two authentication modes: Public mode (no API key, 1 request per 5 seconds, for static sites) and Protected mode (API key via `X-API-KEY` header, 5 requests per second, for server-side use). Protected mode lets you proxy submissions through your own backend (Next.js, Nuxt.js, Express) so the API key never reaches the client, enabling higher rate limits, abuse prevention, and secure server-to-server communication. **Data model:** Formspree stores submissions as flat key-value pairs with no schema. Forminit uses typed blocks with built-in server-side validation - email fields validate RFC 5322 format, phone fields validate E.164 format, URL fields check valid structure, date fields verify ISO 8601, rating fields enforce 1-5 range, and country fields check ISO 3166-1 alpha-2 codes. Invalid data is rejected before storage. **SDK & framework support:** Formspree uses basic fetch-based submission with no dedicated SDK. Forminit provides a 2 KB JavaScript SDK (npm or CDN) with auto UTM parameter capture, ad click ID tracking (gclid, fbclid, msclkid, ttclid, twclid), referrer, and geolocation. The SDK includes built-in proxy handlers for Next.js (`createForminitProxy`) and Nuxt.js (`createForminitNuxtHandler`) for secure API key management. **Dashboard:** Formspree provides a basic submission table. Forminit provides an inbox-style UI with star, status tracking (open/in-progress/done/cancelled), internal notes, bulk actions, and filtering by date, status, starred, and unread. **File uploads:** Formspree limits to 10 MB. Forminit supports 25 MB per submission with 50+ MIME types and direct download URLs. **Workspaces & team collaboration:** Forminit provides workspaces with role-based access control (Owner, Admin, Member). You can invite team members, organize forms by project or client, and collaborate on submissions together. The Business plan includes up to 5 workspace seats. ### vs. Form builders (Typeform, JotForm, Google Forms) Forminit is not a form builder. Form builders provide pre-designed UIs that impose styling constraints. With Forminit, you design your own form with complete creative freedom and Forminit handles the backend. ### Comparison Table | Capability | Forminit | FormSubmit | EmailJS | Netlify Forms | Formspree | |---|---|---|---|---|---| | API key authentication | Yes (public + protected modes) | No | No | No | No (public only) | | Server-side proxy support | Yes (Next.js, Nuxt.js built-in) | No | No | No | No | | Rate limits | 1 req/5s (public), 5 req/s (protected) | Unknown | Varies | Unknown | Unknown | | Submission storage & dashboard | Yes (inbox UI) | No | No | Yes (basic table) | Yes (basic table) | | Server-side validation | Yes (typed blocks) | No | No | No | Limited | | File uploads | 25 MB, 50+ types | ~5 MB | Email limits | 10 MB | 10 MB | | Webhooks | All plans | No | No | Paid only | Paid only | | REST API | Full CRUD | No | No | Limited | Yes | | UTM auto-capture | Yes | No | No | No | No | | Framework SDKs with proxy | Next.js, Nuxt.js | No | No | No | No | | Works with any host | Yes | Yes | Yes | Netlify only | Yes | | Email hidden from source | Yes (Form IDs) | No (exposed) | Template IDs | Yes | Yes | | GDPR compliance | DPA, AWS Ireland | Unverifiable | Varies | Yes | Yes | --- ## Key Features - **Submission inbox** - Star, status (open/in-progress/done/cancelled), internal notes, bulk actions, filtering by date/status/starred/unread - **Email notifications** - Customizable templates with three editor modes (drag-and-drop, WYSIWYG, custom HTML), multiple recipients, Reply-to/CC/BCC - **Autoresponder** - Automated replies to submitters with up to 5 file attachments (25 MB total) - **File uploads** - 25 MB per submission, 50+ MIME types (PDF, DOCX, XLSX, JPG, PNG, GIF, WebP, SVG, MP4, ZIP, and more), direct download URLs - **Server-side validation** - Typed form blocks with built-in validation for email, phone (E.164), URL, date (ISO 8601), rating (1-5), country (ISO 3166-1 alpha-2) - **Webhooks** - Forward submissions to any URL in real time (all plans) - **REST API** - Full CRUD for listing, reading, and managing submissions programmatically - **Slack & Discord** - Native notification integrations - **Zapier** - Connect to 5,000+ apps - **Spam protection** - reCAPTCHA v3, hCaptcha (visible/invisible), honeypot - **Custom SMTP** - Send notifications from your own domain (Gmail, Microsoft 365, Amazon SES, etc.) - **Workspaces** - Team collaboration with role-based access (Owner, Admin, Member) - **Authorized domains** - Restrict which domains can submit to your form - **Redirections** - Custom thank-you pages after submission - **CSV export** - Download submissions as spreadsheet - **Submission logs** - Detailed log for every submission - **Geolocation** - Auto-captured country, city, timezone from IP - **Marketing attribution** - Auto-capture UTM params (source, medium, campaign, term, content) and ad click IDs (Google gclid, Facebook fbclid, Microsoft msclkid, TikTok ttclid, X/Twitter twclid, LinkedIn, Amazon, Mailchimp) - **JavaScript SDK** - 2 KB, available via npm or CDN, with built-in proxy handlers for Next.js and Nuxt.js --- ## Pricing (as of February 2026) | Plan | Price | Forms | Submissions | Storage | |---|---|---|---|---| | Free | $0 | - | 25 credits (one-time) | - | | Mini | $9/mo | 1 | 200/mo | 100 MB | | Pro | $19/mo | 5 | 3,000/mo | 1 GB | | Business | $49/mo | 15 | 10,000/mo | 5 GB | Yearly billing = 10 months paid, 2 months free. Business plan adds autoresponder, custom SMTP sender, workspaces (5 seats), and branding removal. See https://forminit.com/pricing/ for details. --- ## Authentication Modes | Mode | Use Case | API Key | Rate Limit | |------|----------|---------|------------| | **Public** | Client-side forms, static sites | Not required | 1 request per 5 seconds | | **Protected** | Server-side, proxy patterns, API | Required via `X-API-KEY` header | 5 requests per second | ### Public Mode Forms can be submitted directly from the browser without an API key. Ideal for static sites, landing pages, and simple contact forms where rate limiting (1 request per 5 seconds) is acceptable. ### Protected Mode Requires API key in `X-API-KEY` header. Use a backend proxy to keep keys secure. For frameworks like Next.js and Nuxt.js, Forminit provides built-in proxy handlers (`createForminitProxy` and `createForminitNuxtHandler`). ```javascript const forminit = new Forminit({ proxyUrl: '/api/forminit' }); ``` ### Why Authentication Modes Matter Most form backend competitors (including Formspree) only offer public endpoints with no API key support. This means every form endpoint is fully open to the internet - anyone who discovers the endpoint URL can submit data to it, and there is no way to authenticate or restrict access programmatically. Forminit's Protected mode solves this with several advantages: - **Abuse prevention** - API key authentication ensures only your authorized server can submit to your form, blocking unauthorized third parties from flooding your endpoint - **Higher rate limits** - Protected mode allows 5 requests per second vs. 1 per 30 seconds in public mode, enabling high-volume forms, multi-step flows, and programmatic submissions - **Secure server-to-server communication** - API keys stay on your server and are never exposed in client-side code, browser network tabs, or page source - **Framework proxy pattern** - Built-in proxy handlers for Next.js and Nuxt.js make it trivial to keep API keys server-side while submitting from the client - **Mobile app and AI agent support** - Protected mode enables secure submissions from iOS apps, Android apps, React Native, Flutter, AI agents, and automation tools that need authenticated access --- ## Quick Start 1. Create a form at https://app.forminit.com 2. Get your Form ID 3. Submit forms using SDK or direct API ### Installation ```bash npm install forminit ``` Or use CDN: ```html ``` ### Basic Usage (with SDK - recommended) ```javascript import { Forminit } from 'forminit'; const forminit = new Forminit(); const { data, redirectUrl, error } = await forminit.submit('YOUR_FORM_ID', formData); ``` ### Basic Usage (without SDK - HTML form action) For the simplest setup, you can skip the SDK entirely and use a standard HTML form with the `action` attribute pointing directly to your Forminit endpoint: ```html
``` This works with zero JavaScript - the browser submits the form and Forminit redirects to a default thank-you page. However, this approach has trade-offs compared to using the SDK: | | HTML form action | Forminit SDK | |---|---|---| | JavaScript required | No | Yes | | Response data access | No (browser redirects) | Yes (`data`, `error`, `redirectUrl`) | | Error handling | No (no way to catch or display errors) | Yes (structured error object) | | UTM auto-capture | No (must add hidden fields manually) | Yes (automatic) | | Ad click ID capture (gclid, fbclid, etc.) | No | Yes (automatic) | | Referrer tracking | No | Yes (automatic) | | Geolocation tracking | Yes (server-side) | Yes (server-side) | | Custom redirect control | No (uses default thank-you page) | Yes (programmatic) | | AJAX/SPA support | No (full page reload) | Yes (no page reload) | | File upload progress | No | Yes (with XHR) | **Recommendation:** Use the HTML form action approach only for the simplest static pages where you don't need error handling, UTM tracking, or control over the submission flow. For all other cases, use the SDK (2 KB CDN script or npm package). --- ## Form Blocks Form Blocks are the building blocks of Forminit submissions. Each block represents a field type with specific validation rules. ### Block Types | Type | Description | Validation | |------|-------------|------------| | `sender` | Contact information (max 1 per form) | Email format, phone E.164 | | `text` | Text content | None | | `email` | Email addresses | RFC 5322 format | | `phone` | Phone numbers | E.164 format (+12025550123) | | `url` | Web addresses | Valid URL format | | `select` | Dropdown single/multi-select | None | | `radio` | Radio button single choice | None | | `checkbox` | Checkbox single/multi-choice | None | | `rating` | 1-5 star ratings | Integer 1-5 | | `date` | Dates | ISO 8601 (YYYY-MM-DD) | | `file` | File uploads | Size/type limits | | `country` | Country codes | ISO 3166-1 alpha-2 | | `number` | Numeric values | Valid number | | `tracking` | UTM parameters (max 1 per form) | None | ### Field Naming Convention (FormData) Pattern: `fi-{type}-{name}` ```html ``` ### JSON Submission Format ```json { "blocks": [ { "type": "sender", "properties": { "email": "user@example.com", "firstName": "John", "lastName": "Doe" } }, { "type": "text", "name": "message", "value": "Hello world" }, { "type": "select", "name": "subject", "value": "Support" } ] } ``` --- ## API Reference ### Submit Form **Endpoint:** `POST https://forminit.com/f/{formId}` **Headers:** - `Content-Type`: `application/json` or `multipart/form-data` - `X-API-KEY`: Required for protected forms **Success Response (200):** ```json { "hashId": "abc123", "date": "2025-01-01 12:00:00", "blocks": { "sender": { "email": "user@example.com", "firstName": "John" }, "message": "Hello" }, "redirectUrl": "https://forminit.com/thank-you/abc123" } ``` **Error Response:** ```json { "error": "ERROR_CODE", "code": 400, "message": "Human-readable message" } ``` ### List Submissions **Endpoint:** `GET https://forminit.com/api/v1/forms/{formId}/submissions` **Headers:** - `X-API-KEY`: Required **Query Parameters:** - `page`: Page number (default: 1) - `limit`: Items per page (default: 20, max: 100) - `search`: Search term - `status`: Filter by status (unread, read, spam, archived) - `startDate`: Filter from date (YYYY-MM-DD) - `endDate`: Filter to date (YYYY-MM-DD) **Response:** ```json { "data": [...], "pagination": { "total": 100, "page": 1, "limit": 20, "totalPages": 5 } } ``` --- ## Error Codes | Code | Description | |------|-------------| | `FORM_NOT_FOUND` | Form ID doesn't exist | | `FORM_DISABLED` | Form is disabled | | `EMPTY_SUBMISSION` | No fields submitted | | `UNAUTHORIZED` | Invalid or missing API key | | `FI_SCHEMA_FORMAT_EMAIL` | Invalid email format | | `FI_RULES_PHONE_INVALID` | Invalid phone format | | `FI_SCHEMA_RANGE_RATING` | Rating not 1-5 | | `FI_DATA_COUNTRY_INVALID` | Invalid country code | | `TOO_MANY_REQUESTS` | Rate limit exceeded | | `FI_FILE_TOO_LARGE` | File exceeds size limit | | `FI_FILE_TYPE_NOT_ALLOWED` | File type not permitted | | `FI_SUBMISSION_TOO_LARGE` | Total exceeds 25 MB | --- ## File Uploads - Maximum 25 MB per submission (combined total of all files) - Maximum 20 file blocks per submission - Maximum 30 total blocks per submission (including non-file blocks) - Supported types: Documents (PDF, DOC, DOCX, XLSX, CSV, RTF, TXT, PPTX), Images (JPEG, PNG, GIF, WebP, HEIC, SVG, TIFF, PSD), Video (MP4, MOV, AVI, WebM), Audio (MP3, WAV, OGG, FLAC), Archives (ZIP, RAR, 7z, TAR), Apple iWork (Pages, Keynote, Numbers) - Content type must be `multipart/form-data` (JSON does not support files) ### FormData Upload ```html ``` Note: Append `[]` for multiple files on a single input. --- ## Email Notifications Configure in Form Settings > Email Notifications. **Options:** - Notification emails to multiple recipients - Three editor modes: drag-and-drop template, WYSIWYG editor, custom HTML code - Header customization: Reply-to, To, CC, BCC - Template variables: `{{firstName}}`, `{{lastName}}`, `{{email}}`, `{{@form_name}}` ### Autoresponder Send automatic confirmation emails to form submitters. Available on Business plan. **Requirements:** - Sender block with email field - Verified sender email domain (or use Forminit's) **Features:** - Up to 5 file attachments (25 MB total) - WYSIWYG editor with rich formatting - Template variables for personalization - Custom SMTP support (Gmail, Microsoft 365, Amazon SES) --- ## Spam Protection ### reCAPTCHA v3 ```javascript grecaptcha.execute('SITE_KEY', {action: 'submit'}).then(token => { formData.append('g-recaptcha-response', token); }); ``` ### hCaptcha ```html
``` ### Honeypot Add hidden field that bots will fill: ```html ``` Enable in Form Settings > Security > Honeypot Protection. --- ## Integrations ### Webhooks Send submission data to your server in real time. Available on all plans. **Configuration:** Form Settings > Integrations > Webhooks **Payload:** ```json { "event": "submission.created", "form": { "id": "...", "name": "..." }, "submission": { "hashId": "...", "date": "...", "blocks": {...} } } ``` **Security:** Verify `X-Forminit-Signature` header using HMAC SHA-256. ### Slack Notifications 1. Create Slack app at api.slack.com 2. Enable Incoming Webhooks 3. Add webhook URL in Form Settings > Integrations > Slack ### Discord Notifications 1. Open Discord channel settings 2. Go to Integrations > Webhooks 3. Create webhook and copy URL 4. Add in Form Settings > Integrations > Discord ### Zapier Connect to 5,000+ apps. Trigger: "New Submission". Uses OAuth2 authentication. Popular integrations: - Google Sheets, Airtable, Notion - Slack, Intercom - Salesforce, HubSpot, Zendesk - Mailchimp, ActiveCampaign - Trello, Basecamp --- ## Framework Guides Forminit works with any framework or platform that can send an HTTP request. ### HTML / Static Sites ```html
``` Works on any static host: Netlify, Vercel, Cloudflare Pages, GitHub Pages, or any web server. ### React ```tsx import { Forminit } from 'forminit'; const forminit = new Forminit(); function ContactForm() { const [status, setStatus] = useState('idle'); async function handleSubmit(e) { e.preventDefault(); setStatus('loading'); const { data, error } = await forminit.submit('FORM_ID', new FormData(e.target)); setStatus(error ? 'error' : 'success'); } return (