/developers / ad-tech

AdTech API Documentation

Integrate cloud-scale advertising infrastructure with our RESTful APIs. Real-time bidding, audience synchronization, and conversion tracking built for high-throughput DSP/SSP integrations.

Beta Notice
\n

The AdTech API v2 is currently in public beta. Endpoints are stable but subject to minor backward-compatible changes. Subscribe to our changelog for updates.

Authentication

All API requests require authentication using Bearer tokens combined with HMAC-SHA256 signatures for payload integrity. Generate your API key from the CloudNexus Dashboard.

cURL
Python
JavaScript
curl -X POST https://api.cloudnexus.com/v2/rtb/bid \
  -H "Authorization: Bearer $CN_API_KEY" \
  -H "CN-Timestamp: $(date +%s)" \
  -H "CN-Signature: hmac-sha256=..." \
  -H "Content-Type: application/json" \
  -d '{"imp":[{"id":"1","banner":{"w":300,"h":250}}],"bidfloor":0.05}'
import requests, hmac, hashlib, time

auth = {
    "Authorization": f"Bearer {CN_API_KEY}",
    "CN-Timestamp": str(int(time.time())),
    "CN-Signature": "hmac-sha256=" + signature(payload),
    "Content-Type": "application/json"
}

resp = requests.post("https://api.cloudnexus.com/v2/rtb/bid", headers=auth, json=payload)
const response = await fetch('https://api.cloudnexus.com/v2/rtb/bid', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${CN_API_KEY}`,
    'CN-Timestamp': Date.now(),
    'CN-Signature': `hmac-sha256=${sign(payload)}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

Real-Time Bidding (RTB)

Submit bids for ad impressions in real-time. The endpoint accepts OpenRTB 2.6 compliant payloads and responds within 100ms.

Method Endpoint Description
POST /v2/rtb/bid Submit a bid request for a single or batch impression
GET /v2/rtb/win/{bid_id} Retrieve bid winner notification & impression tracking pixel
POST /v2/rtb/bid/cancel Cancel an outstanding bid before auction close
Latency Requirements

Your infrastructure must respond within 100ms for bid requests. Requests exceeding this threshold will be automatically dropped and flagged in your account dashboard.

Audience Synchronization

Upload and sync first-party audience segments using hashed email or device IDs. Supports secure email hashing and GDPR-compliant consent signals.

cURL
JSON Payload
curl -X POST https://api.cloudnexus.com/v2/audiences/sync \
  -H "Authorization: Bearer $CN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "segment_id": "high_value_shoppers",
    "match_type": "secure_hash",
    "entries": [
      {"email": "sha256_hash_1", "consent": true},
      {"email": "sha256_hash_2", "consent": true}
    ]
  }'
{
  "segment_id": "string (required)",
  "match_type": "secure_hash | device_id | idfa | gidfa",
  "entries": [
    {
      "email": "sha256_hashed_email",
      "consent": boolean,
      "ttl_seconds": integer
    }
  ],
  "deduplicate": boolean // defaults to true
}

Conversion Tracking

Record post-click conversions and attribute them to specific ad placements. Supports micro-conversions, macro-conversions, and custom revenue values.

Parameter Type Required Description
conversion_id string Yes Unique identifier for the conversion event
placement_id string Yes Associated ad placement or campaign ID
value float No Monetary value for ROAS calculations
event_type string No purchase, signup, lead, view

Rate Limits & Quotas

AdTech endpoints are optimized for high-throughput. Limits are applied per API key and evaluated at the edge. Exceeding limits returns 429 Too Many Requests with retry-after headers.

10k
Bids/sec (Shared)
50k
Bids/sec (Dedicated)
1k
API Calls/sec

Rate limit headers are included in every response:

Webhooks

Receive real-time notifications for bid wins, impression deliveries, and settlement reports. Configure endpoints in your dashboard.

Signature Verification

Always verify webhook payloads using the X-CN-Signature header. CloudNexus uses HMAC-SHA256 with your webhook secret. Failures return 401 Unauthorized after 3 retries.

Event Payload Description
bid.win win_notification_v2 Impression won, includes tracking pixel & creative URL
impression.delivered delivery_report Ad successfully rendered on user device
settlement.monthly financial_report Monthly billing & revenue breakdown

Official SDKs & Tools

Accelerate integration with our officially maintained SDKs. All packages support async operations, retry logic, and automatic signature generation.

← Authentication Webhooks →