← Back to FormGuard

Documentation

Integrate FormGuard into your website in under 5 minutes. One API call protects your contact forms from spam using AI classification, honeypots, and shared threat intelligence.

On this page

Quick Start

FormGuard works with any website. Send a POST request to our API with the form data, and we handle spam detection, AI classification, and email forwarding. No SDK needed.

Submit a form (any language)curl
curl -X POST https://hub.informationvillagelimited.com/api/formguard/submit \
  -H "Content-Type: application/json" \
  -d '{
    "project": "your-site-name",
    "name": "John Doe",
    "email": "john@example.com",
    "message": "I need a website built",
    "honeypot": "",
    "timestamp": 1711100000
  }'

Response: {"success": true, "message": "Thank you! Your message has been received.", "submission_id": 1}

That is it. FormGuard will classify the submission as legitimate, suspicious, or spam using AI, check against the shared blocklist, and store it for your review.

API Reference

Base URL: https://hub.informationvillagelimited.com/api/formguard

POST /submit

Submit a contact form for classification and storage.

FieldTypeRequiredDescription
projectstringYesYour site identifier (e.g. "my-website")
namestringYesSender name
emailstringYesSender email
messagestringYesForm message content
budgetstringNoBudget range (if applicable)
honeypotstringNoMust be empty. If filled, submission is silently rejected (bot detection)
timestampnumberNoUnix timestamp when form was loaded. If submitted too fast (<3s), flagged as bot

GET /submissions

List all submissions with optional filters.

Query parametersparams
project    - Filter by project name
classification - Filter by: legitimate, suspicious, spam
limit      - Results per page (default: 50)
offset     - Pagination offset

GET /stats

Get aggregate statistics.

POST /review/{submission_id}

Override AI classification. Query param: action=legitimate|spam|delete

Next.js Integration

app/contact/page.tsxtsx
"use client";
import { useState } from "react";

const FORMGUARD_API = "https://hub.informationvillagelimited.com/api/formguard/submit";

export default function ContactPage() {
  const [formData, setFormData] = useState({ name: "", email: "", message: "" });
  const [honeypot, setHoneypot] = useState("");
  const [formLoadTime] = useState(Date.now() / 1000);
  const [submitted, setSubmitted] = useState(false);

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    const res = await fetch(FORMGUARD_API, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        project: "my-nextjs-site",
        ...formData,
        honeypot,
        timestamp: formLoadTime,
      }),
    });
    const data = await res.json();
    if (data.success) setSubmitted(true);
  };

  if (submitted) return <p>Thank you! Message received.</p>;

  return (
    <form onSubmit={handleSubmit}>
      {/* Honeypot - hidden from humans */}
      <div style={{ position: "absolute", left: "-9999px" }}>
        <input value={honeypot} onChange={(e) => setHoneypot(e.target.value)} />
      </div>

      <input placeholder="Name" required
        onChange={(e) => setFormData({ ...formData, name: e.target.value })} />
      <input type="email" placeholder="Email" required
        onChange={(e) => setFormData({ ...formData, email: e.target.value })} />
      <textarea placeholder="Message" required
        onChange={(e) => setFormData({ ...formData, message: e.target.value })} />
      <button type="submit">Send</button>
    </form>
  );
}

SvelteKit Integration

src/routes/contact/+page.sveltesvelte
<script>
  let name = '', email = '', message = '', honeypot = '';
  let submitted = false;
  const loadTime = Date.now() / 1000;

  async function handleSubmit() {
    const res = await fetch(
      'https://hub.informationvillagelimited.com/api/formguard/submit',
      {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          project: 'my-sveltekit-site',
          name, email, message, honeypot,
          timestamp: loadTime,
        }),
      }
    );
    const data = await res.json();
    if (data.success) submitted = true;
  }
</script>

{#if submitted}
  <p>Thank you! Message received.</p>
{:else}
  <form on:submit|preventDefault={handleSubmit}>
    <div style="position:absolute;left:-9999px">
      <input bind:value={honeypot} />
    </div>
    <input bind:value={name} placeholder="Name" required />
    <input bind:value={email} type="email" placeholder="Email" required />
    <textarea bind:value={message} placeholder="Message" required />
    <button type="submit">Send</button>
  </form>
{/if}

Plain HTML Integration

contact.htmlhtml
<form id="contact-form">
  <!-- Honeypot (hidden) -->
  <div style="position:absolute;left:-9999px">
    <input name="honeypot" id="hp" />
  </div>

  <input name="name" placeholder="Name" required />
  <input name="email" type="email" placeholder="Email" required />
  <textarea name="message" placeholder="Message" required></textarea>
  <button type="submit">Send</button>
</form>

<script>
  const loadTime = Date.now() / 1000;
  document.getElementById('contact-form').addEventListener('submit', async (e) => {
    e.preventDefault();
    const form = e.target;
    const res = await fetch(
      'https://hub.informationvillagelimited.com/api/formguard/submit',
      {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          project: 'my-website',
          name: form.name.value,
          email: form.email.value,
          message: form.message.value,
          honeypot: form.honeypot.value,
          timestamp: loadTime,
        }),
      }
    );
    const data = await res.json();
    if (data.success) {
      form.innerHTML = '<p>Thank you! Message received.</p>';
    }
  });
</script>

Honeypot Setup

A honeypot is an invisible form field that humans never see but bots auto-fill. If the honeypot field is non-empty, FormGuard silently rejects the submission and adds the IP to the blocklist.

Always include a honeypot field in your form, positioned off-screen with CSS. Use position: absolute; left: -9999px or aria-hidden="true".

The timestamp field records when the form was loaded. If a submission arrives less than 3 seconds after load, it is flagged as a bot (humans cannot fill forms that fast).

Dashboard

View all submissions at the API endpoint:

List submissionscurl
# All submissions
curl https://hub.informationvillagelimited.com/api/formguard/submissions

# Filter by project
curl "https://hub.informationvillagelimited.com/api/formguard/submissions?project=my-site"

# Filter by classification
curl "https://hub.informationvillagelimited.com/api/formguard/submissions?classification=spam"

# Get stats
curl https://hub.informationvillagelimited.com/api/formguard/stats

Override AI classification for false positives:

Review a submissioncurl
# Mark as legitimate (false positive)
curl -X POST "https://hub.informationvillagelimited.com/api/formguard/review/123?action=legitimate"

# Mark as spam
curl -X POST "https://hub.informationvillagelimited.com/api/formguard/review/123?action=spam"

# Delete
curl -X POST "https://hub.informationvillagelimited.com/api/formguard/review/123?action=delete"

Webhooks (Coming Soon)

Webhook support for real-time notifications when legitimate submissions arrive. Configure a callback URL per project to receive instant POST notifications.

Built by Information Village Limited