API Reference

Everything you need to integrate BurnerBlocker. One endpoint, one header, instant fraud scoring.

Overview

BurnerBlocker is a REST API that scores transactions for fraud risk. Send an email address (and optionally an IP, BIN, or phone number) and get back a risk score (0–100) with a verdict: ALLOW, REVIEW, or BLOCK.

Authentication

All API requests require an API key passed in the x-api-key header:

x-api-key: bb_YOUR_API_KEY_HERE

You receive your API key via email after signing up. You can view and regenerate keys in your dashboard.

Base URL

https://api.burnerblocker.com

All endpoints are relative to this base. HTTPS only — plain HTTP will be rejected.

Rate Limits

Rate limits are based on your plan's monthly scan allocation:

When you exceed your monthly limit, the API returns 429 Too Many Requests. Your limit resets on the 1st of each month (UTC).

Scan a Transaction

Score a transaction across all available detection signals.

Request Headers

Request Body

Response

{
  "risk_score": 72,
  "verdict": "BLOCK",
  "checks": {
    "disposable_email": "FLAGGED",
    "email_velocity": "OK",
    "email_pattern_abuse": "OK",
    "email_entropy": "OK",
    "tor_node": "FLAGGED",
    "vpn_or_proxy": "OK",
    "datacenter_ip": "FLAGGED",
    "velocity_check": "OK",
    "ip_multi_account": "OK",
    "bin_risk": "HIGH",
    "bin_diversity": "OK",
    "phone_validation": "OK",
    "user_agent": "NOT_PROVIDED"
  }
}

Response Fields

Health Check

Returns the API status. No authentication required. Useful for uptime monitoring.

{
  "status": "healthy",
  "risk_engine": "active",
  "tor_nodes_loaded": 1247
}

Detection Signals

Each signal in the checks object returns one of these values:

Email Signals Free

IP Signals Paid

Card / BIN Signals Paid

Other Signals Paid

Verdicts

These are suggestions. You control how to act on each verdict in your own code.

Error Codes

Plans & Limits

Example: cURL

# Scan a transaction
curl -X POST https://api.burnerblocker.com/v1/scan \
  -H "x-api-key: bb_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "suspect@tempmail.com",
    "ip_address": "185.220.101.34",
    "bin": "424242"
  }'

Example: Python

import requests

resp = requests.post(
    "https://api.burnerblocker.com/v1/scan",
    headers={"x-api-key": "bb_YOUR_KEY"},
    json={
        "email": "suspect@tempmail.com",
        "ip_address": "185.220.101.34",
        "bin": "424242",
    },
)

data = resp.json()
if data["verdict"] == "BLOCK":
    # reject the transaction
    raise Exception("Fraudulent transaction blocked")
elif data["verdict"] == "REVIEW":
    # flag for manual review
    queue_for_review(order_id)
else:
    # all clear
    process_payment(order_id)

Example: Node.js

const res = await fetch("https://api.burnerblocker.com/v1/scan", {
  method: "POST",
  headers: {
    "x-api-key": "bb_YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email: "suspect@tempmail.com",
    ip_address: "185.220.101.34",
    bin: "424242",
  }),
});

const { risk_score, verdict, checks } = await res.json();

if (verdict === "BLOCK") {
  // reject the order
  return res.status(403).json({ error: "Order rejected" });
}

if (verdict === "REVIEW") {
  // add to review queue
  await flagForReview(orderId);
}

// Otherwise: proceed with payment

Example: Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func scanTransaction(email, ip, bin string) (map[string]interface{}, error) {
    payload, _ := json.Marshal(map[string]string{
        "email":      email,
        "ip_address": ip,
        "bin":        bin,
    })

    req, _ := http.NewRequest("POST",
        "https://api.burnerblocker.com/v1/scan",
        bytes.NewBuffer(payload))
    req.Header.Set("x-api-key", "bb_YOUR_KEY")
    req.Header.Set("Content-Type", "application/json")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)

    if result["verdict"] == "BLOCK" {
        fmt.Println("Transaction blocked!")
    }
    return result, nil
}

Example: PHP

<?php

$response = file_get_contents('https://api.burnerblocker.com/v1/scan', false,
    stream_context_create([
        'http' => [
            'method'  => 'POST',
            'header'  => "x-api-key: bb_YOUR_KEY\r\nContent-Type: application/json",
            'content' => json_encode([
                'email'      => 'suspect@tempmail.com',
                'ip_address' => '185.220.101.34',
                'bin'        => '424242',
            ]),
        ],
    ])
);

$data = json_decode($response, true);

if ($data['verdict'] === 'BLOCK') {
    // reject the transaction
    throw new Exception('Fraudulent transaction blocked');
}

if ($data['verdict'] === 'REVIEW') {
    // flag for manual review
    flagForReview($orderId);
}

Webhooks Paid

Get notified in real time when BurnerBlocker flags a transaction. Set your webhook URL and we'll POST to it whenever a scan returns BLOCK or REVIEW.

Set your webhook URL

curl -X PUT https://api.burnerblocker.com/v1/settings/webhook \
  -H "x-api-key: bb_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"webhook_url": "https://yourapp.com/hooks/burnerblocker"}'

Webhook payload

When a scan returns BLOCK or REVIEW, we POST this JSON to your URL:

{
  "event": "scan.flagged",
  "verdict": "BLOCK",
  "risk_score": 82,
  "email": "suspect@tempmail.com",
  "ip_address": "185.220.101.34",
  "checks": { /* full signal map */ }
}

Webhooks are best-effort with a 5-second timeout. No retries — design your endpoint to respond quickly.

Real-World Integrations

Copy-paste examples showing how to add BurnerBlocker to common flows. Each example includes the API call, verdict handling, and best practices.

Quick Start — 5 Lines

The fastest way to start blocking fraud. Drop this into any backend:

# Python — pip install requests
import requests

def is_fraudulent(email, ip=None):
    r = requests.post("https://api.burnerblocker.com/v1/scan", json={
        "email": email, "ip_address": ip
    }, headers={"x-api-key": "bb_YOUR_KEY"})
    return r.json()["verdict"] == "BLOCK"

# Usage: if is_fraudulent(user_email, user_ip): deny()

Stripe Checkout Integration

Scan the customer before creating a Stripe PaymentIntent. Block fraudulent cards before they cost you chargebacks.

import stripe, requests

BURNER_KEY = "bb_YOUR_KEY"

def create_payment(email, ip, card_bin, amount_cents):
    # 1. Scan with BurnerBlocker
    scan = requests.post("https://api.burnerblocker.com/v1/scan", json={
        "email": email,
        "ip_address": ip,
        "bin": card_bin,     # first 6 digits of card
    }, headers={"x-api-key": BURNER_KEY}).json()

    # 2. Act on verdict
    if scan["verdict"] == "BLOCK":
        raise Exception(f"Transaction blocked (score: {scan['risk_score']})")

    if scan["verdict"] == "REVIEW":
        # Flag for manual review but still process
        flag_for_review(email, scan)

    # 3. Safe to charge — create the PaymentIntent
    intent = stripe.PaymentIntent.create(
        amount=amount_cents,
        currency="usd",
        receipt_email=email,
        metadata={
            "bb_score": scan["risk_score"],
            "bb_verdict": scan["verdict"],
        }
    )
    return intent

Signup / Registration Protection

Block fake accounts at signup. Prevent burner email abuse on your free tier.

// Node.js / Express middleware
const axios = require('axios');

async function antifraudMiddleware(req, res, next) {
  const { email } = req.body;
  const ip = req.headers['x-forwarded-for'] || req.ip;

  try {
    const { data } = await axios.post(
      'https://api.burnerblocker.com/v1/scan',
      { email, ip_address: ip },
      { headers: { 'x-api-key': process.env.BB_API_KEY } }
    );

    if (data.verdict === 'BLOCK') {
      return res.status(403).json({
        error: 'Registration blocked — suspicious activity detected'
      });
    }

    // Attach score to request for downstream use
    req.riskScore = data.risk_score;
    req.riskVerdict = data.verdict;
    next();
  } catch (err) {
    // Fail open — don't block signups if our API is down
    console.error('BurnerBlocker error:', err.message);
    next();
  }
}

// Usage
app.post('/signup', antifraudMiddleware, signupHandler);

E-Commerce Order Protection

Full checkout scan with all signals — email, IP, BIN, and phone.

# Django view example
import requests
from django.http import JsonResponse

BB_KEY = "bb_YOUR_KEY"

def place_order(request):
    data = request.POST
    ip = request.META.get('HTTP_X_FORWARDED_FOR', request.META['REMOTE_ADDR'])

    # Full fraud scan — all signals
    scan = requests.post("https://api.burnerblocker.com/v1/scan", json={
        "email":      data["email"],
        "ip_address": ip.split(",")[0].strip(),
        "bin":        data["card_number"][:6],
        "phone":      data.get("phone"),
        "user_agent": request.META.get("HTTP_USER_AGENT"),
    }, headers={"x-api-key": BB_KEY}, timeout=3).json()

    if scan["verdict"] == "BLOCK":
        return JsonResponse({
            "error": "Order declined",
            "reason": "Our fraud detection flagged this transaction."
        }, status=403)

    if scan["verdict"] == "REVIEW":
        Order.objects.create(status="review", risk_score=scan["risk_score"], ...)
        return JsonResponse({"status": "pending_review"})

    # ALLOW — process normally
    Order.objects.create(status="confirmed", risk_score=scan["risk_score"], ...)
    charge_card(data)
    return JsonResponse({"status": "confirmed"})

💡 Best Practice: Always set a timeout on your API calls and fail open — if BurnerBlocker is unreachable, let the transaction through rather than blocking legitimate customers.