RTB Domains API

🔐 Security: Two-Key System

Your campaign uses two separate API keys for security:

Why two keys? This prevents traffic sources from manipulating their own bidding modifiers by adding themselves to boost lists or removing competitors.

Quick Start: Bidding Endpoint

Get dynamic bid prices and destination URLs based on country, OS, browser, and traffic source.

Endpoint

GET https://app.rtbdomains.com/bids/

Required Parameters

Domain Matching & Modifiers

The bidding system supports two types of domain matching:

1. Exact Domain Matching (Lists)

Lists contain exact domain names and apply modifiers when the source domain exactly matches.

List "Premium Sites" (2x modifier)
Domains: example.com, test.com

src=example.com → List matches → 2x modifier applied
src=example.net → No match → 1x modifier (no effect)

2. Contains Pattern Matching (Pattern Rules)

Pattern Rules contain keywords and apply modifiers when the source domain contains the pattern anywhere.

Pattern Rule "Apple Boost" (1.3x modifier)
Patterns: apple, mac, iphone

src=applestore.com → Contains "apple" → 1.3x modifier
src=pineapple.com → Contains "apple" → 1.3x modifier
src=macdeals.net → Contains "mac" → 1.3x modifier
src=google.com → No match → 1x modifier

How Modifiers Stack

When multiple lists and pattern rules match, modifiers multiply together:

Base Bid: $0.10
List #1 matches (2x) + Pattern Rule matches (1.3x)
Final Bid: $0.10 × 2 × 1.3 = $0.26

Response Format

{
  "country": "us",
  "src": "example.com",
  "os": "windows",
  "browser": "chrome",
  "time": "14:30",
  "bid": 1.5,
  "url": "https://destination.com/?cpc=1.5&domain=example.com"
}

Response Fields

Example Request

GET https://app.rtbdomains.com/bids/?api=YOUR_API_KEY&cc=us&ua=Mozilla%2F5.0%20(Windows%20NT%2010.0%3B%20Win64%3B%20x64)%20AppleWebKit%2F537.36%20(KHTML%2C%20like%20Gecko)%20Chrome%2F120.0.0.0%20Safari%2F537.36&src=example.com

Error Responses

The bidding API returns specific error codes for validation failures:

Example Error Response

{
  "error": "Invalid source domain format",
  "message": "Domain must contain only letters, numbers, hyphens, dots, and underscores"
}

Click Tracking

The url field in the bid response contains a signed tracking URL that logs actual clicks before redirecting to your destination.

How It Works

1. User clicks the tracking URL from your bid response
2. Request is verified (HMAC-SHA256 signature + timestamp check)
3. Click is logged to Analytics Engine (actual spend tracking)
4. User is redirected (301) to your destination URL

Security Features

• HMAC-SHA256 Signatures: Prevents URL tampering and open redirect attacks
• 5-Minute Expiry: Tracking URLs expire after 5 minutes to prevent replay attacks
• Constant-Time Verification: Prevents timing attacks on signature validation

Click Endpoint

GET https://app.rtbdomains.com/click/{signed_data}

Click Tracking Error Responses

Note: You don't need to call this endpoint directly. Traffic sources automatically click the URL returned in the bid response.

Features

• ⚡ Optimized Performance: ~100ms average response times globally
• 🎯 Advanced Targeting: Country, OS, and browser-based rules
• 📊 Domain Lists: Boost or reduce bids for specific sources
• 🔍 Pattern Matching: Substring-based rules for flexible targeting
• ⏰ Time-Based Modifiers: Adjust bids by hour, day, or date range
• 📈 Real-Time Analytics: Track impressions, clicks, and revenue
• 🔒 HMAC-Secured Tracking: Tamper-proof click tracking with signature verification

Programmatic Reporting API

Retrieve statistics and performance data using your API key. Perfect for external dashboards and automated reporting.

Authentication

Use either your bidding key or management key as a query parameter: ?api_key=YOUR_KEY

GET /api/v1/stats

Statistics report for a SINGLE DAY aggregated by subId (source domain), detailing impressions and revenue

GET https://app.rtbdomains.com/api/v1/stats?api_key=YOUR_KEY&date=2025-11-18

Response:
{
  "success": true,
  "data": [
    {
      "subId": "example.com",
      "source": "example.com",
      "impressions": 523,
      "clicks": 15,
      "revenue": 7.50,
      "ctr": 2.87,
      "date": "2025-11-18"
    }
  ],
  "meta": {
    "date": "2025-11-18",
    "returned_sources": 15,
    "total_impressions": 2000,
    "total_clicks": 60,
    "total_revenue": 30.00,
    "filters": {
      "min_revenue": 0.0000001,
      "limit": 10000
    },
    "note": "Showing sources with revenue > $0. Use ?min_revenue=0 to include zero-revenue sources."
  }
}

Query Parameters

• api_key (required): Your campaign API key (bidding or management key)
• date (optional): Single date in YYYY-MM-DD format, defaults to today
  • NOTE: For date ranges, make multiple API calls (one per day) and aggregate client-side
• min_revenue (optional): Minimum revenue filter in dollars (default: 0.0000001)
  • Default 0.0000001: Shows all revenue-generating sources (excludes zero-revenue)
  • Set to 0: Include sources with zero revenue (impressions but no clicks)
  • Set to 0.01: Only sources with 1¢+ revenue
  • Set to 1.00: Only sources with $1+ revenue
• limit (optional): Maximum number of sources to return (default: 10000)
  • Default 10000: Safe for most use cases
  • Set to 100: Quick preview of top performers
  • Set to 0: Unlimited (use with caution on large datasets)

Error Responses

Programmatic Domain List API

Manage domain lists programmatically using your API key. Perfect for large portfolios that need daily updates.

Authentication

Use your management API key (found in campaign settings): ?api_key=YOUR_MANAGEMENT_KEY

Endpoints

GET /api/v1/lists

List all domain lists for your campaign

GET https://app.rtbdomains.com/api/v1/lists?api_key=YOUR_KEY

Response:
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Premium Publishers",
      "modifier": 1.2,
      "list_type": "boost",
      "domain_count": 1523
    }
  ],
  "count": 1
}

POST /api/v1/lists/{id}/domains

Add domains to a list (duplicates are skipped)

POST https://app.rtbdomains.com/api/v1/lists/1/domains?api_key=YOUR_KEY
Content-Type: application/json

{
  "domains": ["example.com", "example2.com", "example3.com"]
}

Response:
{
  "success": true,
  "message": "Added 3 domain(s), skipped 0 duplicate(s)",
  "added": 3,
  "skipped": 0
}

DELETE /api/v1/lists/{id}/domains

Remove specific domains from a list

DELETE https://app.rtbdomains.com/api/v1/lists/1/domains?api_key=YOUR_KEY
Content-Type: application/json

{
  "domains": ["example.com", "example2.com"]
}

Response:
{
  "success": true,
  "message": "Removed 2 domain(s)",
  "removed": 2
}

PUT /api/v1/lists/{id}/domains

Replace all domains in a list (full synchronization)

PUT https://app.rtbdomains.com/api/v1/lists/1/domains?api_key=YOUR_KEY
Content-Type: application/json

{
  "domains": ["newdomain1.com", "newdomain2.com", "newdomain3.com"]
}

Response:
{
  "success": true,
  "message": "Replaced list with 3 domain(s)",
  "total": 3
}

Notes

• All domains are automatically normalized to lowercase
• Duplicate domains are automatically skipped
• KV cache is automatically regenerated after modifications
• Changes take effect immediately for new bid requests

Error Responses

Support

For access to the control panel and additional features, please log in at: /login