Header Bidding — `/hb/auction`

Hosts: {rtb_domain} is your network's RTB domain, used by the bidder endpoints; a network without a dedicated RTB domain uses its ad domain there. {ad_domain} is the network's ad-serving domain. Inside the panel both are filled in for you.

Lightweight custom auction. Best for publishers who don't already run Prebid.js. One request per page with a slots array.

Endpoint#

POST https://{ad_domain}/hb/auction with Content-Type: application/json. token is the SSP campaign token (required). slots[] is an array of placement slots — each slot becomes an independent auction whose winner appears in the response bids[] keyed by slot_id.

URL

POST https://{ad_domain}/hb/auction

Auction Request#

slot_id is the publisher-stable slot identifier — each unique value gets auto-provisioned as an adzone on the relevant site / adtype / size. ad_type is one of banner, video, native, pop, push. subid overrides the campaign default for stats attribution on this slot only.

Single banner slot

{
  "token": "{token}",
  "page": "https://site.com/page.html",
  "ref": "https://google.com/",
  "slots": [{
    "slot_id": "div-gpt-leaderboard",
    "ad_type": "banner",
    "w": 728,
    "h": 90,
    "floor": 0.10,
    "subid": "homepage"
  }]
}

Multiple slots

{
  "token": "{token}",
  "page": "https://site.com/page.html",
  "ref": "https://google.com/",
  "slots": [
    { "slot_id": "div-gpt-top",     "ad_type": "banner", "w": 970, "h": 250, "floor": 0.50 },
    { "slot_id": "div-gpt-side",    "ad_type": "banner", "w": 300, "h": 600, "floor": 0.20 },
    { "slot_id": "div-gpt-preroll", "ad_type": "video",  "w": 640, "h": 360, "floor": 0.30 },
    { "slot_id": "div-gpt-native",  "ad_type": "native", "floor": 0.15 }
  ]
}

Auction Response#

One bid per slot that received a winning bid; slots with no bid are omitted. adm carries the rendered creative markup (HTML for banners, VAST XML for video, OpenRTB Native object stringified for native). nurl is the win-notice URL — fire it once the creative is rendered.

Banner response

{
  "bids": [{
    "slot_id": "div-gpt-leaderboard",
    "price": 1.42,
    "ad_type": "banner",
    "w": 728,
    "h": 90,
    "adm": "<a href=\"https://site.com\" target=\"_blank\"><img src=\"https://cdn.example.com/728x90.png\" width=\"728\" height=\"90\" border=\"0\"></a>",
    "hash": "ab12cd34",
    "nurl": "https://{ad_domain}/win?h=ab12cd34&p=${AUCTION_PRICE}",
    "adomain": ["advertiser.com"]
  }],
  "cur": "USD",
  "elapsed_ms": 87.3
}

Video response

{
  "bids": [{
    "slot_id": "div-gpt-preroll",
    "price": 3.20,
    "ad_type": "video",
    "w": 640,
    "h": 360,
    "adm": "<VAST version=\"3.0\"><Ad id=\"1\"><Wrapper><AdSystem>NetworkName</AdSystem><VASTAdTagURI><![CDATA[https://vast.example.com/tag.xml]]></VASTAdTagURI><Impression><![CDATA[https://impression.example.com/log]]></Impression></Wrapper></Ad></VAST>",
    "hash": "ef56gh78",
    "nurl": "https://{ad_domain}/win?h=ef56gh78&p=${AUCTION_PRICE}",
    "adomain": ["advertiser.com"]
  }],
  "cur": "USD",
  "elapsed_ms": 124.5
}

Native response

{
  "bids": [{
    "slot_id": "div-gpt-native",
    "price": 0.75,
    "ad_type": "native",
    "adm": "{\"native\":{\"link\":{\"url\":\"https://site.com\"},\"eventtrackers\":[{\"event\":1,\"method\":1,\"url\":\"https://mysite.com/tracker\"}],\"assets\":[{\"id\":1,\"title\":{\"text\":\"Title\"}},{\"id\":2,\"img\":{\"url\":\"https://mysite.com/image.png\",\"w\":300,\"h\":250}},{\"id\":3,\"data\":{\"value\":\"Description\"}}]}}",
    "hash": "ij90kl12",
    "nurl": "https://{ad_domain}/win?h=ij90kl12&p=${AUCTION_PRICE}",
    "adomain": ["advertiser.com"]
  }],
  "cur": "USD",
  "elapsed_ms": 102.1
}

No-bid response

{
  "bids": [],
  "cur": "USD",
  "elapsed_ms": 95.2
}