# Backforms Developer Documentation (Consolidated Reference)

> Headless Form Backend for Modern Developers.
> https://backforms.com

---


---

# Quickstart: Integrating Backforms in 60 Seconds

Backforms is a headless form backend for developers. Collect form submissions, block spam bots, and forward leads to Email, Discord, Telegram, WhatsApp, and Webhooks without writing backend code.

## 1. Create a Form Endpoint
1. Open your Backforms Dashboard: https://backforms.com/dashboard
2. Click **"+ New Form"** and name your form (e.g., "Contact Form").
3. Copy your unique Form Endpoint URL or Access Key:
   `https://backforms.com/f/YOUR_ACCESS_KEY`

## 2. Point Your HTML Form to Backforms
Paste your Form Endpoint URL into your HTML `<form>` action attribute:

```html
<form action="https://backforms.com/f/YOUR_ACCESS_KEY" method="POST">
  <input type="text" name="name" placeholder="Your Name" required />
  <input type="email" name="email" placeholder="Your Email" required />
  <textarea name="message" placeholder="Your Message" required></textarea>

  <!-- Optional Honeypot Bot Trap (invisible to humans) -->
  <input type="text" name="botcheck" style="display: none;" tabIndex="-1" autoComplete="off" />

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

## 3. Submit and Verify
1. Fill out your form and click submit.
2. Backforms intercepts the submission, validates spam shields, logs the lead in your dashboard, and delivers notifications.
3. For AJAX/Fetch requests, Backforms responds with JSON: `{ "success": true, "submissionId": "..." }`.



---

# Backforms Architecture & Ingestion Pipeline

Backforms operates a high-throughput, edge-accelerated ingestion pipeline designed for zero data loss and sub-50ms processing.

## Submission Ingestion Pipeline
1. **Edge Ingestion**: Submissions arrive at `https://backforms.com/f/[accessKey]` via standard `POST` (JSON or multipart/form-data).
2. **CORS & Domain Whitelisting**: The Origin and Referer headers are verified against your authorized domains.
3. **Multi-Layer Spam Isolation**:
   - **Honeypot Trap**: Evaluates hidden `botcheck` / `_gotcha` fields.
   - **Disposable Email Shield**: Cross-references email domains against our in-memory database of 75,400+ burner providers.
   - **Cloudflare Turnstile**: Validates cryptographic challenge tokens with Cloudflare's siteverify API.
   - **Quarantine Engine**: Spammers receive HTTP 200 OK stealthily, but submissions are quarantined and never consume your monthly quota.
4. **Encrypted Storage**: Validated leads are stored in encrypted, high-availability database clusters with automated deduplication.
5. **Asynchronous Multi-Channel Fan-Out**: Dispatches notifications in parallel across Meta WhatsApp Cloud API v22.0, Discord Rich Embeds, Telegram Bots, verified transactional email alerts, and HMAC-SHA256 signed custom webhooks.



---

# Plain HTML Form Integration

Backforms works seamlessly with vanilla HTML, static websites, Webflow, WordPress, Hugo, Jekyll, and Shopify.

```html
<form action="https://backforms.com/f/YOUR_ACCESS_KEY" method="POST">
  <!-- Core Fields -->
  <label for="name">Name</label>
  <input type="text" id="name" name="name" required />

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

  <label for="subject">Subject</label>
  <input type="text" id="subject" name="subject" />

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

  <!-- Optional Custom Redirect URL -->
  <input type="hidden" name="_next" value="https://mywebsite.com/thank-you" />

  <!-- Optional Honeypot Anti-Spam Trap -->
  <input type="text" name="botcheck" style="display: none;" tabIndex="-1" autoComplete="off" />

  <button type="submit">Submit</button>
</form>
```



---

# React / Next.js Integration

Integrate Backforms using client-side React components with `fetch()` and `FormData`.

```tsx
"use client";

import { useState } from "react";

export function ContactForm() {
  const [status, setStatus] = useState<"idle" | "loading" | "success" | "error">("idle");
  const [errorMessage, setErrorMessage] = useState("");

  const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    setStatus("loading");
    setErrorMessage("");

    const formData = new FormData(e.currentTarget);

    try {
      const response = await fetch("https://backforms.com/f/YOUR_ACCESS_KEY", {
        method: "POST",
        headers: {
          Accept: "application/json",
        },
        body: formData,
      });

      const result = await response.json();

      if (response.ok && result.success) {
        setStatus("success");
        (e.target as HTMLFormElement).reset();
      } else {
        setStatus("error");
        setErrorMessage(result.message || "Something went wrong.");
      }
    } catch {
      setStatus("error");
      setErrorMessage("Network error occurred. Please try again.");
    }
  };

  return (
    <form onSubmit={handleSubmit} className="space-y-4">
      <input type="text" name="name" placeholder="Your Name" required />
      <input type="email" name="email" placeholder="Your Email" required />
      <textarea name="message" placeholder="Your Message" required />

      {/* Honeypot Trap */}
      <input type="text" name="botcheck" style={{ display: "none" }} tabIndex={-1} autoComplete="off" />

      <button type="submit" disabled={status === "loading"}>
        {status === "loading" ? "Sending..." : "Send Message"}
      </button>

      {status === "success" && <p className="text-emerald-500">Thank you! Message sent.</p>}
      {status === "error" && <p className="text-rose-500">{errorMessage}</p>}
    </form>
  );
}
```



---

# Astro Integration

Integrate Backforms in Astro projects with zero-JS static HTML forms or enhanced client components.

```astro
---
// src/components/ContactForm.astro
---

<form action="https://backforms.com/f/YOUR_ACCESS_KEY" method="POST" class="contact-form">
  <input type="text" name="name" placeholder="Full Name" required />
  <input type="email" name="email" placeholder="Email Address" required />
  <textarea name="message" placeholder="How can we help?" required></textarea>

  <!-- Custom Redirect -->
  <input type="hidden" name="_next" value="https://mysite.com/thanks" />

  <!-- Silent Honeypot -->
  <input type="text" name="botcheck" style="display: none;" tabIndex="-1" autoComplete="off" />

  <button type="submit">Submit Inquiry</button>
</form>
```



---

# Vue 3 / Nuxt Integration

Using Vue 3 Composition API with reactive state and fetch:

```vue
<script setup lang="ts">
import { ref } from "vue";

const isSubmitting = ref(false);
const isSuccess = ref(false);

const submitForm = async (e: Event) => {
  const form = e.target as HTMLFormElement;
  isSubmitting.value = true;

  const formData = new FormData(form);

  try {
    const res = await fetch("https://backforms.com/f/YOUR_ACCESS_KEY", {
      method: "POST",
      headers: { Accept: "application/json" },
      body: formData,
    });
    const data = await res.json();
    if (data.success) {
      isSuccess.value = true;
      form.reset();
    }
  } finally {
    isSubmitting.value = false;
  }
};
</script>

<template>
  <form @submit.prevent="submitForm">
    <input type="text" name="name" required placeholder="Name" />
    <input type="email" name="email" required placeholder="Email" />
    <textarea name="message" required placeholder="Message"></textarea>
    <input type="text" name="botcheck" style="display: none;" tabindex="-1" autocomplete="off" />
    <button type="submit" :disabled="isSubmitting">Send</button>
    <p v-if="isSuccess">Message sent successfully!</p>
  </form>
</template>
```



---

# cURL & REST API Reference

Submit leads directly via HTTP POST requests from CLI, Postman, or backend workers.

## HTTP POST Endpoint
```bash
curl -X POST https://backforms.com/f/YOUR_ACCESS_KEY \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Alex Mercer",
    "email": "alex@example.com",
    "subject": "Partnership Inquiry",
    "message": "Interested in integrating Backforms into our agency workflow."
  }'
```

## Sample HTTP 200 OK Response
```json
{
  "success": true,
  "message": "Form submitted successfully!",
  "submissionId": "688402bf-b855-4015-ba2e-503c00aa16b3",
  "data": {
    "name": "Alex Mercer",
    "email": "alex@example.com",
    "subject": "Partnership Inquiry",
    "message": "Interested in integrating Backforms into our agency workflow."
  }
}
```



---

# Custom Redirects & Thank-You Pages

Send users to custom confirmation pages on static sites, or handle JSON responses programmatically.

## Native HTML Form Redirection (HTTP 303 See Other)
When submitting standard HTML forms, Backforms intercepts the request and issues an immediate `HTTP 303 See Other` redirect to your custom URL.

```html
<form action="https://backforms.com/f/YOUR_ACCESS_KEY" method="POST">
  <input type="text" name="name" required />
  <input type="email" name="email" required />

  <!-- Custom Redirect URL -->
  <input type="hidden" name="_next" value="https://mywebsite.com/thank-you" />

  <button type="submit">Submit</button>
</form>
```

## Supported Redirect Parameter Aliases
- `_next`: Standard recommended parameter (e.g., `https://site.com/thanks`).
- `redirect`: Formspree compatibility alias.
- `redirect_url`: Explicit URL alias.
- `next`: Python/Django convention alias.

*Note: You can also configure a permanent default redirect URL directly inside the Settings tab of each form in your Backforms Dashboard.*



---

# File Uploads & Attachments

Accept applicant resumes, screenshots, invoices, and documents securely without building custom S3 pipelines.

## Key Features
- **Supported File Types**: PDF, DOCX, ZIP, PNG, JPG, JPEG, WEBP, CSV, TXT.
- **File Size Limits**: Up to 10MB per submission on Pro/Agency plans (2MB on Free tier).
- **Security**: Automatic MIME-type verification and file name sanitization against directory traversal.

## HTML Example with enctype="multipart/form-data"
```html
<form 
  action="https://backforms.com/f/YOUR_ACCESS_KEY" 
  method="POST" 
  enctype="multipart/form-data"
>
  <input type="text" name="applicant_name" placeholder="Full Name" required />
  <input type="email" name="applicant_email" placeholder="Email Address" required />
  
  <!-- File Upload Field -->
  <label for="resume">Upload Resume (PDF, max 10MB):</label>
  <input type="file" id="resume" name="resume" accept=".pdf,.docx" required />

  <button type="submit">Submit Application</button>
</form>
```



---

# Zero-Friction Honeypot Anti-Spam

Stop automated spam scrapers without frustrating legitimate users with difficult visual puzzle captchas.

## How the Honeypot Works
1. Place an invisible input field named `botcheck` in your form:
```html
<input type="text" name="botcheck" style="display: none;" tabIndex="-1" autoComplete="off" />
```
2. Real human users cannot see this field and leave it blank. Automated scrapers detect the input in your HTML and fill it automatically.
3. When Backforms receives a submission with `botcheck` filled, it stealthily isolates the submission into your **Spam Quarantined** mailbox, suppresses email notifications, and returns HTTP 200 OK so bots never realize they were blocked.

## Zero Keys Required
Unlike Turnstile or reCAPTCHA, honeypots require **zero API keys**, no third-party JavaScript scripts, and no external accounts.



---

# Disposable & Burner Email Shield

Stop fake accounts and throwaway leads before they pollute your CRM or email campaigns.

## Real-Time Blocklist of 75,400+ Domains
- **Live Filtering**: Every submission's email is cross-referenced against 75,400+ verified disposable email providers (Mailinator, TempMail, GuerrillaMail, 10MinuteMail, YOPmail, BullBaby, etc.).
- **Automatic Quarantine**: Leads using burner domains are flagged and routed to your Spam box without triggering webhook or email alerts.
- **Zero False Positives**: Legitimate domains (Gmail, Outlook, Yahoo, iCloud, Proton, corporate domains, and newly purchased domains) are always accepted.



---

# Cloudflare Turnstile Anti-Spam (BYOK Model)

Non-interactive, privacy-friendly bot challenge that replaces frustrating puzzle CAPTCHAs.

## Understanding the Two Keys
- **Site Key (Public • Frontend)**: Placed in your website's HTML/React code. Generates a one-time cryptographic token (`cf-turnstile-response`). **One Site Key works across all forms on your domain.**
- **Secret Key (Private • Backforms Dashboard)**: Saved encrypted in Backforms Settings. Backforms uses this key server-to-server to verify token authenticity with Cloudflare.

## Setup Instructions

### 1. Embed Widget in Your Form
```html
<!-- Include Cloudflare Turnstile script -->
<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>

<form action="https://backforms.com/f/YOUR_ACCESS_KEY" method="POST">
  <input type="text" name="name" required />
  <input type="email" name="email" required />

  <!-- Turnstile Widget with your public Site Key -->
  <div class="cf-turnstile" data-sitekey="YOUR_CLOUDFLARE_SITE_KEY"></div>

  <button type="submit">Submit</button>
</form>
```

### 2. Save Secret Key in Backforms
Open your Form Settings in Backforms -> **Spam & Security** tab -> Paste your private Secret Key from Cloudflare.



---

# Domain Whitelisting (CORS Protection)

Prevent third parties from scraping your form endpoint and submitting spam from unauthorized origins.

## Configuration
In your Backforms Form Settings, enter your allowed domains separated by commas:
```
mywebsite.com, staging.mywebsite.com, localhost
```

Submissions from origins not matching this list will be rejected immediately with **HTTP 403 Forbidden**.



---

# Adaptive Rate Limiting & Inbound DDoS Shield

Backforms automatically enforces high-performance edge rate limiting on all public form endpoints to protect your applications from bot floods, automated spam attacks, and denial-of-wallet scripts.

## Automatic Zero-Config Protection
Rate limiting is enabled by default across all forms and plans (Free Developer, Pro Freelancer, and Agency). No API keys, plugins, or reverse-proxy configurations are required.

## Protective Thresholds
- **Per-Form Endpoint Shield**: Up to **10 submissions per 60 seconds per IP address** for any single form. This accommodates rapid user corrections or multi-step forms while preventing automated rapid-fire spam.
- **Global Network Shield**: Up to **30 submissions per 60 seconds per IP address** across the entire platform, stopping distributed scrapers that attempt to cycle through multiple client forms.
- **Zero Quota Loss**: Submissions blocked by the rate limiter are halted at the edge in under 10ms. **They never count toward your monthly submission quota** and trigger no database writes or downstream notifications.

## HTTP 429 Response & Standard Headers
When a client exceeds the submission threshold, Backforms returns an **HTTP 429 Too Many Requests** status with standard rate limit telemetry headers:

```http
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 45
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1772651430
```

### JSON Response Body
```json
{
  "success": false,
  "message": "Too many submissions from this network. Please wait 45 seconds before submitting again."
}
```

## Handling Rate Limits in Frontend Code (React / Fetch)
```typescript
const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
  e.preventDefault();
  const formData = new FormData(e.currentTarget);

  const response = await fetch("https://backforms.com/f/YOUR_ACCESS_KEY", {
    method: "POST",
    headers: { "Accept": "application/json" },
    body: formData,
  });

  if (response.status === 429) {
    const retryAfter = response.headers.get("Retry-After") || "60";
    alert(`Please slow down. You can submit again in ${retryAfter} seconds.`);
    return;
  }

  const result = await response.json();
  if (result.success) {
    alert("Form submitted successfully!");
  }
};
```

## High-Volume Delivery Smoothing
For connected downstream channels (such as WhatsApp Cloud API or Webhooks), Backforms dynamically smooths out sudden high-volume bursts into compliant throughput windows so notifications are delivered reliably without exceeding third-party provider limits.



---

# WhatsApp Cloud API (Meta) Alerts

Receive real-time lead alerts directly on WhatsApp via the official Meta WhatsApp Cloud API v22.0.

## Supported Modes
- **Managed Backforms Alert Gateway**: Turn on instant alerts with zero Meta configuration.
- **BYOK (Bring Your Own Key)**: Connect your own Meta App ID, Phone Number ID, and System User Access Token.



---

# Discord Webhook Integration

Stream form submissions straight into your team's Discord channels with rich embed cards.

## Setup
1. In Discord: Server Settings -> Integrations -> Webhooks -> New Webhook -> Copy Webhook URL.
2. In Backforms: Form Settings -> Integrations -> Discord -> Paste Webhook URL and toggle Active.



---

# Telegram Bot Alerts

Deliver instant markdown-formatted notifications to your private Telegram chat or team group.

## Setup
1. Message `@BotFather` on Telegram to create a bot and get your **Bot Token**.
2. Message `@userinfobot` to get your **Chat ID**.
3. In Backforms: Form Settings -> Integrations -> Telegram -> Enter credentials and save.



---

# Custom Webhooks & HMAC-SHA256 Signatures

Stream raw form JSON payloads to your API, AWS Lambda, Zapier, Make, or n8n with cryptographic signature verification.

## Dispatched HTTP Headers
- `Content-Type`: application/json
- `X-Backforms-Event`: form.submission
- `X-Backforms-Form-Id`: form_xxx
- `X-Backforms-Submission-Id`: sub_xxx
- `X-Backforms-Signature`: sha256=<hex_digest>

## Verification Recipes

### Node.js / Express (TypeScript)
```typescript
import express, { Request, Response } from "express";
import crypto from "crypto";

const app = express();
const WEBHOOK_SECRET = process.env.BACKFORMS_WEBHOOK_SECRET!;

app.use(express.json({
  verify: (req: any, _res, buf) => { req.rawBody = buf; }
}));

app.post("/webhook", (req: any, res: Response) => {
  const signatureHeader = req.headers["x-backforms-signature"] as string;
  if (!signatureHeader?.startsWith("sha256=")) return res.status(401).send("Unauthorized");

  const expectedSig = signatureHeader.replace("sha256=", "");
  const computedSig = crypto.createHmac("sha256", WEBHOOK_SECRET).update(req.rawBody).digest("hex");

  const isValid = crypto.timingSafeEqual(Buffer.from(computedSig, "hex"), Buffer.from(expectedSig, "hex"));
  if (!isValid) return res.status(403).send("Signature mismatch");

  console.log("Verified lead:", req.body.data);
  return res.status(200).json({ received: true });
});
```

### Python (FastAPI)
```python
import hmac, hashlib
from fastapi import FastAPI, Request, HTTPException

app = FastAPI()
WEBHOOK_SECRET = "your_secret_key"

@app.post("/webhook")
async def backforms_webhook(request: Request):
    sig_header = request.headers.get("X-Backforms-Signature", "")
    if not sig_header.startswith("sha256="):
        raise HTTPException(status_code=401)
        
    expected_sig = sig_header.replace("sha256=", "")
    raw_body = await request.body()
    computed_sig = hmac.new(WEBHOOK_SECRET.encode("utf-8"), raw_body, hashlib.sha256).hexdigest()
    
    if not hmac.compare_digest(computed_sig, expected_sig):
        raise HTTPException(status_code=403)
        
    return {"received": True}
```



---

# Google Sheets Real-Time Sync (Pro & Agency)

Sync form submissions directly into your Google Spreadsheet row-by-row in real time without Zapier, Make, or third-party webhooks.

> **Plan Requirement**: Google Sheets Sync is available on **Pro Freelancer** and **Agency & Team** subscription plans.

---

## How It Works

Backforms integrates with the official **Google Sheets API v4** via an automated server-to-server Service Account bot.
1. When a visitor submits your form, Backforms validates spam checks and securely stores the submission.
2. The asynchronous dispatcher extracts the form data and requests your Google Sheet.
3. **Dynamic Header Matching**:
   - Backforms scans row 1 of your selected tab for existing column names.
   - If a form field matches an existing column, the value is placed in that column.
   - If a new form field is detected that does not exist in row 1, Backforms **automatically appends a new column header** to row 1 on-the-fly.
   - Existing formulas, cell formatting, and past rows remain completely untouched.
4. The submission is appended as a new row in under **200 milliseconds**.

---

## 30-Second Setup Guide

### Step 1: Open Your Google Sheet
Create a new spreadsheet or open an existing one in your [Google Drive](https://drive.google.com).

### Step 2: Share Spreadsheet with Backforms Bot
Click the blue **Share** button at the top-right of your Google Sheet. Invite our automated sync bot email as **Editor**:
```
backforms-sync@backforms.iam.gserviceaccount.com
```
*(You can uncheck "Notify people" since this is an automated service account).*

### Step 3: Copy URL into Backforms
1. Copy the full spreadsheet URL from your browser address bar:
   `https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFM.../edit`
2. In your Backforms Dashboard:
   - Go to your form -> **Integrations** tab.
   - Expand the **Google Sheets Sync** card.
   - Paste the Google Spreadsheet URL or ID.
   - Specify the Sheet tab name (defaults to `Sheet1`).
   - Click **Save Google Sheets** and toggle the switch to **Active**.
   - Click **Test Row Sync** to verify instant append.

---

## Automated Columns Included

In addition to custom form inputs (e.g. `name`, `email`, `message`), Backforms automatically appends telemetry columns for auditing:
- `Submission ID`: Unique identifier (e.g. `sub_9812fa...`)
- `Date / Time (UTC)`: Submission timestamp in ISO 8601 format
- `Form Name`: The human-readable name of the form in Backforms

---

## Security & Privacy
- **Least-Privilege Isolation**: The sync bot only accesses spreadsheets that you explicitly share with its email address.
- **Zero Drive Access**: Backforms cannot view, list, or modify other files in your Google Drive or Google Workspace account.
- **Formula Injection Defense**: Text starting with formula characters (`=`, `+`, `-`, `@`) is sanitized to prevent spreadsheet formula injection vulnerabilities (OWASP CWE-1236).



---

# Submission Parameters Reference

| Parameter Name | Type | Description |
|---|---|---|
| `access_key` | string | Public access token of your form. |
| `_next` / `redirect` | string (URL) | Custom redirect URL upon successful HTML submission (HTTP 303). |
| `botcheck` / `_gotcha` | string | Hidden honeypot field. Must be left blank by humans. |
| `cf-turnstile-response` | string | Cloudflare Turnstile cryptographic token. |
| `subject` / `asunto` | string | Custom subject line override for notifications. |
| `email` | string | Submitter's email address (used for auto-responders and gravatar). |
| `name` | string | Submitter's full name. |
| `[any custom key]` | any | Any custom inputs (phone, company, budget, checkboxes) are saved automatically. |



---

# HTTP Status Codes Reference

| Status Code | Reason | Meaning |
|---|---|---|
| **200 OK** | Success | Form submission accepted and stored successfully. |
| **303 See Other** | Redirect | Native HTML form redirecting to thank you page. |
| **400 Bad Request** | Missing Key / Invalid JSON | Malformed payload or missing required access_key. |
| **403 Forbidden** | CORS Unauthorized | Domain not in allowed domains whitelist or invalid HMAC. |
| **429 Rate Limit** | Quota Exceeded | Monthly submission limit reached for active tier. |
| **500 Server Error** | Internal Failure | Temporary processing failure on our cluster. |



---

# Model Context Protocol (MCP) Server: backforms-mcp

Backforms provides an official Model Context Protocol server published on NPM as `backforms-mcp` (`https://www.npmjs.com/package/backforms-mcp`). It allows AI coding agents (Cursor, Windsurf, Claude Desktop, Claude Code, and Antigravity) to autonomously provision forms, inspect submissions, configure webhooks, and test pipelines.

## 1. Authentication
Generate a Personal Access Token in your Backforms Dashboard under **Settings -> API Keys** (`/dashboard/settings/api-keys`).
The key begins with `bf_live_sec_` and is authenticated via cryptographic SHA-256 hashing.

## 2. Configuration for AI IDEs

### Cursor IDE (`.cursor/mcp.json`)
```json
{
  "mcpServers": {
    "backforms": {
      "command": "npx",
      "args": ["-y", "backforms-mcp"],
      "env": {
        "BACKFORMS_API_KEY": "bf_live_sec_YOUR_KEY"
      }
    }
  }
}
```

### Claude Desktop (`claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "backforms": {
      "command": "npx",
      "args": ["-y", "backforms-mcp"],
      "env": {
        "BACKFORMS_API_KEY": "bf_live_sec_YOUR_KEY"
      }
    }
  }
}
```

### Claude Code CLI
```bash
claude mcp add backforms --env BACKFORMS_API_KEY=bf_live_sec_YOUR_KEY -- npx -y backforms-mcp
```



---

# MCP 9 Tools Reference for backforms-mcp

The `backforms-mcp` server registers 9 autonomous tools:

1. **`create_form`**: Provisions a new form endpoint with anti-spam and redirect settings.
   - Arguments: `name` (string, required), `primary_email` (string), `allowed_domains` (string), `redirect_url` (string), `honeypot_enabled` (boolean), `disposable_email_shield` (boolean).
2. **`list_forms`**: Lists workspace forms with submission counts and endpoints.
   - Arguments: `limit` (number), `offset` (number).
3. **`get_form_details`**: Fetches complete settings, security switches, and integrations for a form.
   - Arguments: `form_id` (string, required).
4. **`get_form_submissions`**: Queries recent submissions with full JSON payload and spam quarantine status.
   - Arguments: `form_id` (string, required), `limit` (number), `is_spam` (boolean).
5. **`update_form_settings`**: Mutates form properties, allowed origins, and anti-spam flags.
   - Arguments: `form_id` (string, required), `name`, `allowed_domains`, `redirect_url`, `honeypot_enabled`, `turnstile_enabled`.
6. **`setup_webhook`**: Configures or updates third-party notification connectors (Discord, Telegram, Slack, Webhook).
   - Arguments: `form_id` (string, required), `type` ('webhook' | 'discord' | 'telegram' | 'slack'), `url` (string, required).
7. **`send_test_submission`**: Dispatches a verified test lead to verify webhook and alert fanout.
   - Arguments: `form_id` (string, required), `payload` (object).
8. **`delete_form`**: Permanently deletes a form endpoint and all associated historical data.
   - Arguments: `form_id` (string, required).
9. **`check_workspace_usage`**: Queries monthly usage quota, spam blocked stats, and plan limits.
   - Arguments: none.



---

# Public REST API v1 Reference

Base URL: `https://app.backforms.com/api/v1`
Authentication: `Authorization: Bearer bf_live_sec_...`

## Endpoints

### 1. List Forms
- **Method**: `GET /api/v1/forms`
- **Query Params**: `limit` (default 20), `offset` (default 0)
- **Response**: `{ "forms": [...], "total": 12, "workspace": { ... } }`

### 2. Create Form
- **Method**: `POST /api/v1/forms`
- **Body**: `{ "name": "Contact Sales", "allowed_domains": "acme.com", "honeypot_enabled": true }`
- **Response**: `{ "success": true, "id": "form_...", "action_url": "https://app.backforms.com/f/..." }`

### 3. Retrieve Submissions
- **Method**: `GET /api/v1/forms/:id/submissions`
- **Query Params**: `limit` (default 10), `is_spam` (boolean)

### 4. Trigger Test Submission
- **Method**: `POST /api/v1/forms/:id/test`
- **Body**: `{ "data": { "name": "Test User", "email": "test@domain.com" } }`

### 5. Workspace Usage & Quotas
- **Method**: `GET /api/v1/workspaces/usage`
- **Response**: `{ "workspace": { "plan": "pro" }, "usage": { "submissions_this_month": 150, "submissions_limit": 5000 } }`



---

# Slack Notifications Integration

Backforms supports direct Slack notifications via official OAuth 2.0.

## Setup
1. In your Backforms Dashboard, navigate to your form's **Integrations** tab.
2. Click **"Connect Slack"** and authorize your workspace and channel (e.g. `#leads`).
3. Backforms posts real-time Block Kit cards with sender name, email, submission fields, and dashboard links.
4. Click **"Test"** to send an instant verification alert to your channel.



---

# Notion Database Sync Integration

Automatically convert form submissions into organized rows in your Notion databases without third-party automation tools like Zapier or Make.

## Setup
1. In your Backforms Dashboard, navigate to **Integrations** and click **"Connect Notion"**.
2. Select your Notion workspace and grant access to the desired pages.
3. Choose the target database from the dropdown.
4. Backforms dynamically maps submitted inputs (`name`, `email`, `message`, `phone`) to matching Notion database properties.



---

# Workspaces & Team Role-Based Access Control (RBAC)

Collaborate securely with multi-tenant workspaces and a 5-seat collaborative quota on Pro and Agency plans.

## Roles & Permissions Matrix
- **Owner**: Full workspace management, billing invoices, API key creation, member role management.
- **Admin**: Create and delete forms, configure integrations (Slack, Notion, Discord, Webhooks), invite members.
- **Member**: Create forms, update endpoints, view and export submission records.
- **Viewer**: Read-only access to submissions, analytics, and form metrics.

## Invitations
Invite members via email or secret token links (`https://app.backforms.com/invite/:token`) in **Dashboard -> Settings -> Team**.



---

# Email Auto-Responders & Routing

Send immediate, branded confirmation emails back to the submitter upon form ingestion.

## Configuration
1. In Form **Settings**, toggle on **Auto-Responder**.
2. Customize the subject and body using dynamic tags like `{{name}}` and `{{email}}`.
3. Add **Secondary Notification Emails** to CC colleagues and co-founders on every submission alert.