Logo

Docs

OpenRTB

Specifications

  • Platform supports OpenRTB 2.5, OpenNative 1.2
  • Currency is strictly USD
  • Pricing models are CPM and CPC
  • Multiple data-centers across the globe: USA(Washington DC), Europe(Amsterdam, Frankfurt), Asia (Singapore)

Supported Ad Types

  • Banner
  • Popunder
  • Native
  • Web Push Notification
  • Video PreRoll
  • Email

Win notifications

Our platform supports win notifications
This information is used purely for statistics and have no effect on billing.
In case no NURLs found in responses from Publisher side the discrepancies in the statistics will not be considered.

Billing notifications

Our platform supports billing notifications
This information is used purely for billing statistics. You can bill by pixel, nurl, burl notifications

Response Codes

General rule about http status codes is to follow HTTP conventions and OpenRTB specification.

Code Description
200 Responses returning content, we advise not to use it for noad responses (with nbr field).
204 Empty response meaning No Content (most economical in terms of bandwidth).
400 Client error, the request is incorrect.
429 Server is facing temporary overload
500 Internal Server Error
502 Bad Gateway, check if your URL is correct
503 Service Unavailable, this is temporary state due to maintenance.

Request documentation

Bid Request

Attribute Required Description
id Yes Unique ID of the bid request, provided by the exchange.
imp Yes Array of Imp objects representing the impressions offered.
site Yes Details via a Site object about the publisher’s website.
app No Details via an App object about the publisher’s app.
device Yes Details via a Device object about the user’s device to which the impression will be delivered.
user No Details via a User object about the human user of the device; the advertising audience.
at No Auction type, where 1 = First Price, 2 = Second Price. Defaults to 2 - second price.
ext No Placeholder for exchange-specific extensions to OpenRTB.

Impression

Attribute Required Description
id yes A unique identifier for this impression within the context of the bid request.
banner only for banner imps A Banner object ; required if this impression is offered as a banner ad opportunity.
native only for native imps A Native object ; required if this impression is offered as a native ad opportunity.
instl no 1 = the ad is interstitial or full screen, 0 = not interstitial.
tagid recommended Identifier for specific ad placement or ad tag that was used to initiate the auction.
bidfloor no; default 0 Minimum bid for this impression expressed in CPM.
secure no; recommended 1 Flag to indicate if the impression requires secure HTTPS URL creative assets and markup.
ext no Placeholder for exchange-specific extensions to OpenRTB.

Impression.ext

Attribute Required Description
type no Indicates which advertisement format is used, valid values are pop and webpush.

Site

Attribute Required Description
id recommended Exchange-specific site ID.
name recommended The Site name (may be aliased at the publisher’s request).
domain recommended Domain of the site (e.g., “example.com”).
page recommended URL of the page where the impression will be shown.
ref recommended Referrer URL that caused navigation to the current page.
search no Search string that caused navigation to the current page.
mobile no Mobile-optimized signal, where 0 = no, 1 = yes.
keywords recommended Comma separated list of keywords about the site.
ext no Placeholder for exchange-specific extensions to OpenRTB.

Device

Attribute Required Description
ua yes Browser user agent string.
geo no Location of the device assumed to be the user’s current location defined by a Geo object.
dnt no Standard “Do Not Track” flag as set in the header by the browser, can be 0 or 1.
lmt no “Limit Ad Tracking” signal commercially endorsed (e.g., iOS, Android), where 0 = tracking is unrestricted, 1 = tracking must be limited per commercial guidelines.
ip yes IPv4 address closest to device.
ipv6 recommended IP address closest to device as IPv6.
devicetype no The general type of device.
os no Device operating system (e.g., “iOS” or “Android”).
osv no Device operating system version.
h recommended Physical height of the screen in pixels.
w recommended Physical width of the screen in pixels.
js no Support for JavaScript, where 0 = no, 1 = yes. always = 1
language recommended Device language. Only ISO 639-1 Alpha-2 or Alpha-3 codes.
carrier no Carrier or ISP (e.g., “VERIZON”).
ifa no The raw IDFA or Google Advertising ID, unhashed.
ext no Placeholder for exchange-specific extensions to OpenRTB.

Geo

Attribute Required Description
lat no Latitude from -90.0 to +90.0, where negative is south.
lon no Longitude from -180.0 to +180.0, where negative is west.
type no Source of location data; recommended when passing lat/lon.
country no Country code using ISO-3166-1-alpha-3.
region no Region code using ISO-3166-2; 2-letter state code if USA.
city no Always derived from IP, never a reverse geocode from Lat/Lon
zip no Always derived from IP, never a reverse geocode from Lat/Lon
utcoffset no Local time as the number +/- of minutes from UTC.
ext no Placeholder for exchange-specific extensions to OpenRTB.

App

Attribute Required Description
id no Exchange-specific app ID.
name recommended App name (may be aliased at the publisher’s request).
domain recommended Domain of the app (e.g., “mygame.foo.com”).
keywords recommended Comma separated list of keywords about the app.
ext no Placeholder for exchange-specific extensions to OpenRTB.

User

Attribute Required Description
id no Exchange-specific ID for the user. At least one of id or buyerid is recommended.
keywords recommended Comma separated list of keywords, interests, or intent.
geo no Location of the user’s home base defined by a Geo object
ext no Placeholder for exchange-specific extensions to OpenRTB.
Attribute Required Description
w no Width of the impression in pixels. This value is an exact width requirement.
h no Height of the impression in pixels. This value is an exact height requirement.
btype no Blocked banner ad types.
pos no Ad position on screen.

Native

Attribute Required Description
request yes Request payload complying with the Native Ad Specification. Note that this is a string
ver no Version of the Native Ad Specification to which request complies; highly recommended for efficient parsing.
battr no Blocked creative attributes.

Native.request

Attribute Required Description
ver yes Version of the Native Markup version in use.
layout no The Layout ID of the native ad unit. See the Table of Layout IDs below. Refer to list 7.1 of the OpenRTB Native 1.0 spec.
adunit no The Ad unit ID of the native ad unit. See Table of Layout IDs below for a list of supported core ad units.
plcmtcnt no The number of identical placements in this Layout.
assets yes An array of AssetObjects. Any bid must comply with the array of elements expressed by the Exchange. Note this is similar to what we previously called ‘admsupport’

Examples

Popunder request

{
  "id": "00799aa8590ea7ff048f9fcb10000000",
  "imp": [
    {
      "id": "00799aa8590ea7ff048f9fcb12a00000",
      "bidfloor": 0.001,
      "instl": 0,
      "tagid": "<zone_id>",
      "secure": 1,
      "ext": {
        "type": "pop"
      }
    }
  ],
  "site": {
    "id": "<site_id>",
    "domain": "example.com",
    "keywords": "Hell, Cisco, Mainstream"
  },
  "user": {
    "id": "4edbd6fa-b762-4c32-91c4-23e7fe872726"
  },
  "device": {
    "ua": "Mozilla/5.0 (Linux; Android 9; SAMSUNG SM-A105F Build/PPR1.180610.011) AppleWebKit/537.36 (KHTML, like Gecko) SamsungBrowser/9.0 Chrome/67.0.3396.87 Mobile Safari/537.36",
    "ip": "8.8.8.8",
    "language": "en"
  },
  "at": 1
}

{
  "id": "8dccfb85-03fd-4de1-a963-47373d7ec1f4",
  "imp": [
    {
      "id": "4007cff0-c6ae-4938-95c0-ee7416a17720",
      "banner": {
        "w": 300,
        "h": 250
      },
      "tagid": "<zone_id>",
      "bidfloor": 0.0205,
      "secure": 1
    }
  ],
  "site": {
    "id": "<site_id>",
    "domain": "example.com",
    "keywords": "Hell, Cisco, Mainstream"
  },
  "user": {
    "id": "4edbd6fa-b762-4c32-91c4-23e7fe872726"
  },
  "device": {
    "ua": "Mozilla/5.0 (Linux; Android 9; SM-A505FN) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/76.0.3809.132 Mobile Safari/537.36",
    "ip": "8.8.8.8",
    "language": "en"
  },
  "at": 1
}

Native request

{
  "id": "7a452540-c8c9-43ca-9d30-ab9d8bfd17a4",
  "imp": [
    {
      "id": "2d099176-9feb-44e9-85f9-f385b34123a1",
      "native": {
        "request": "{\"native\":{\"ver\":\"1.2\"\n,\"context\":1\n,\"contextsubtype\":10\n,\"plcmttype\":4\n,\"plcmtcnt\":4\n,\"assets\":[{\"id\":1,\"required\":1,\"title\":{\"len\":124}},{\"id\":2,\"data\":{\"type\":1,\"len\":50}},{\"id\":3,\"required\":1,\"img\":{\"type\":3,\"wmin\":150,\"hmin\":150}}]\n}}",
        "ver": "1.2"
      },
      "tagid": "<zone_id>",
      "bidfloor": 0.035,
      "secure": 1
    }
  ],
  "site": {
    "id": "<site_id>",
    "domain": "example.com",
    "keywords": "Hell, Cisco, Mainstream"
  },
  "user": {
    "id": "37d1951a-7184-4b7f-b227-5571a1ea7467"
  },
  "device": {
    "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 11_4_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15G77 Version/11.4.1 Safari/604.1 AlohaBrowser/2.10.0b17",
    "ip": "8.8.8.8",
    "language": "en"
  },
  "at": 1
}

Web Push Notification request

{
  "id": "00799aa8590ea7ff048f9fcb10000000",
  "imp": [
    {
      "id": "00799aa8590ea7ff048f9fcb12a00000",
      "tagid": "<zone_id>",
      "bidfloor": 0.001,
      "ext": {
        "type": "webpush"
      }
    }
  ],
  "site": {
    "id":  "<site_id>",
    "domain": "example.com",
    "keywords": "Millenium, Cisco, Hell"
  },
  "user": {
    "id": "4edbd6fa-b762-4c32-91c4-23e7fe872726"
  },
  "device": {
    "ua": "Mozilla/5.0 (Linux; Android 9; SAMSUNG SM-A105F Build/PPR1.180610.011) AppleWebKit/537.36 (KHTML, like Gecko) SamsungBrowser/9.0 Chrome/67.0.3396.87 Mobile Safari/537.36",
    "ip": "8.8.8.8",
    "language": "en"
  },
  "at": 1
}

Video PreRoll request

{
  "id": "b48a9a0a8c864bbab8592c0505f666cb",
  "imp": [
    {
      "id": "b48a9a0a8c864bbab8592c0505f666cb1",
      "video": {
        "mimes": ["video/mp4"],
        "protocols": [2,3],
        "w": 300,
        "h": 250
      },
      "tagid": "<zone_id>",
      "bidfloor": 0.1,
      "secure": 1,
      "ext": {
        "type": "video_banner",
      }
    }
  ],
  "site": {
    "id": "<site_id>",
    "domain": "example.com",
    "keywords": "Hell, Cisco, Mainstream"
  },
  "user": {
    "id": "694340061255827389"
  },
  "device": {
    "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 11_4_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15G77 Version/11.4.1 Safari/604.1 AlohaBrowser/2.10.0b17",
    "ip": "8.8.8.8",
    "language": "en"
  },
  "at": 1
}

Email request

{
  "id": "b48a9a0a8c864bbab8592c0505f666cb",
  "imp": [
    {
      "id": "b48a9a0a8c864bbab8592c0505f666cb1",
      "el": "{}",
      "tagid": "<zone_id>",
      "bidfloor": 0.1
    }
  ],
  "site": {
    "id": "<site_id>",
    "domain": "example.com",
    "keywords": "Hell, Cisco, Mainstream"
  },
  "device": {
    "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 11_4_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15G77 Version/11.4.1 Safari/604.1 AlohaBrowser/2.10.0b17",
    "ip": "8.8.8.8",
    "language": "en"
  },
  "user": {
    "id": "694340061255827389"
  },
  "at": 1
}

Popunder response

{
  "id": "c290ff3a9e3b36db39698a13706813ce",
  "seatbid": [
    {
      "bid": [
        {
          "id": "30767351-1918-4f53-8db6-31f8f98089fe",
          "impid": "c290ff3a9e3b36db39698a13706813ce",
          "price": 0.15,
          "adid": "1507372",
          "nurl": "https://notification.url",
          "burl": "https://billing.url",
          "adm": "https://click.url",
          "cid": "201609",
          "crid": "1507372"
        }
      ]
    }
  ]
}

Response documentation

Bid Response

Attribute Required Description
id string; required ID of the bid request to which this is a response. (i.e., must match bidrequest.id)
seatbid required Collection of bids made by the bidder on behalf of a specific seat.
bidid optional Bidder generated response ID to assist with logging/tracking.
ext object Placeholder for bidder-specific extensions to OpenRTB.

Seat Bid

Attribute Required Description
bid required Array of 1+Bidobjects each related to an impression. Multiple bids can relate to the same impression.
seat recommended ID of the bidder seat on whose behalf this bid is made.
group no 0 = impressions can be won individually; 1 = impressions must be won or lost as a group. Default 0
ext no Placeholder for bidder-specific extensions to OpenRTB.

Bid

Attribute Required Description
id required Bidder generated bid ID to assist with logging/tracking.
impid required ID of theImpobject in the related bid request.
price required Bid price expressed as CPM.
adid optional ID of a preloaded ad to be served if the bid wins.
nurl recommended Win notice URL called by the exchange if the bid wins.
adm required Optional means of conveying ad markup in case the bid wins; supersedes the win notice if markup is included in both. Substitution macros may be included.
iurl optional URL without cache-busting to an image that is representative of the content of the campaign for ad quality/safety checking.
cid recommended Campaign ID to assist with ad quality checking; the collection of creatives for which iurl should be representative.
crid required Creative ID to assist with ad quality checking.
attr optional Set of attributes describing the creative.
h optional Height of the creative in pixels.
w optional Width of the creative in pixels.
ext object Placeholder for bidder-specific extensions to OpenRTB.

Examples

{
  "id": "rtb_82_078b03e1b9d0ef386fd901ddc46b7f62_1569187754_153275834",
  "seatbid": [
    {
      "bid": [
        {
          "id": "024d1131-6183-43d2-a8f5-7c041712c279",
          "impid": "item_0",
          "price": 0.0035,
          "adid": "981397",
          "nurl": "http://notification.url",
          "burl": "http://billing.url",
          "adm": "<iframe src=\"click.url\" style=\"border:none\"scrolling=\"no\" allowtransparency=\"true\" allowfullscreen=\"true\" frameborder=\"0\" marginheight=\"0\" marginwidth=\"0\" vspace=\"0\" hspace=\"0\" seamless=\"\" width=\"300\" height=\"250\"></iframe>",
          "iurl": "https://image.url",
          "cid": "153969",
          "crid": "981397",
          "h": 250,
          "w": 300
        }
      ]
    }
  ]
}

Native response

{
  "id": "93b03d37-7b3e-4d61-a06d-88fd82a9ed72",
  "seatbid": [
    {
      "bid": [
        {
          "id": "a494df6f-8d81-49e0-bfa7-2298b6d8310d",
          "impid": "93b03d37-7b3e-4d61-a06d-88fd82a9ed72",
          "price": 0.012,
          "adid": "1429379",
          "nurl": "https://notification.url",
          "burl": "https://billing.url",
          "adm": "{\"native\":{\"ver\":\"1.2\",\"assets\":[{\"id\":1,\"img\":{\"type\":0,\"url\":\"https://image.url\"}},{\"id\":2,\"title\":{\"text\":\"Example title\"}}],\"link\":{\"url\":\"https://click.url\"},\"eventtrackers\":[{\"event\":1,\"methods\":[1],\"url\":\"https://image.url\"}]}}",
          "iurl": "https://image.url",
          "cid": "180474",
          "crid": "1429379"
        }
      ]
    }
  ]
}

Web Push Notification response

{
  "id": "93b03d37-7b3e-4d61-a06d-88fd82a9ed72",
  "seatbid": [
    {
      "bid": [
        {
          "id": "024d1131-6183-43d2-a8f5-7c041712c279",
          "impid": "93b03d37-7b3e-4d61-a06d-88fd82a9ed72",
          "price": 0.012,
          "nurl": "https://notification.url",
          "burl": "https://billing.url",
          "adm": "{\"id\":\"43ddb67e-e85e-425e-a29c-f0b16eeb2306\",\"title\":\"Example title\",\"content\":\"Example content\",\"url\":\"https://click.url",\"icon\":\"https://icon.url\",\"image\":\"https://image.url\"}",
          "adid": "1429379",
          "cid": "180474",
          "crid": "1429379"
        }
      ]
    }
  ]
}

Video PreRoll response

{
    "id": "93b03d37-7b3e-4d61-a06d-88fd82a9ed72",
    "seatbid":  [
        {
            "bid": [
                {
                    "id": "024d1131-6183-43d2-a8f5-7c041712c279",
                    "impid": "93b03d37-7b3e-4d61-a06d-88fd82a9ed72",
                    "price": 0.012,
                    "nurl": "https://notification.url",
                    "burl": "https://billing.url",
                    "adm": "<VAST version=\"3.0\"><Ad id=\"static\"><InLine><AdSystem>RTBPanda</AdSystem><Impression>https://image.url</Impression><Creatives><Creative><Linear><Duration>00:00:08</Duration><TrackingEvents><Tracking event=\"start\">http://tracking.url</Tracking></TrackingEvents><VideoClicks><ClickThrough>http://click.url</ClickThrough></VideoClicks><MediaFiles><MediaFile type=\"video/mp4\" bitrate=\"300\" width=\"480\" height=\"270\">http://example.com/uploads/myPrerollVideo.mp4</MediaFile></MediaFiles></Linear></Creative></Creatives></InLine></Ad></VAST>",
                    "adid": "1429379",
                    "cid": "180474",
                    "crid": "1429379"
                }
            ]
        }
    ]
}

Email response

{
    "id": "93b03d37-7b3e-4d61-a06d-88fd82a9ed72",
    "seatbid": [
        {
            "bid": [
                {
                    "id": "024d1131-6183-43d2-a8f5-7c041712c279",
                    "impid": "93b03d37-7b3e-4d61-a06d-88fd82a9ed72",
                    "price": 0.012,
                    "nurl": "https://notification.url",
                    "burl": "https://billing.url",
                    "adm": "<ad><emailClick><url>http://click.url</url></emailClick></ad>",
                    "adid": "1429379",
                    "cid": "180474",
                    "crid": "1429379"
                }
            ]
        }
    ]
}