Documentation

Quick Start

1. Create an account and add a project in your dashboard.

2. Copy your API key.

3. Add the FormShield script to your site:

<script src="https://formshield.dev/s.js" data-key="fs_live_your_key"></script>

That's it. FormShield will automatically protect all forms on the page.

How It Works

The script automatically injects an invisible honeypot field into every form, tracks how long the page has been open (timing analysis), and intercepts form submissions.

When a form is submitted, FormShield sends the form metadata to our API for scoring. The scoring engine uses multiple layers:

Honeypot detection (bots fill hidden fields)
Timing analysis (bots submit too fast)
Content heuristics (spam keywords, link density, all-caps)
IP signals (flood detection, datacenter IPs)
User agent analysis (known bot signatures)

Each signal adds to a 0-100 spam score. Submissions are classified as:

ham (score < 30) — real message, passes through
review (30-69) — uncertain, flagged for review
spam (score ≥ 70) — blocked silently

API Reference

POST /api/v1/check

Score a form submission.

// Request

curl -X POST https://formshield.dev/api/v1/check \
  -H "Authorization: Bearer fs_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": { "name": "John", "email": "john@example.com", "message": "Hello!" },
    "honeypot": "",
    "timing": 5200,
    "url": "https://example.com/contact"
  }'

// Response

{
  "verdict": "ham",
  "score": 5,
  "id": "sub_abc123"
}

Custom Integration

If you prefer not to use the script tag, you can call the API directly from your backend. This is useful for server-side form handling.

The formshield:blocked custom event is dispatched on the form element when a submission is blocked. You can listen for this to show a custom message:

form.addEventListener("formshield:blocked", (e) => {
  console.log("Blocked:", e.detail);
  // Show "submission received" to avoid tipping off spammers
});