Header Bidding — Prebid Server (`/openrtb2/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.

Standard Prebid Server v2 endpoint. Speaks OpenRTB 2.5 with the Prebid ext.prebid extensions. Wire-compatible with Prebid.js's built-in prebidServerBidAdapter — zero custom adapter code needed.

Endpoint#

POST https://{ad_domain}/openrtb2/auction with Content-Type: application/json. The SSP campaign token is read from one of (in order): Authorization: Bearer <token> header, ext.prebid.storedrequest.id, or site.publisher.id (the standard Prebid Server accountId location — set via the s2sConfig accountId field in Prebid.js).

URL

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

Bid Request#

Standard OpenRTB 2.5 with Prebid extensions. We support imp.banner, imp.video, and imp.native. Pop / push imps require the same ext.type marker as the standalone OpenRTB topics. ext.prebid.targeting on the request enables hb_pb / hb_size / hb_adid keys in the response.

Banner request

{
  "id": "auction-uuid",
  "tmax": 500,
  "imp": [{
    "id": "imp-1",
    "tagid": "div-gpt-leaderboard",
    "banner": {
      "format": [{ "w": 728, "h": 90 }, { "w": 970, "h": 90 }],
      "topframe": 1
    },
    "ext": { "prebid": { "bidder": { "goadserver": { "subid": "homepage" } } } }
  }],
  "site": {
    "domain": "site.com",
    "page": "https://site.com/page.html",
    "publisher": { "id": "{token}" }
  },
  "device": {
    "ua": "{user_agent}",
    "ip": "{client_ip}",
    "language": "{language}",
    "geo": { "country": "NLD" }
  },
  "user": { "id": "5a80e2e5857d86a298e013ab0091c17e" },
  "regs": { "ext": { "gdpr": 1 } },
  "ext": {
    "prebid": {
      "targeting": { "pricegranularity": "high" },
      "cache":     { "bids": {} }
    }
  }
}

Multi-format

{
  "id": "auction-uuid",
  "tmax": 500,
  "imp": [
    {
      "id": "imp-1",
      "tagid": "div-gpt-top",
      "banner": { "format": [{ "w": 970, "h": 250 }] }
    },
    {
      "id": "imp-2",
      "tagid": "div-gpt-preroll",
      "video": { "mimes": ["video/mp4"], "w": 640, "h": 360 }
    },
    {
      "id": "imp-3",
      "tagid": "div-gpt-native",
      "native": {
        "request": "{\"native\":{\"plcmttype\":1,\"plcmtcnt\":1,\"assets\":[{\"id\":1,\"required\":1,\"title\":{\"len\":140}},{\"id\":2,\"required\":0,\"img\":{\"type\":3,\"wmin\":300,\"hmin\":250}}]}}",
        "ver": "1.2"
      }
    }
  ],
  "site": {
    "domain": "site.com",
    "page": "https://site.com/page.html",
    "publisher": { "id": "{token}" }
  },
  "device": {
    "ua": "{user_agent}",
    "ip": "{client_ip}",
    "language": "{language}",
    "geo": { "country": "NLD" }
  },
  "user": { "id": "5a80e2e5857d86a298e013ab0091c17e" },
  "ext": { "prebid": { "targeting": {}, "cache": { "bids": {} } } }
}

Bid Response#

Standard OpenRTB 2.5 BidResponse with ext.prebid.targeting populated so Prebid.js sees the targeting keys out of the box. nbr (no bid reason) is set when no bidders responded — code 2 means invalid request, 3 means known error.

Successful auction

{
  "id": "auction-uuid",
  "cur": "USD",
  "seatbid": [{
    "seat": "goadserver",
    "bid": [{
      "id": "our-bid-id",
      "impid": "imp-1",
      "price": 1.42,
      "adm": "<a href=\"https://site.com\"><img src=\"https://cdn.example.com/970x250.png\" width=\"970\" height=\"250\"></a>",
      "adomain": ["advertiser.com"],
      "crid": "creative-1",
      "w": 970,
      "h": 250,
      "ext": {
        "prebid": {
          "type": "banner",
          "targeting": {
            "hb_pb":      "1.40",
            "hb_size":    "970x250",
            "hb_adid":    "our-bid-id",
            "hb_bidder":  "goadserver",
            "hb_cache_id": "abc-123"
          }
        }
      }
    }]
  }]
}

No-bid (nbr)

{
  "id": "auction-uuid",
  "nbr": 2,
  "seatbid": []
}

Prebid.js setup#

Drop-in s2sConfig for Prebid.js — replace {ad_domain} and {token} with your tenant's ad host and SSP campaign token. The bidder code matches the network name (configurable per tenant; defaults to goadserver).

Prebid.js s2sConfig

{
  "s2sConfig": {
    "accountId":  "{token}",
    "bidders":    ["goadserver"],
    "endpoint":   "https://{ad_domain}/openrtb2/auction",
    "syncEndpoint": "https://{ad_domain}/openrtb2/sync",
    "timeout":    500,
    "defaultVendor": null
  },
  "consentManagement": { "gdpr": { "cmpApi": "iab", "timeout": 8000 } }
}