Back to Documentation

API Reference

Integrate ClickDefender directly into your application with our REST API.

Authentication

All API requests require authentication using your property API key. Include it in the x-api-key header.

curl -X POST https://www.clickdefender.app/api/clickdefender/events \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "page_view", "url": "https://example.com"}'

Keep your API key secret! Never expose it in client-side code. Use our JavaScript SDK for browser-based tracking.

Base URL

https://www.clickdefender.app/api/clickdefender

All API endpoints are served over HTTPS. HTTP requests will be redirected.

Rate Limits

API requests are rate-limited per property:

  • 1,000 requests per minute per property
  • Rate limit headers are included in all responses
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1704067200

If you exceed the rate limit, you'll receive a 429 Too Many Requests response.

Endpoints

POST/events

Track a visitor event (page view, click, conversion)

Request Body

{
  "type": "page_view" | "click" | "conversion",
  "url": "https://example.com/landing",
  "referrer": "https://google.com",
  "visitorId": "visitor_abc123",
  "gclid": "CjwKCAjw...",
  "data": {
    "userAgent": "Mozilla/5.0...",
    "scrollDepth": 75,
    "timeOnPage": 45000
  }
}

Response (200 OK)

{
  "success": true,
  "eventId": "evt_abc123xyz",
  "visitorId": "vis_xyz789"
}

GET/decision

Get fraud decision for a visitor

Query Parameters

GET /decision?visitorId=vis_xyz789

Response (200 OK)

{
  "score": 85,
  "label": "FRAUD",
  "action": "BLOCK",
  "reasons": [
    {"rule": "datacenter_ip", "score": 25, "details": "AWS IP range"},
    {"rule": "rapid_clicks", "score": 30, "details": "15 clicks in 60s"},
    {"rule": "short_dwell", "score": 20, "details": "3s on page"},
    {"rule": "honeypot", "score": 40, "details": "Clicked hidden link"}
  ]
}
CLEAN
Score 0-39
SUSPICIOUS
Score 40-69
FRAUD
Score 70+

GET/property/:id/blocklist

Get blocked IP addresses for a property

Query Parameters

  • format - Response format: json (default) or csv
  • days - Number of days to include (default: 30)

Response (200 OK)

{
  "blocklist": [
    {
      "ip": "192.168.1.100",
      "score": 85,
      "lastSeen": "2024-01-05T12:00:00Z",
      "reason": "Repeat clicks, datacenter IP"
    }
  ],
  "total": 127,
  "generatedAt": "2024-01-05T14:30:00Z"
}

GET/property/:id/stats

Get fraud statistics for a property

Query Parameters

  • range - Time range: today, 7days, 30days, 90days

Response (200 OK)

{
  "totalEvents": 15420,
  "totalDecisions": 12350,
  "cleanCount": 11200,
  "suspiciousCount": 850,
  "fraudCount": 300,
  "fraudRate": "2.4%",
  "topRules": [
    {"rule": "datacenter_ip", "count": 180},
    {"rule": "repeat_clicks", "count": 95}
  ]
}

Error Handling

All errors follow a consistent format:

{
  "error": "Error message here",
  "code": "ERROR_CODE",
  "details": {}
}
Status
Code
Description
400
INVALID_REQUEST
Malformed request body
401
UNAUTHORIZED
Missing or invalid API key
402
PAYMENT_REQUIRED
Subscription inactive or trial expired
404
NOT_FOUND
Resource not found
429
RATE_LIMITED
Too many requests
500
SERVER_ERROR
Internal server error

Code Examples

JavaScript / Node.js

const response = await fetch('https://www.clickdefender.app/api/clickdefender/events', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.CLICKDEFENDER_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'click',
    url: 'https://example.com/landing',
    visitorId: 'vis_xyz789',
  }),
});

const result = await response.json();
console.log('Event tracked:', result.eventId);

Python

import requests
import os

response = requests.post(
    'https://www.clickdefender.app/api/clickdefender/events',
    headers={
        'x-api-key': os.environ['CLICKDEFENDER_API_KEY'],
        'Content-Type': 'application/json',
    },
    json={
        'type': 'click',
        'url': 'https://example.com/landing',
        'visitorId': 'vis_xyz789',
    }
)

result = response.json()
print(f"Event tracked: {result['eventId']}")

cURL

curl -X POST https://www.clickdefender.app/api/clickdefender/events \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "click",
    "url": "https://example.com/landing",
    "visitorId": "vis_xyz789"
  }'

Need Help?

Questions about the API? We're here to help.