CleanTap Bid API Documentation

Built in full respect of the OpenRTB 2.6 IAB Specification.

Introduction

CleanTap provides two environments for the bidding API:

  • Development: https://api-dev.cleantap.media
  • Production: https://api.cleantap.media

Bid Request Endpoint

The endpoint supports POST requests with JSON bodies. The path is /bid/v1/request.

Development endpoint:

https://api-dev.cleantap.media/bid/v1/request

Production endpoint:

https://api.cleantap.media/bid/v1/request

Required Headers

  • X-API-Key: Obtained from CleanTap dashboard or manager.
  • x-openrtb-version: 2.6
  • Content-Type: application/json

Optional: You can include a zone_id parameter in your request (often as a query param) for organizational grouping. Defaults to "1".

Filtering & No-Bid Reasons

CleanTap automatically filters each bid request, checking for data center traffic, invalid locations, non-CTV devices, etc. If a request is filtered out (e.g., isp_issue), CleanTap returns a no-bid response with seatbid: [], an nbr code, and a human-readable reason inext.details.

For instance, reason isp_issue might appear with nbr: 5 indicating suspected non-human traffic.

Sample Bid Request 1

A fully-featured CTV request example (OpenRTB 2.6):

{
  "id": "6869fc03936050a002b491bd2edcbe28",
  "device": {
    "ip": "69.67.139.2",
    "ua": "Roku/DVP-14.0 (14.0.4.12230-H2)",
    "dnt": 0,
    "lmt": 0,
    "ifa": "f598d590-6315-4844-aaf3-d15d3ac927dc",
    "make": "Roku",
    "model": "DVP-14.0",
    "devicetype": 3,
    "geo": {
      "city": "Frisco",
      "country": "USA",
      "region": "CO",
      "metro": "751",
      "lat": 39.5589,
      "lon": -106.1381,
      "accuracy": 1000,
      "zip": "80443"
    },
    "carrier": "IC2NET"
  },
  "tmax": 500,
  "at": 1,
  "cur": ["USD"],
  "app": {
    "id": "333d730b64298ca9a82170a732c44d13",
    "name": "WWBT 12 News",
    "bundle": "120430",
    "cat": ["IAB1-5", "IAB1", "IAB19-11", "IAB19", "IAB23-5", "IAB23"],
    "publisher": { "id": "808" }
  },
  "imp": [
    {
      "id": "eae93d634f804afc6216771ff03a7ecd",
      "bidfloor": 1.1364355122842666,
      "bidfloorcur": "USD",
      "secure": 1,
      "video": {
        "w": 1920,
        "h": 1080,
        "linearity": 1,
        "pos": 0,
        "mimes": ["video/mp4", "video/ogg", "video/webm", "application/javascript"],
        "protocols": [2, 3, 5, 6, 7, 8],
        "skip": 0,
        "skipmin": 0,
        "playbackmethod": [1],
        "minduration": 3,
        "maxduration": 300,
        "startdelay": 0
      },
      "ext": { "wopv": "7cec757d-47ab-4817-bc36-08702662178b" }
    }
  ],
  "user": { "ext": { "consent": "" } },
  "ayUserId": "2bb3e8a348ea1185c7a5bfb3566c5ea5",
  "ayRequestId": "296cd898-5ed3-485e-bfae-8315138cc130",
  "regs": { "coppa": 0, "ext": { "gdpr": 0 } },
  "source": {
    "ext": {
      "schain": { "ver": "1.0", "complete": 1, "nodes": [] }
    },
    "pchain": "6c5b49d96ec1b458:808"
  },
  "bcat": [],
  "ext": {
    "schain": { "ver": "1.0", "complete": 1, "nodes": [] }
  },
  "wseat": []
}

Sample Bid Response 1

A successful bid with VAST Wrappers, nurl for win notice, and burl for billing notice:

{
  "id": "6869fc03936050a002b491bd2edcbe28",
  "cur": "USD",
  "bidid": "5348b2f1-cf43-4476-b9bc-733c8d18f255",
  "seatbid": [
    {
      "bid": [
        {
          "id": "5348b2f1-cf43-4476-b9bc-733c8d18f255",
          "adm": "<VAST version=\"2.0\">...VAST XML BLOCK...</VAST>",
          "cat": ["IAB24"],
          "cid": "0-1458353",
          "adid": "7370464",
          "crid": "29348590",
          "iurl": "http://cdn.xad.com/content/openrtb/templates/1920x1080-29348590.png",
          "nurl": "https://api-dev.cleantap.media/bid/v1/notify?...t=winbid&price=${AUCTION_PRICE}...",
          "impid": "eae93d634f804afc6216771ff03a7ecd",
          "price": 1.1464355122842667,
          "crtype": "video",
          "adomain": ["ghirardelli.com"],
          "burl": "https://api-dev.cleantap.media/bid/v1/notify?...t=billbid&price=${AUCTION_PRICE}..."
        }
      ]
    }
  ]
}

Sample Bid Request 2

{
  "id": "b03b5c112a2373f7771b001003bd65bf",
  "device": {
    "ip": "24.229.230.135",
    "ua": "JaybirdTV/2.14.2 (Linux; Android 11) ExoPlayerLib/2.14.2",
    "dnt": 0,
    "lmt": 0,
    "ifa": "ca046dda-48d2-59e2-855c-c9d4f8a56c50",
    "os": "Android",
    "osv": "11",
    "make": "Generic",
    "model": "Android 11.0",
    "devicetype": 3,
    "geo": {
      "city": "Kernsville",
      "country": "USA",
      "region": "PA",
      "metro": "504",
      "lat": 40.6276,
      "lon": -75.6011,
      "accuracy": 10,
      "zip": "18069"
    },
    "carrier": "PenTeleData",
    "ext": { "ifa_type": "dpid" }
  },
  "tmax": 700,
  "at": 1,
  "cur": ["USD"],
  "app": {
    "id": "6db846451ae91d788328e93aa3fc9868",
    "name": "WFMZ+ Streaming",
    "bundle": "com.wfmz.plus",
    "storeurl": "https://play.google.com/store/apps/details?id=com.wfmz.plus",
    "cat": ["IAB12"],
    "publisher": { "id": "796" },
    "ext": { "inventorypartnerdomain": "zeam.com" }
  },
  "imp": [
    {
      "id": "081f45f744bf412c02fcc8c80241a5bd",
      "bidfloor": 10,
      "bidfloorcur": "USD",
      "secure": 1,
      "video": {
        "w": 1280,
        "h": 720,
        "linearity": 1,
        "pos": 7,
        "mimes": [
          "video/mp4",
          "video/ogg",
          "video/webm",
          "application/javascript",
          "video/x-flv",
          "application/x-shockwave-flash",
          "audio/mp4",
          "audio/mpeg",
          "audio/mp3",
          "audio/wav",
          "audio/aac"
        ],
        "protocols": [2, 3, 5, 6, 7, 8],
        "skip": 0,
        "skipmin": 0,
        "minduration": 3,
        "maxduration": 300,
        "startdelay": 0
      },
      "ext": { "wopv": "207cf817-33a7-4389-941c-af0a8b2c0046" }
    }
  ],
  "user": { "ext": { "consent": "" } },
  "ayUserId": "0c3c6789f7f836e9c44be5f02c337f4c",
  "ayRequestId": "b2b1fc5d-0824-40ca-8e14-bbde2c514e75",
  "regs": { "coppa": 0, "ext": { "gdpr": 0 } },
  "source": { "ext": {}, "pchain": "6c5b49d96ec1b458:796" },
  "bcat": [],
  "ext": {
    "schain": { "ver": "1.0", "complete": 1, "nodes": [] }
  },
  "wseat": []
}

Sample Bid Response 2

A "no-bid" response example, with nbr=5 and ext.details = "isp_issue":

{
  "id": "b03b5c112a2373f7771b001003bd65bf",
  "seatbid": [],
  "nbr": 5,
  "ext": { "details": "isp_issue" }
}

Example cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -H "x-openrtb-version: 2.6" \
  -H "X-API-Key: <YOUR_SELLER_API_KEY>" \
  "https://api.cleantap.media/bid/v1/request?zone_id=1" \
  -d '{
    "id": "ExampleBidRequest",
    "device": {
      "ip": "8.8.8.8",
      "devicetype": 3,
      "geo": {
        "country": "USA",
        "region": "CA"
      }
    },
    "imp": [...],
    "app": {...},
    "tmax": 500
  }'

Error & No-Bid Handling

  • 401 Unauthorized: if X-API-Key is missing or invalid
  • 400 Bad Request: if the JSON body is invalid
  • 409 Conflict: if a request ID was already processed
  • For other no-bid reasons, you'll see seatbid: [], a numeric nbr and an ext.details cause (e.g. isp_issue).

Last Updated: Feb 4, 2025