Form Shield Integration Guide

If you're not using WordPress, you can integrate Form Shield directly via the Public API. This guide covers the request/response format and integration patterns.

Architecture

Your Application
    ↓ Form submission received
Your Backend
    ↓ POST /api/v1/forms/analyze (with Bearer API key + form data)
TrolleyShield API
    ↓ AI analysis
    ↓ Returns intent classification
Your Backend
    ↓ Allow, flag, or block based on result
Your Application

Prerequisites

1. A TrolleyShield account on a paid plan (Forms, Starter, Growth, or Agency)
2. An API key created from Settings → API Keys in your dashboard

Quick Example

curl -X POST https://app.trolleyshield.com/api/v1/forms/analyze \
  -H "Authorization: Bearer tsk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "form_data": {
      "name": "John Doe",
      "email": "john@example.com",
      "message": "I need a quote for roof repair"
    },
    "site_url": "https://yoursite.com",
    "form_id": "contact-form",
    "behavioral_score": 85,
    "ip_address": "203.0.113.50"
  }'

Response

{
  "intent": "legitimate",
  "confidence": 95,
  "reasoning": "Professional inquiry with specific service request and valid contact details.",
  "action": "allow",
  "ai_analysis": true,
  "ip_reputation": null
}

Handling Results

Based on the action field in the response:

const result = await response.json();

switch (result.action) {
  case 'allow':
    // Accept the submission normally
    saveSubmission(formData);
    break;
  case 'flag':
    // Accept but mark for review
    saveSubmission(formData, { flagged: true });
    break;
  case 'block':
    // Reject the submission
    return { error: 'Your submission could not be processed.' };
}

Behavioral Scoring

For best results, implement client-side behavioral scoring and include it in the request. The behavioral score (0-100) measures human-like interaction:

• Mouse movement patterns — bots don't move the mouse naturally
• Typing cadence — real humans have variable typing speed
• Time on page — bots submit forms instantly
• Scroll behavior — real users scroll to read content
• Field focus patterns — humans tab between fields naturally

A score below 40 is a strong bot indicator. Include it as behavioral_score in your API request. If omitted, it defaults to 50.

Failsafe Behavior

If the TrolleyShield API is unreachable or returns an error, always allow the submission to prevent blocking legitimate users due to an API outage:

try {
  const result = await analyzeForm(formData);
  handleResult(result);
} catch (error) {
  // API unavailable — allow submission
  saveSubmission(formData);
}

Full API Reference

See the Forms Analyze API reference for the complete request/response specification, including error codes and code examples in multiple languages.