🛡️ RiskScore API Documentation

Enterprise-grade fraud detection API with tier-specific features. Protect your platform from fraudulent users with AI-powered risk scoring.

🚀 Quick Start in 30 Seconds

Get your API key at forgeapis.com/signup
Make your first API call:

curl -X POST https://api.forgeapis.com/risk-check \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'
                

Check your usage at /dashboard

💎 Pricing & Features

Feature	Free	Starter ($29/mo)	Business ($99/mo)
API Calls/Month	100	1,000	5,000
Email Analysis	✓	✓	✓
Basic IP Detection	✓	✓	✓
Phone Analysis	✗	✓	✓
Advanced IP Intelligence	✗	✓	✓
Webhook Notifications	✗	✓	✓
Custom Risk Thresholds	✗	✗	✓
Batch Processing	✗	✗	✓
Advanced ML Patterns	✗	✗	✓

🔐 Authentication

All API requests require an X-API-Key header:

X-API-Key: rsk_live_your_api_key_here

💡

Pro Tip: Store your API key in environment variables, never hardcode it in your application.

📍 Core API Endpoints

POST /risk-check ALL TIERS

Main endpoint for comprehensive risk assessment. Analyzes user data and returns fraud risk score.

Request Body

{
  "email": "user@example.com",       // Required
  "ip_address": "192.168.1.1",      // Optional (Starter+)
  "phone": "+1234567890"             // Optional (Starter+)
}
                

Response

{
  "risk_score": 75,
  "confidence": 25,
  "signals_detected": [
    "🚨 Disposable email provider detected",
    "🌍 Location: United States",
    "🎯 Threshold 'Block High Risk' triggered: BLOCK"
  ],
  "recommendation": "HIGH_RISK",
  "risk_factors": ["Known temporary email service"],
  "data_sources": ["Email Analysis", "IP Intelligence"],
  "timestamp": "2024-01-15T10:30:00Z",
  "request_id": "uuid-here"
}
                

📊

Risk Score Interpretation:
0-30: LOW_RISK - Likely legitimate user
31-70: MODERATE_RISK - Requires review
71-100: HIGH_RISK - High fraud probability

POST /batch-risk-check BUSINESS ONLY

Process up to 100 users in a single API call. Perfect for bulk verification and user imports.

Request Body

{
  "items": [
    {
      "reference_id": "user_001",
      "email": "john@example.com",
      "ip_address": "192.168.1.1",
      "phone": "+1234567890"
    },
    {
      "reference_id": "user_002",
      "email": "jane@example.com"
    }
  ]
}
                

CSV Upload Format (Dashboard)

email,ip_address,phone,reference_id
john@example.com,192.168.1.1,+1234567890,user_001
jane@example.com,,,user_002
                

🔔 Webhook Management

⚡

Available for Starter and Business plans only

POST /webhook-config STARTER+

Configure webhook notifications for usage alerts.

Available Events

usage_80_percent - Triggered at 80% usage
usage_95_percent - Triggered at 95% usage
monthly_limit_reached - Triggered when limit reached

Webhook Signature Verification

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return f"sha256={expected}" == signature
                

🎯 Custom Risk Thresholds

💼

Available for Business plan only

POST /thresholds BUSINESS ONLY

Create automated actions based on risk scores.

Available Actions

block - Automatically deny the user
flag - Flag for manual review
review - Require additional verification
allow - Explicitly allow despite score
webhook - Trigger custom webhook

💻 Integration Examples

JavaScript/Node.js

const response = await fetch('https://api.forgeapis.com/risk-check', {
  method: 'POST',
  headers: {
    'X-API-Key': 'rsk_live_your_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'user@example.com',
    ip_address: req.ip
  })
});

const result = await response.json();

if (result.risk_score > 70) {
  // High risk - require additional verification
  return { action: 'block', reason: result.risk_factors };
}
            

Python

import requests

response = requests.post(
    'https://api.forgeapis.com/risk-check',
    headers={
        'X-API-Key': 'rsk_live_your_key',
        'Content-Type': 'application/json'
    },
    json={
        'email': 'user@example.com',
        'ip_address': '192.168.1.1'
    }
)

result = response.json()

if result['risk_score'] > 70:
    # High risk detected
    print(f"Blocked: {result['risk_factors']}")
            

🚨 Error Codes

Code	Description	Solution
401	Invalid or missing API key	Check X-API-Key header
403	Feature not available in plan	Upgrade to required plan
429	Rate limit exceeded	Wait or upgrade plan
400	Invalid request format	Check request body
500	Internal server error	Contact support

🔒 Security Best Practices

⚠️

Important: Never expose API keys in client-side code or public repositories.

Store API keys in environment variables
Rotate keys regularly via dashboard
Always verify webhook signatures
Use HTTPS endpoints only
Implement request timeouts (5 seconds recommended)
Handle rate limits gracefully with exponential backoff

Disclaimer: RiskScore provides risk intelligence signals for fraud prevention. This is NOT a legal age verification or identity verification service.