DOCUMENTATION

Simple API Integration

Get started in minutes with our straightforward API. One endpoint, clear responses, no complexity.

Quick Start

1. Get your API key

Sign up for a free account and find your API key in the dashboard.

2. Send form data to our endpoint

POST your form data to our API endpoint with your API key.

3. Handle the response

Check if the submission is spam and process accordingly.

API Endpoint

POST https://forms.nomospam.dev/api/forms/submit

Request

Headers

Content-Type: application/json
X-API-Key: your_api_key_here

Body

{
  "email": "user@example.com",
  "name": "John Doe",
  "message": "I'm interested in your services",
  "ip": "192.168.1.1",
  "user_agent": "Mozilla/5.0...",
  "referer": "https://yoursite.com/contact",
  "honeypot": "",
  "submit_time": 15.2,
  "fields": {
    "company": "Acme Corp",
    "phone": "+1234567890"
  }
}

Parameters

email REQUIRED

The email address from the form submission

message REQUIRED

The main message content

ip OPTIONAL

Client IP address (helps with detection)

honeypot OPTIONAL

Hidden field value (should be empty for humans)

submit_time OPTIONAL

Time in seconds to complete the form

fields OPTIONAL

Additional form fields as key-value pairs

Response

Success Response

{
  "success": true,
  "is_spam": false,
  "score": 0.12,
  "reasons": [],
  "id": "sub_1234567890"
}

Spam Detected Response

{
  "success": true,
  "is_spam": true,
  "score": 0.94,
  "reasons": [
    "honeypot_filled",
    "suspicious_content",
    "disposable_email"
  ],
  "id": "sub_1234567891"
}

Response Fields

is_spam

Boolean indicating if submission is spam

score

Spam probability score (0.0 to 1.0)

reasons

Array of detection reasons if spam

id

Unique submission ID for reference

Code Examples

JavaScript / Node.js

const response = await fetch('https://forms.nomospam.dev/api/forms/submit', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your_api_key_here'
  },
  body: JSON.stringify({
    email: formData.email,
    name: formData.name,
    message: formData.message,
    honeypot: formData.honeypot || '',
    submit_time: (Date.now() - startTime) / 1000
  })
});

const result = await response.json();

if (result.is_spam) {
  // <T key="docs.codeComments.handleSpam" />
  console.log('<T key="docs.codeComments.spamDetected" />', result.reasons);
} else {
  // <T key="docs.codeComments.processLegitimate" />
  await saveToDatabase(formData);
}

Python

import requests
import time

start_time = time.time()

# After form submission
response = requests.post(
    'https://forms.nomospam.dev/api/forms/submit',
    headers={
        'Content-Type': 'application/json',
        'X-API-Key': 'your_api_key_here'
    },
    json={
        'email': form_data['email'],
        'name': form_data['name'],
        'message': form_data['message'],
        'honeypot': form_data.get('honeypot', ''),
        'submit_time': time.time() - start_time
    }
)

result = response.json()

if result['is_spam']:
    # <T key="docs.codeComments.handleSpamShort" />
    print(f"<T key="docs.codeComments.spamDetected" /> {result['reasons']}")
else:
    # <T key="docs.codeComments.processLegitimateShort" />
    save_to_database(form_data)

PHP

$data = [
    'email' => $_POST['email'],
    'name' => $_POST['name'],
    'message' => $_POST['message'],
    'honeypot' => $_POST['honeypot'] ?? '',
    'submit_time' => microtime(true) - $_SESSION['form_start_time']
];

$ch = curl_init('https://forms.nomospam.dev/api/forms/submit');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'X-API-Key: your_api_key_here'
]);

$response = curl_exec($ch);
$result = json_decode($response, true);

if ($result['is_spam']) {
    // <T key="docs.codeComments.handleSpamShort" />
    error_log('<T key="docs.codeComments.spamDetected" /> ' . implode(', ', $result['reasons']));
} else {
    // <T key="docs.codeComments.processLegitimateShort" />
    save_to_database($data);
}

Error Handling

400 Bad Request

Missing required fields or invalid data format

401 Unauthorized

Invalid or missing API key

429 Too Many Requests

Rate limit exceeded for your API key

500 Internal Server Error

Server error - please retry or contact support

Rate Limits

PLAN REQUESTS/MINUTE REQUESTS/MONTH
Free 10 100
Pro 100 10,000
Enterprise Unlimited Unlimited

Webhook Notifications

Get real-time notifications when forms are submitted. Configure webhooks to receive detailed submission data and status updates.

Webhook Configuration

Configure your webhook settings in the dashboard to receive notifications:

Webhook URL

The endpoint that will receive webhook notifications

Webhook Secret

Secret key for verifying webhook signatures

Include Error Details

Include detailed error information in webhook payload

Include Webhook Status

Return webhook delivery status in API response

Webhook Payload

{
  "event": "form.submission",
  "data": {
    "submission_id": "sub_1234567890",
    "form_id": "form_abc123",
    "status": "processed",
    "submitted_at": "2024-01-15T10:30:00Z",
    "data": {
      "email": "user@example.com",
      "name": "John Doe",
      "message": "Contact message content"
    },
    "metadata": {
      "ip_address": "192.168.1.1",
      "user_agent": "Mozilla/5.0..."
    },
    "spam_detection": {
      "is_spam": false,
      "confidence_score": 0.12,
      "signals": []
    }
  },
  "timestamp": "2024-01-15T10:30:01Z"
}

Webhook Headers

X-NMS-Signature

HMAC-SHA256 signature of the payload

X-NMS-Timestamp

ISO 8601 timestamp of the webhook event

Response Status

When 'Include Webhook Status' is enabled, the API response includes webhook delivery information:

{
  "success": true,
  "data": {
    "id": "sub_1234567890",
    "status": "processed",
    "message": "Thank you for your submission",
    "webhook_status": {
      "delivered": true,
      "status": "processed",
      "errors": [],
      "details": {
        "webhook": {
          "sent": true,
          "url": "https://your-site.com/webhook",
          "status_code": 200,
          "response_time_ms": 145
        }
      }
    }
  }
}

Signature Verification

Verify webhook authenticity using HMAC-SHA256:

const crypto = require('crypto');

// Verify webhook signature
const signature = request.headers['x-nms-signature'];
const timestamp = request.headers['x-nms-timestamp'];
const payload = JSON.stringify(request.body);

const expectedSignature = crypto
  .createHmac('sha256', webhookSecret)
  .update(payload)
  .digest('hex');

if (signature === expectedSignature) {
  // Webhook is authentic
  processWebhook(request.body);
}

Need help?

Our API is designed to be simple, but we're here if you need us.

Contact Support