🔌 ScamDB API Documentation

Integrate scam checking into your applications

Getting Started

The ScamDB API allows you to programmatically check if phone numbers, emails, or websites are known scams. All API requests require an API key.

📋 Request Your API Key

API keys are currently managed by admins. Contact the admin team to request an API key for your application.

📡 API Endpoints

1. Check if Something is a Scam

Query Parameters:

• phone - Phone number to check
• email - Email address to check
• website - Website URL to check

Example Request:

curl -X GET "https://darkseclabs.com/api/v1/check?phone=%2B1234567890" \
  -H "X-API-Key: scamdb_your_api_key_here"

Example Response:

{
  "found": true,
  "total_reports": 5,
  "verified_reports": 3,
  "total_amount_lost": 15000,
  "reports": [
    {
      "report_id": "RPT_1234567890_abc123",
      "scam_type": "Phishing",
      "title": "Fake tech support scam",
      "description": "Called pretending to be from Microsoft...",
      "phone": "+1234567890",
      "verified": true,
      "created_at": "2024-01-15T10:30:00.000Z"
    }
  ]
}

2. Get Statistics

Example Request:

curl -X GET "https://darkseclabs.com/api/v1/stats" \
  -H "X-API-Key: scamdb_your_api_key_here"

Example Response:

{
  "statistics": {
    "total_reports": 1247,
    "verified_reports": 856,
    "total_amount_lost": 2450000,
    "unique_scammers": {
      "phones": 423,
      "emails": 312,
      "websites": 189
    },
    "by_scam_type": [
      { "scam_type": "Phishing", "count": 456 },
      { "scam_type": "Romance Scam", "count": 234 }
    ]
  }
}

3. Submit a Report

Request Body (JSON):

{
  "scam_type": "Phishing",
  "title": "Fake tech support",
  "description": "Called pretending to be from Microsoft...",
  "phone": "+1234567890",
  "email": "scammer@example.com",
  "website": "https://fake-site.com",
  "amount_lost": 500,
  "currency": "USD"
}

Example Request:

curl -X POST "https://darkseclabs.com/api/v1/report" \
  -H "X-API-Key: scamdb_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"scam_type":"Phishing","title":"Fake tech support",
       "description":"Called pretending to be from Microsoft",
       "phone":"+1234567890"}'

📊 Rate Limiting

All API responses include rate limit headers:

• X-RateLimit-Limit: Total requests allowed per day (100)
• X-RateLimit-Remaining: Requests remaining today
• X-RateLimit-Reset: When your limit resets (ISO 8601 timestamp)

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

⚠️ Error Handling

All errors follow this format:

{
  "error": "Rate limit exceeded",
  "message": "Free tier allows 100 requests per day",
  "limit": 100,
  "reset": "2024-01-16T00:00:00.000Z"
}

Common HTTP Status Codes:

• 200 - Success
• 201 - Created (report submitted)
• 400 - Bad Request (missing parameters)
• 401 - Unauthorized (invalid/missing API key)
• 429 - Too Many Requests (rate limit exceeded)

💡 Use Cases

🔑 Need an API Key?

Contact the admin team to request API access for your application

Admin Portal