Auctera API Documentation. Build on the ultimate engine.

Campaign Management

Create, read, update, and manage your DSP and Affiliate campaigns.

List Active Campaigns

Retrieves a paginated list of all active campaigns associated with your advertiser account.

This endpoint returns core metrics such as current daily spend, lifetime spend, target CPA, ROAS, and overall status. Results can be filtered using query parameters like `?status=active`, `?type=dsp_retargeting`, or `?date_range=last_7_days`. The pagination cursor ensures efficient fetching for enterprise accounts with thousands of campaigns.

curl -X GET "https://api.auctera.io/v2/campaigns?status=active" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": [
    {
      "id": "cmp_89f2a",
      "name": "Q4 Retargeting - US",
      "status": "active",
      "budget": { "daily": 5000, "currency": "USD" },
      "performance": {
        "spend_today": 1240.50,
        "conversions_today": 45,
        "current_cpa": 27.56
      }
    }
  ],
  "pagination": { "next_cursor": "cXc..." }
}

Get Campaign Details

Retrieve full configuration details, current bid multipliers, and targeting settings.

Unlike the list endpoint, this call provides deep nested data. It returns the exact geographic targeting boundaries (including zip codes and DMAs), device-type bidding multipliers, pacing settings (e.g., ASAP vs. Even), and the selected algorithmic bidding strategy (e.g., Maximize Conversions vs. Target CPA).

curl -X GET "https://api.auctera.io/v2/campaigns/cmp_89f2a" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "id": "cmp_89f2a",
  "name": "Q4 Retargeting - US",
  "targeting": {
    "geo": ["US", "CA"],
    "device_types": ["mobile", "tablet"]
  },
  "bidding": {
    "strategy": "target_cpa",
    "target_amount": 35.00
  }
}

Create Campaign

Programmatically create a new programmatic or affiliate campaign.

Ideal for bulk-uploading campaigns via internal tools. You must specify the `type` (e.g., 'dsp_prospecting', 'affiliate_cpa'), the total budget, and initial targeting vectors. The campaign will enter a `pending_review` state until the creative assets are verified by our automated compliance scanners.

curl -X POST "https://api.auctera.io/v2/campaigns" \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Holiday Promo", "budget": 10000, "type": "dsp_retargeting"}'

{
  "success": true,
  "campaign_id": "cmp_9b8x2",
  "status": "pending_review"
}

Update Campaign Budget

Adjust the daily budget, target CPA, or status (pause/resume) of a live campaign.

Use this endpoint to build automated rules in your internal BI tools. For example, if a campaign's ROAS exceeds a certain threshold in your Looker dashboard, you can trigger an API call to automatically increase the `daily_budget` by 20%.

curl -X PATCH "https://api.auctera.io/v2/campaigns/cmp_89f2a" \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"budget": {"daily": 7500}, "status": "active"}'

{
  "success": true,
  "campaign_id": "cmp_89f2a",
  "updated_fields": ["budget", "status"]
}

Archive Campaign

Permanently archive a campaign. This halts all spending immediately.

Archived campaigns cannot be restarted. All historical reporting data is preserved. Any in-flight bids are immediately canceled, and publisher tracking links are deactivated within 500 milliseconds globally.

curl -X DELETE "https://api.auctera.io/v2/campaigns/cmp_89f2a" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "campaign_id": "cmp_89f2a",
  "status": "archived"
}

Conversions & Attribution

Manage server-side tracking, multi-touch attribution, and postbacks.

Server-to-Server (S2S) Postback

Securely report a conversion event from your backend directly to Auctera.

Bypasses the browser entirely, preventing cookie-loss and ad-blocker interference. Requires a cryptographic signature (HMAC-SHA256) of the payload using your API secret to prevent postback fraud. Used extensively for mobile app install (CPI) campaigns and strict financial compliance.

curl -X POST "https://api.auctera.io/v2/conversions" \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"click_id": "auc_982hfj28", "event_type": "purchase", "revenue": 149.99, "currency": "USD"}'

{
  "success": true,
  "transaction_id": "txn_p92jd",
  "fraud_score": 0.01
}

Multi-Touch Attribution Report

Retrieve a detailed journey analysis for a specific conversion.

Returns every single ad impression, click, and interaction the user had across DSP, Retargeting, and Affiliate channels prior to converting. It displays the fractional credit assigned to each touchpoint based on your selected MTA model (e.g., linear, time-decay, data-driven ML).

curl -X GET "https://api.auctera.io/v2/reports/mta?conversion_id=txn_p92jd" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "conversion_id": "txn_p92jd",
  "touchpoints": [
    {"channel": "DSP", "interaction": "impression", "credit": 0.20},
    {"channel": "Affiliate", "interaction": "click", "credit": 0.80}
  ]
}

Reverse Conversion

Invalidate a previously fired conversion due to a refund or chargeback.

Crucial for e-commerce and SaaS brands to maintain accurate CPA/ROAS data. When a user refunds a purchase, firing this endpoint will deduct the payout from the affiliate and recalculate the campaign's true ROI. Must be called within 30 days of the original transaction.

curl -X POST "https://api.auctera.io/v2/conversions/reversal" \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"transaction_id": "txn_p92jd", "reason": "chargeback"}'

{
  "success": true,
  "status": "reversed",
  "payout_deducted": 45.00
}

Upload Offline Conversions

Batch upload in-store purchases or CRM-tracked lead conversions.

For omnichannel brands. Upload a CSV or JSON array containing hashed email addresses and transaction values. Auctera will attempt to match these offline events back to earlier digital ad impressions to prove true omnichannel ROAS.

curl -X POST "https://api.auctera.io/v2/conversions/offline" \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"events": [{"hashed_email": "e2a...", "value": 50}, {"hashed_email": "f9b...", "value": 120}]}'

{
  "success": true,
  "matched_events": 1,
  "unmatched_events": 1
}

Conversion Fraud Analysis

View detailed algorithmic reasoning for rejected or flagged conversions.

If a conversion is blocked by Auctera's Pre-Bid or Post-Click fraud filters, this endpoint returns the exact telemetry that triggered the block (e.g., 'Velocity Mismatch', 'Known VPN IP', 'Scripted Touch Cadence'). Provides full transparency into IVT.

curl -X GET "https://api.auctera.io/v2/conversions/fraud-log?transaction_id=txn_flagged1" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "transaction_id": "txn_flagged1",
  "status": "rejected",
  "reason": "device_fingerprint_anomaly",
  "confidence_score": 0.99
}

Audiences & Targeting

Programmatically manage custom segments, lookalikes, and data syncs.

Sync First-Party Audience

Upload or update a deterministic list of identifiers.

Pass an array of SHA-256 hashed emails, Mobile Advertising IDs (MAIDs), or phone numbers. Supports operations like 'add', 'remove', or 'replace'. Processing happens asynchronously; the endpoint returns a job ID to poll for completion.

curl -X POST "https://api.auctera.io/v2/audiences/sync" \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"audience_id": "aud_77b3x", "action": "add", "identifiers": [{"type": "email_sha256", "value": "a1b2..."}]}'

{
  "success": true,
  "records_processed": 10000,
  "estimated_match_rate": 0.85
}

List Audiences

Retrieve all custom audiences, lookalike segments, and retargeting pools.

Returns a summary of all targetable segments, including real-time estimated size, match rates across the Auctera identity graph, and the creation source (e.g., 'CRM Sync', 'Pixel Event', 'Lookalike ML').

curl -X GET "https://api.auctera.io/v2/audiences" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": [
    {"id": "aud_77b3x", "name": "Cart Abandoners (7d)", "size_estimate": 450000}
  ]
}

Generate Lookalike Audience

Trigger the ML engine to build a predictive lookalike model.

Provide a high-performing seed audience (e.g., 'Top 10% LTV Customers'). The algorithm will evaluate thousands of behavioral and contextual vectors across the Auctera network to find similar users. You can define the strictness via the `similarity_percentage` parameter (e.g., 1% vs 5%).

curl -X POST "https://api.auctera.io/v2/audiences/lookalike" \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"seed_audience_id": "aud_77b3x", "similarity_percentage": 1.5, "geo": ["US"]}'

{
  "success": true,
  "lookalike_audience_id": "aud_lal_99x",
  "status": "building"
}

Delete Custom Audience

Permanently delete an uploaded audience segment.

For GDPR/CCPA compliance, deleting an audience instantly purges the matched identity graph linkages from Auctera's servers. Active campaigns relying on this audience will automatically pause to prevent targeting errors.

curl -X DELETE "https://api.auctera.io/v2/audiences/aud_77b3x" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "status": "deleted"
}

Audience Overlap Analysis

Calculate the exact user overlap between two or more audience segments.

Extremely useful for campaign planning. Discover if your 'Past Purchasers' segment heavily overlaps with your newly generated 'Lookalike' segment to prevent bidding against yourself and ensure you are actually reaching net-new users.

curl -X GET "https://api.auctera.io/v2/audiences/overlap?ids=aud_1,aud_2" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "overlap_percentage": 14.2,
  "estimated_unique_users": 1250000
}

Reporting & Analytics

Extract granular, log-level performance data for your BI tools.

Daily Performance Aggregation

Pull high-level daily aggregates for spend, impressions, clicks, conversions.

The most commonly used endpoint for populating internal executive dashboards (Tableau, Looker). Data is strictly verified and finalized 24 hours post-event to account for delayed conversions and fraud clawbacks.

curl -X GET "https://api.auctera.io/v2/reports/daily?start_date=2026-10-01&end_date=2026-10-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": [
    {"date": "2026-10-01", "spend": 4500.00, "roas": 3.4, "ivt_blocked": 1240}
  ]
}

Publisher Placement Report

Log-level transparency report showing exact domain and app performance.

We believe in zero black-box optimization. This endpoint allows you to see exactly which SSPs, specific domains (e.g., nytimes.com), mobile app bundles, or affiliate partners drove the conversions, including the exact clearing price paid to the publisher.

curl -X GET "https://api.auctera.io/v2/reports/publishers?campaign_id=cmp_89f2a" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": [
    {"domain": "forbes.com", "impressions": 50000, "spend": 250.00, "conversions": 12},
    {"affiliate_id": "pub_8821", "clicks": 450, "payout": 1200.00, "conversions": 24}
  ]
}

Creative A/B Test Report

Analyze the performance of specific DCO variants and assets.

Allows your creative teams to programmatically pull performance data to see which specific headline, image, or CTA button generated the highest Click-Through Rate (CTR) and Conversion Rate (CVR).

curl -X GET "https://api.auctera.io/v2/reports/creatives?campaign_id=cmp_89f2a" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": [
    {"creative_id": "crt_11a", "variant": "blue_cta", "ctr": 0.85, "cvr": 2.1},
    {"creative_id": "crt_11b", "variant": "red_cta", "ctr": 0.92, "cvr": 1.8}
  ]
}

Trigger Async Report Export

Generate massive log-level data dumps in CSV or Parquet format.

For reports containing millions of rows, synchronous API calls will timeout. Use this endpoint to trigger an asynchronous job. Auctera will generate a secure AWS S3 pre-signed URL containing the zipped CSV or Parquet file once the job completes.

curl -X POST "https://api.auctera.io/v2/reports/export" \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"type": "log_level_impressions", "date": "2026-10-01", "format": "parquet"}'

{
  "job_id": "exp_998xl2",
  "status": "processing",
  "estimated_time_seconds": 120
}

Poll Export Status

Check the status of an asynchronous report export and retrieve the download link.

Poll this endpoint every 30 seconds. Once the `status` changes to `completed`, the response will include a short-lived `download_url` valid for 15 minutes.

curl -X GET "https://api.auctera.io/v2/reports/export/exp_998xl2" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "job_id": "exp_998xl2",
  "status": "completed",
  "download_url": "https://s3.amazonaws.com/auctera-exports/..."
}

Creative & Asset Management

Upload and manage display banners, videos, and dynamic creatives.

Upload Display Asset

Upload images, HTML5 bundles, or video files to the Auctera CDN.

Supports JPG, PNG, GIF, MP4, and zipped HTML5 workspaces. Assets are immediately uploaded to our edge CDN and assigned a unique `asset_id`. The payload must be sent as `multipart/form-data`.

curl -X POST "https://api.auctera.io/v2/creatives/upload" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@banner_300x250.jpg" -F "type=image"

{
  "success": true,
  "asset_id": "ast_9921",
  "cdn_url": "https://cdn.auctera.io/ast_9921.jpg"
}

Check Creative Audit Status

Check if an uploaded creative has passed automated ad exchange audits.

All major exchanges (Google AdX, Magnite) require creatives to be audited for malware, brand safety, and excessive CPU usage before they can bid. This endpoint tells you if your asset is 'approved' or 'rejected' by the global exchange consortium.

curl -X GET "https://api.auctera.io/v2/creatives/audit?asset_id=ast_9921" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "asset_id": "ast_9921",
  "status": "approved",
  "malware_scan": "clean",
  "iab_category": "IAB3-1"
}

Create DCO Template

Define a Dynamic Creative Optimization structural template.

Construct a JSON template defining placeholder variables for headlines, background images, and CTA buttons. The Auctera engine will automatically generate and test all permutations of these variables during ad delivery.

curl -X POST "https://api.auctera.io/v2/creatives/dco" \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Dynamic Retargeting", "variables": ["headline", "product_image", "price"]}'

{
  "success": true,
  "dco_template_id": "dco_77a"
}

Inject Tracking Macros

Programmatically append third-party click/impression trackers.

Allows you to append DoubleClick (DCM), Sizmek, or IAS tracking tags to your uploaded creatives via API, ensuring third-party verification matches first-party data.

curl -X POST "https://api.auctera.io/v2/creatives/macros" \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"asset_id": "ast_9921", "click_tracker": "https://ad.doubleclick.net/clk/..."}'

{
  "success": true,
  "status": "macros_applied"
}

Delete Asset

Remove an asset from the CDN and all associated active campaigns.

Instantly purges the file from all edge nodes globally. If the asset is currently being used in an active campaign, the campaign will gracefully pause to prevent serving empty ad slots.

curl -X DELETE "https://api.auctera.io/v2/creatives/ast_9921" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "status": "purged"
}

Affiliate & Network Offers

For publishers and networks to pull offers and generate tracking links.

List Affiliate Offers

Retrieve a list of available CPA offers approved for your publisher ID.

Includes real-time payout amounts, allowed geographic regions, EPC (Earnings Per Click) estimates, and strict promotional rules (e.g., 'No Incentivized Traffic', 'Email Only'). Crucial for automated affiliate portals.

curl -X GET "https://api.auctera.io/v2/offers?geo=US" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": [
    {"offer_id": "off_442", "advertiser": "FintechCorp", "payout": 65.00, "epc": 1.24}
  ]
}

Generate Tracking Links

Generate dynamic, user-specific SmartLinks or standard tracking URLs.

Pass your sub-affiliate IDs (`sub_id1`, `sub_id2`) to dynamically generate tracking links. These links route through the Auctera anti-fraud gateway before redirecting to the final advertiser URL.

curl -X GET "https://api.auctera.io/v2/offers/links?offer_id=off_442&sub_id1=source_a" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "tracking_url": "https://trk.auctera.io/click?o=442&p=8821&s1=source_a",
  "impression_pixel": "https://trk.auctera.io/imp?o=442&p=8821"
}

Submit Network Application

Apply to run a private or exclusive offer.

Many high-payout enterprise offers require manual approval. Submit an application detailing your exact traffic sources, promotional methods, and expected volume.

curl -X POST "https://api.auctera.io/v2/network/applications" \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"offer_id": "off_998", "traffic_type": "SEO", "volume_estimate": 500}'

{
  "success": true,
  "application_id": "app_221x",
  "status": "pending_manual_review"
}

List Publisher Postbacks

Retrieve a list of your currently configured global server-to-server postbacks.

Allows publishers to verify their webhook endpoints. When Auctera records a conversion for your tracking link, we will fire a GET or POST request to the URLs listed here so your internal tracker (e.g., Voluum, Binom) registers the sale.

curl -X GET "https://api.auctera.io/v2/network/postbacks" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": [
    {"id": "pb_1", "event": "purchase", "url": "https://tracker.com/postback?cid={click_id}&p={payout}"}
  ]
}

Create Publisher Postback

Register a new webhook URL to receive conversion notifications.

Supports dynamic macros like `{click_id}`, `{payout}`, `{currency}`, and `{geo}`. You can configure postbacks to fire on all offers globally, or restrict them to a specific `offer_id`.

curl -X POST "https://api.auctera.io/v2/network/postbacks" \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"event": "purchase", "url": "https://tracker.com/pb?c={click_id}"}'

{
  "success": true,
  "postback_id": "pb_2",
  "status": "active"
}