FormBox API Documentation

Simple, powerful form endpoints with spam protection and AI intelligence

📖 Overview

FormBox provides instant form endpoints for your websites. No backend code required. Just point your form to your unique endpoint and we handle the rest.

📮 Download Postman Collection
🔌 Insomnia: Import → From URL → paste the Postman link above

Key Features

  • Instant Setup: Get your form endpoint in 30 seconds
  • Spam Protection: Built-in honeypot and rate limiting
  • AI Intelligence: Automatic lead scoring, sentiment analysis, intent detection
  • Email Notifications: Get notified instantly when someone submits
  • Webhooks: Connect to Zapier, Make, n8n, or any webhook endpoint
  • CSV Export: Export all submissions with one click

🚀 Quickstart

Get up and running in 3 steps:

1. Create Your Form

Sign up at formbox.gibby-workspace.com and create a form. You'll get a unique endpoint like:

URL
https://formbox.gibby-workspace.com/f/abc123def456

2. Add to Your Website

Point your HTML form to your endpoint:

HTML
<form action="https://formbox.gibby-workspace.com/f/YOUR_FORM_ID" 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"></textarea>
    
    <!-- Hidden honeypot for spam protection -->
    <input type="text" name="_honeypot" style="display:none">
    
    <button type="submit">Send Message</button>
</form>

3. View Submissions

Log in to your dashboard to see submissions, export CSV, or configure webhooks.

✓ That's it!

Your form is now live and collecting submissions with spam protection.

🔐 Authentication

FormBox uses per-form unique URLs for authentication. Each form has its own endpoint:

Pattern
https://formbox.gibby-workspace.com/f/{FORM_ID}

The form ID acts as your authentication token. Keep it private if you don't want unauthorized submissions.

⚠️ Security Note

Form IDs are not secret by design (they're in your HTML). Rate limiting and spam protection prevent abuse. For truly private forms, use server-side submission.

📬 Submit Form

POST/f/{form_id}

Submit data to your form. Accepts application/x-www-form-urlencoded or application/json.

Request Body

Field Type Description
* (any field) string Your form fields (name, email, message, etc.)
_honeypot string Hidden field for spam protection (must be empty)
_redirect string Optional: URL to redirect after submission
_ajax boolean Optional: Return JSON instead of redirect

Example Request (HTML Form)

HTML
<form action="https://formbox.gibby-workspace.com/f/abc123" method="POST">
    <input type="text" name="name" value="John Smith">
    <input type="email" name="email" value="[email protected]">
    <textarea name="message">I need help with...</textarea>
    <input type="text" name="_honeypot" style="display:none">
    <input type="hidden" name="_redirect" value="https://yoursite.com/thank-you">
    <button type="submit">Submit</button>
</form>

Example Request (JavaScript/AJAX)

JavaScript
// Using Fetch API
fetch('https://formbox.gibby-workspace.com/f/abc123', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        name: 'John Smith',
        email: '[email protected]',
        message: 'I need help with...',
        _honeypot: '', // Must be empty
        _ajax: true    // Return JSON response
    })
})
.then(response => response.json())
.then(data => {
    console.log('Success:', data);
    // { "status": "success", "message": "Form submitted successfully" }
})
.catch(error => console.error('Error:', error));

Response

For HTML forms, redirects to success page or _redirect URL.

For AJAX requests (_ajax: true), returns JSON:

JSON
{
    "status": "success",
    "message": "Form submitted successfully",
    "submission_id": "sub_abc123def456"
}
💡 AI Intelligence

All submissions are automatically analyzed for lead quality, sentiment, and intent. View AI insights in your dashboard.

🔗 Webhooks

Get notified in real-time when someone submits your form. Perfect for Zapier, Make, n8n, or custom integrations.

Setup

  1. Go to your form's Settings tab
  2. Enter your webhook URL
  3. Save settings

Webhook Payload

FormBox sends a POST request to your webhook URL with this payload:

JSON
{
    "form_id": "abc123def456",
    "form_name": "Contact Form",
    "submission_id": "sub_xyz789",
    "submitted_at": "2026-02-17T10:30:45Z",
    "data": {
        "name": "John Smith",
        "email": "[email protected]",
        "message": "I need help with my account"
    },
    "meta": {
        "ip": "173.233.2.71",
        "user_agent": "Mozilla/5.0...",
        "referrer": "https://yoursite.com/contact"
    },
    "ai": {
        "lead_score": 85,
        "sentiment": "positive",
        "intent": "high_interest",
        "summary": "User needs account assistance"
    }
}

Webhook Security

Webhooks are sent via POST with HTTPS. For additional security, verify the submission_id format matches FormBox's pattern.

⚠️ Retry Policy

Webhooks are retried up to 3 times with exponential backoff if your endpoint returns a non-200 status code.

📥 Export CSV

GET/api/forms/{form_id}/export.csv

Export all submissions for a form as CSV. Requires authentication (must be logged in).

Example Request

cURL
curl -X GET \
  'https://formbox.gibby-workspace.com/api/forms/abc123/export.csv' \
  -H 'Cookie: session=your_session_cookie'

Response

Returns a CSV file with all submissions:

CSV
Submitted At,Email,IP Address,User Agent,name,email,message,Lead Score,Sentiment,Intent
2026-02-17 10:30:45,[email protected],173.233.2.71,Mozilla/5.0...,John Smith,[email protected],Need help,85,positive,high_interest
2026-02-16 14:22:30,[email protected],192.168.1.100,Chrome...,Jane Doe,[email protected],Question,72,neutral,info_seeking
💡 Tip

You can also export CSV directly from the dashboard by clicking the "Export CSV" button on your form's submissions page.

⚠️ Error Codes

FormBox uses standard HTTP status codes to indicate success or failure.

Code Meaning Description
200 Success Form submitted successfully
400 Bad Request Missing required fields or invalid data
404 Not Found Form ID does not exist
429 Rate Limit Too many requests (see rate limits below)
422 Spam Detected Submission blocked by spam protection
500 Server Error Something went wrong on our end

Error Response Format

JSON
{
    "status": "error",
    "error": "rate_limit_exceeded",
    "message": "Too many submissions. Please try again in 60 seconds.",
    "retry_after": 60
}

⏱️ Rate Limits

FormBox enforces rate limits to prevent abuse and ensure fair usage.

Limit Type Free Tier Pro Tier Business Tier
Submissions per month 50 500 2,000
Submissions per IP/hour 5 20 50
Webhook requests - Unlimited Unlimited
Forms per account 3 25 Unlimited
⚠️ Rate Limit Headers

When approaching limits, responses include X-RateLimit-Remaining and X-RateLimit-Reset headers.

🛡️ Spam Protection

FormBox includes multiple layers of spam protection to keep your submissions clean.

Honeypot Field

Add a hidden field that humans won't see but bots will fill:

HTML
<input type="text" name="_honeypot" style="display:none">

If this field is filled, the submission is rejected as spam.

Rate Limiting

Submissions from the same IP are limited to prevent flooding (see rate limits above).

AI Analysis

All submissions are analyzed for spam patterns using AI. Suspicious submissions are flagged in your dashboard.

✓ Always Enabled

Spam protection is always on. No configuration needed.

💻 Code Examples

HTML Form (Basic)

HTML
<!DOCTYPE html>
<html>
<head>
    <title>Contact Us</title>
</head>
<body>
    <h1>Get in Touch</h1>
    
    <form action="https://formbox.gibby-workspace.com/f/YOUR_FORM_ID" 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" required></textarea>
        </label>
        
        <!-- Honeypot for spam protection -->
        <input type="text" name="_honeypot" style="display:none">
        
        <!-- Redirect after submission -->
        <input type="hidden" name="_redirect" value="https://yoursite.com/thank-you">
        
        <button type="submit">Send Message</button>
    </form>
</body>
</html>

JavaScript/AJAX

JavaScript
// Modern Fetch API
document.getElementById('contact-form').addEventListener('submit', async (e) => {
    e.preventDefault();
    
    const formData = new FormData(e.target);
    const data = Object.fromEntries(formData);
    data._ajax = true; // Return JSON instead of redirect
    
    try {
        const response = await fetch('https://formbox.gibby-workspace.com/f/YOUR_FORM_ID', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
            },
            body: JSON.stringify(data)
        });
        
        const result = await response.json();
        
        if (result.status === 'success') {
            alert('Thank you! Your message has been sent.');
            e.target.reset();
        } else {
            alert('Error: ' + result.message);
        }
    } catch (error) {
        console.error('Error:', error);
        alert('Something went wrong. Please try again.');
    }
});

React

JSX
import { useState } from 'react';

function ContactForm() {
    const [formData, setFormData] = useState({
        name: '',
        email: '',
        message: '',
        _honeypot: '' // Must remain empty
    });
    const [status, setStatus] = useState('');
    
    const handleSubmit = async (e) => {
        e.preventDefault();
        setStatus('Sending...');
        
        try {
            const response = await fetch('https://formbox.gibby-workspace.com/f/YOUR_FORM_ID', {
                method: 'POST',
                headers: {
                    'Content-Type': 'application/json',
                },
                body: JSON.stringify({ ...formData, _ajax: true })
            });
            
            const result = await response.json();
            
            if (result.status === 'success') {
                setStatus('Message sent successfully!');
                setFormData({ name: '', email: '', message: '', _honeypot: '' });
            } else {
                setStatus('Error: ' + result.message);
            }
        } catch (error) {
            setStatus('Something went wrong. Please try again.');
        }
    };
    
    const handleChange = (e) => {
        setFormData({
            ...formData,
            [e.target.name]: e.target.value
        });
    };
    
    return (
        <form onSubmit={handleSubmit}>
            <input
                type="text"
                name="name"
                value={formData.name}
                onChange={handleChange}
                placeholder="Your name"
                required
            />
            
            <input
                type="email"
                name="email"
                value={formData.email}
                onChange={handleChange}
                placeholder="Your email"
                required
            />
            
            <textarea
                name="message"
                value={formData.message}
                onChange={handleChange}
                placeholder="Your message"
                required
            /></textarea>
            
            {/* Hidden honeypot */}
            <input
                type="text"
                name="_honeypot"
                value={formData._honeypot}
                onChange={handleChange}
                style={{ display: 'none' }}
            />
            
            <button type="submit">Send Message</button>
            
            {status && <p>{status}</p>}
        </form>
    );
}

export default ContactForm;

Need help? Have questions?

Go to Dashboard →