API Reference

This section provides detailed information about Formonger’s API endpoints, authentication, and data formats.

Base URL

https://api.formonger.com

Authentication

All API requests require authentication using your endpoint’s API key. Include the key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Security Notes

• Keep your API key secure - never expose it in client-side code
• API keys are tied to specific endpoints and cannot be used across different endpoints
• Keys are hashed and stored securely - they cannot be recovered if lost

Endpoints

POST /submit

Submit form data to your endpoint.

Request

POST /submit
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
 
{
  "name": "John Doe",
  "email": "john@example.com",
  "message": "Hello, this is my message"
}

Parameters

Response

Success (200)

{
  "success": true,
  "message": "Form submitted successfully",
  "submission_id": "sub_1234567890abcdef"
}

Validation Error (400)

{
  "error": "Validation failed",
  "details": {
    "email": {
      "issues": [
        {
          "code": "invalid_string",
          "message": "Invalid email",
          "path": ["email"],
          "validation": "email"
        }
      ],
      "name": "ZodError"
    }
  }
}

Rate Limit Exceeded (429)

{
  "error": "Submission limit exceeded",
  "message": "You have reached your monthly limit of 100 submissions. Please upgrade your plan.",
  "limit": 100,
  "remainingSubmissions": 0
}

Spam Detected (429)

{
  "error": "Submission could not be processed",
  "message": "Your submission appears to be spam and has been blocked."
}

Rate Limiting

Formonger implements rate limiting to prevent abuse:

• Per-endpoint limits: Based on your plan’s submission allowance
• IP-based rate limiting: Additional protection against automated attacks
• Automatic retries: Failed requests due to rate limiting can be retried after a cooldown period

Data Validation

All submissions are validated against your endpoint’s JSON schema:

Supported Field Types

• string: Text fields
• number: Numeric values
• boolean: True/false values
• object: Nested objects
• array: Lists of values

Validation Rules

• required: Field must be present
• min/max: String length or numeric ranges
• email: Email format validation
• url: URL format validation
• pattern: Regular expression matching

Example Schema

{
  "name": {
    "type": "string",
    "required": true,
    "minLength": 2,
    "maxLength": 100
  },
  "email": {
    "type": "string",
    "required": true,
    "format": "email"
  },
  "age": {
    "type": "number",
    "minimum": 18,
    "maximum": 120
  },
  "newsletter": {
    "type": "boolean",
    "default": false
  }
}

Spam Protection

Formonger includes built-in spam detection that runs automatically on all submissions:

Detection Methods

• Content Analysis: Scans for spam keywords and patterns
• Behavioral Analysis: Monitors submission timing and patterns
• Honeypot Fields: Hidden fields that should remain empty
• Link Limits: Configurable maximum number of links allowed

Spam Scoring

Each submission receives a spam score from 0-100:

• 0-25: Low risk - likely legitimate
• 26-50: Medium risk - requires review
• 51-75: High risk - suspicious
• 76-100: Very high risk - blocked automatically

Custom Rules (Pro Plan)

Pro and higher plans can configure:

• Custom spam keywords
• Link limits
• Advanced filtering rules

Error Handling

HTTP Status Codes

Error Response Format

{
  "error": "Error type",
  "message": "Human-readable error message",
  "details": {
    // Additional error-specific information
  }
}

Webhooks

Configure webhooks to receive real-time notifications when form submissions are processed.

Webhook Payload

{
  "event": "submission.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "endpoint": {
    "id": "ep_1234567890abcdef",
    "name": "Contact Form"
  },
  "submission": {
    "id": "sub_1234567890abcdef",
    "data": {
      "name": "John Doe",
      "email": "john@example.com",
      "message": "Hello!"
    },
    "spam_score": 5,
    "ip_address": "192.168.1.1",
    "user_agent": "Mozilla/5.0...",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Webhook Security

• Signature Verification: Webhooks include a signature for verification
• Retry Logic: Failed webhook deliveries are automatically retried
• Timeout: Webhooks timeout after 10 seconds

SDKs and Libraries

Official SDKs (WIP)

• JavaScript/TypeScript: npm install @formonger/js-sdk
• Python: pip install formonger-python
• PHP: composer require formonger/php-sdk

Libraries (WIP)

• React Hook: @formonger/react
• Vue Plugin: @formonger/vue
• Laravel Package: formonger/laravel

Performance

1. Batch submissions when possible
2. Implement client-side validation to reduce server requests
3. Use appropriate field types for better validation performance
4. Monitor your usage to avoid hitting rate limits

Error Handling

1. Handle all error responses appropriately
2. Implement retry logic for transient failures
3. Log errors for debugging purposes
4. Provide user feedback for form submission failures

Support

Need help with the API? Contact our support team:

• Email: support@formonger.com
• Documentation: docs.formonger.com