Bid Responses

The OpenRTB bid response fields CloudX reads, creative markup rules, and win/loss notification URLs with macros.

Return a standard OpenRTB bid response to bid on an impression. This page covers the fields CloudX reads, the markup rules for CloudX-rendered creatives, and the notification URLs you use to track outcomes.

No-bid responses

To pass on an impression, return HTTP 204 with an empty body, or HTTP 200 with an empty seatbid array. Use the 200 form when you want to report a reason in nbr (OpenRTB List 5.24) — a 204 cannot carry a body.

Response object

Bid object

Creative markup rules

• Return the full markup in adm. CloudX does not fetch markup from nurl.
• Use HTTPS URLs everywhere. HTTP references violate the partner contract and may be rejected.
• HTML/MRAID markup is a snippet the CloudX SDK renders in a WebView. VAST markup is the complete XML document. See the Creative Specification for formats, sizes, and rendering behavior.

Win and loss notifications

CloudX calls the notification URLs on your bid as the auction and on-device outcomes become known:

Notification delivery is asynchronous and best-effort, not exactly once. Notices may be delayed, retried, duplicated, delivered out of order, or dropped. Make handlers idempotent: deduplicate by URL type plus ${AUCTION_ID}, ${AUCTION_IMP_ID}, and ${AUCTION_BID_ID}, and return 2xx only after durably recording the event.

Macros

Embed macros in notification URLs and CloudX substitutes values before calling them. Macros are case-sensitive; always use the ${...} form.

A macro stays literal when that notification path does not supply its context, such as ${AUCTION_LOSS} in an nurl. When the path does supply context, an empty optional source field can instead yield an empty replacement. Build handlers that tolerate both literal macros and empty values.

Price macro behavior

Loss reason codes

${AUCTION_LOSS} carries one of these OpenRTB codes:

Late responses are discarded. Do not rely on the lurl in a late response receiving code 2; server-generated timeout notices are available only through endpoint adapters that implement them.

Example response

{
  "id": "7f3d9a1c2e4b48f0a6d5c8b2e1f40937",
  "cur": "USD",
  "bidid": "b-92f4ac",
  "seatbid": [
    {
      "seat": "your-seat-id",
      "bid": [
        {
          "id": "bid-0001",
          "impid": "1",
          "price": 6.25,
          "crid": "creative-48291",
          "adid": "ad-48291",
          "adomain": ["advertiser.example"],
          "cat": ["IAB1-1"],
          "adm": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><VAST version=\"3.0\">...</VAST>",
          "nurl": "https://events.bidder.example/win?price=${AUCTION_PRICE}",
          "burl": "https://events.bidder.example/bill?price=${AUCTION_PRICE}",
          "lurl": "https://events.bidder.example/loss?reason=${AUCTION_LOSS}&price=${AUCTION_PRICE}",
          "ext": { "crtype": "vast" }
        }
      ]
    }
  ]
}