# FormsList — complete guide for AI agents

FormsList (formslist.com) is a form backend. This file contains the full integration contract: instant provisioning, the submission endpoint, the authenticated REST v1 API, and the MCP server.

================================================================
1. INSTANT PROVISIONING (no auth — built for agents)
================================================================

POST https://formslist.com/api/v1/instant
Content-Type: application/json

Request:  {"email": "site-owner@example.com", "form_name": "Contact form"}

Success (201):
{
  "form_id": "...",
  "endpoint": "https://formslist.com/f/abc123def456",   // live immediately
  "method": "POST",
  "html_snippet": "<form action=\"...\" method=\"POST\">...</form>",
  "curl_example": "curl -X POST ...",
  "claim_url": "https://formslist.com/claim?token=...",  // also emailed to the owner
  "expires_at": "...",                                    // unclaimed forms delete after 7 days
  "docs_url": "https://formslist.com/docs#instant"
}

Errors are {"error", "fix", "docs_url"} — follow the "fix". Notable:
- 409 account_exists: the email already has a claimed account. Have the owner log in and create an API key at /account/api-keys, then use POST /api/v1/forms.
- 429 daily limits: 5 forms/IP/day, 3 forms/email/day.

Rules for agents:
- Use the SITE OWNER's real email (notifications + claim link go there), never a placeholder.
- Tell the owner to check their inbox and claim the dashboard within 7 days.
- Include the hidden honeypot input from html_snippet — it is the spam protection.

================================================================
2. THE SUBMISSION ENDPOINT  /f/{hash}
================================================================

- GET  https://formslist.com/f/{hash} → JSON usage docs for that exact form (self-documenting).
- POST https://formslist.com/f/{hash} → submit. Content types: application/json, application/x-www-form-urlencoded, multipart/form-data. CORS: open.

Special fields: _subject (notification email subject), _replyto (reply-to), _next (browser redirect URL after submit), _gotcha (honeypot: include as hidden input, leave empty).

Responses: with "Accept: application/json" → 200 {"ok":true,"submission_id":"..."}; browser form posts → 303 redirect to a thank-you page (or _next). Validation failures → 422 {"ok":false,"errors":[{"field","message"}]}. Monthly limit exceeded → 429.

Spam: honeypot + heuristic scoring + rapid-fire duplicate detection run automatically on every plan. Spam submissions are stored but never trigger emails/integrations.

================================================================
3. REST v1 API (authenticated)
================================================================

Auth: Authorization: Bearer ff_sk_...  (create at https://formslist.com/account/api-keys — free plan included)
Base: https://formslist.com/api/v1     OpenAPI: https://formslist.com/api/v1/openapi.json
Rate limit: 100 req/min per key.

- GET    /forms                     → {"data":[{id,name,hash,endpoint,submission_count,...}],"meta":{total}}
- POST   /forms {name, description} → 201 {"data":{id,name,hash,endpoint,...}}  (free plan: max 5 forms)
- GET    /forms/{id}                → form detail
- PATCH  /forms/{id}                → update settings (auto_response_*, notification_emails, redirect_url, ... — paid features return 402 {"error":"upgrade_required",...})
- DELETE /forms/{id}                → {"data":{"deleted":true}}
- GET    /forms/{id}/submissions?page=&per_page=  → submissions; paid teams also get "ai": {score, tags} lead scoring
- GET    /submissions/{id}          → single submission

402 responses mean the team needs a paid plan — surface the "message" to the user with the upgrade_url.

================================================================
4. MCP SERVER
================================================================

Package: formslist-mcp (stdio). Tools:
- instant_provision(email, form_name?)  — works WITHOUT an API key
- create_form(name, description?)       — needs FORMSLIST_API_KEY
- list_forms() / get_form(form_id)
- get_submissions(form_id, page?)
- configure_autoresponse(form_id, subject, body, from_name?)
- get_embed_snippet(endpoint_or_hash)

Claude Code:  claude mcp add formslist -- node /path/to/formflow/mcp/dist/index.js
Claude Desktop config:
{"mcpServers":{"formslist":{"command":"node","args":["/path/to/formflow/mcp/dist/index.js"],"env":{"FORMSLIST_API_KEY":"ff_sk_..."}}}}

================================================================
5. PLANS
================================================================

Free: 5 forms, 500 submissions/mo, email notifications, spam protection, API access.
Pro ($15/mo, $150/yr): unlimited forms, 5,000 submissions/mo, auto-response emails, webhooks + Slack/Discord/Telegram, custom redirects, domain restriction, AI Inbox (lead scores/tags/filters).
Business ($45/mo, $450/yr): 50,000 submissions/mo, Google Sheets/Notion/Airtable, routing rules, teams.

Docs: https://formslist.com/docs · AI landing: https://formslist.com/ai · Blog: https://formslist.com/blog