OpenRTB specification
How to sell traffic to Youtarget via OpenRTBAn open IAB standard for real-time exchange of requests and bids between SSPs and DSPs. 2.5 and 2.6. Request–response pairs are on the OpenRTB examples page.
Specifications
- OpenRTB 2.5 and OpenRTB 2.6: the version is chosen for the integration when you connect.
- Native 1.2: Native Request 1.1 or 1.2 in the request, Native Response 1.1 in the response.
- VAST 4.2: we return VAST Wrapper 2.0–4.2 and VAST InLine 3.0.
- One currency per integration, agreed when you connect.
- Pricing models: CPMThe price per thousand impressions. (per 1,000 impressions) and CPC (per click); the model is set per integration.
- You can compress the request with gzip; we don't compress the response.
Supported formats
- Banner: example, including MRAID in apps and DOOH (2.6 only).
- Interstitial: example.
- Video: example, including rewarded and fullscreen.
- Native: example.
- Push: example.
- Popunder: example.
- Multiformat: example.
- Audio: not supported.
Push, popunder, HTML banners as is and native in a banner slot are enabled for the integration by your account manager: request fields can't tell them apart.
Key rules
IMPORTANT
- We process only
imp[0]. We ignore the otherimpelements: one placement, one request. - The creative is always in
adm.nurlis only a notification; we don't serve markup from it. ${AUCTION_PRICE}as a plain number. Innurlandburl, pass a price like0.85: if the macro is left as is or the price is encrypted, the notice is rejected and the impression is not counted.- No bid:
204with no body. - There is no test mode. We process a request with
test=1as a regular one: bids and notifications are live.
Connection
- One endpoint for all integration variants, for example
https://bid.example.com/bid?id=5b0f3c1e-8a2d-4f6b-9c7e-2d4a6b8c0e1f. Theidparameter is the integration UUID; the manager sends you the full URL. - Method:
POST; the body is a JSON BidRequest. You can keep the connection open (keep-alive). Content-Type: application/jsonis required;Content-Encoding: gzipif you compress. Other encodings are not supported.- We don't read
X-OpenRTB-Version: in both versions we understand the 2.5 and 2.6 field names, and if both are present, we use the 2.6 field. - A bid response comes with
Content-Type: application/json; charset=utf-8andX-OpenRTB-Version: 2.5or2.6. In the Popunder over OpenRTB variant, parse the body as JSON without relying on the headers.
| Integration variant | How it differs |
|---|---|
| OpenRTB 2.5 | Response in 2.5 form, see differences between 2.5 and 2.6. |
| OpenRTB 2.6 | Response in 2.6 form; we accept the dooh context. |
| HTML banners as is | Like OpenRTB 2.6, but the HTML banner comes in adm in its original form, without our JS wrapper. |
| Popunder over OpenRTB | We treat any imp as a popunder; adm carries the URL to open. Response in 2.5 form. |
The manager configures the variant, formats, pricing model, currency, impression counting event, response time and requests per second limit. The variant is not passed in the request.
Notifications
Each bid has nurl and burl, and sometimes lurl:
https://notify.example.com/wn?id=<bid.id>&t=<токен>&price=${AUCTION_PRICE}
https://notify.example.com/bn?id=<bid.id>&t=<токен>&price=${AUCTION_PRICE}
https://notify.example.com/ln?id=<bid.id>&t=<токен>&price=${AUCTION_PRICE}&loss=${AUCTION_LOSS}&mtw=${AUCTION_MIN_TO_WIN}- The SSP calls
nurlwhen the bid wins,burlwhen the impression has happened and can be billed, andlurlwhen the bid loses. Method:GETorPOST. - Call them right after the event: we accept notices for a limited time after the bid.
- Don't change or truncate the
idandtparameters, and don't encode the URL again. - The impression is counted by the event agreed when you connect:
nurl,burl, our impression pixel inadm, or the click with CPC. Call bothnurlandburl, even if counting is based on only one of them. - We don't count a price above our bid: we count at the bid price. A repeated notice for the same bid is not counted a second time.
- In
lurlyou may leave the macros unreplaced. - The event time is the moment the notice reaches us, not the request time. Keep this in mind at the day boundary during reconciliation.
- In the Popunder over OpenRTB variant,
nurlandburlhave no price macro; we count at our bid price. We count the impression when the user opens the URL fromadm, or bynurlorburlif agreed. A URL opened by a bot is not counted.
| Response | Meaning |
|---|---|
200 | Accepted. A repeated notice also gets 200. |
400 | No id or it is not a UUID, the t token is missing or invalid, the acceptance period has expired, the price is not a number. |
Response codes
| Code | Meaning | What to do |
|---|---|---|
200 | There is a bid; the body is a BidResponse. | Show adm, call the notifications. |
204 | No bid; the body is empty. We also respond this way if the request limit is exceeded, the request failed the traffic quality check or the integration filters, or tmax expired. We don't send the reason (nbr). | Nothing, this is a regular no-bid. |
400 | No id in the URL; the body is not JSON or cannot be decompressed; no request id; imp is empty; an imp has no id; an imp has none of banner, video, native or audio (the Popunder over OpenRTB variant needs no format objects). | Fix the request. |
403 | The integration is inactive. | Contact the manager. |
404 | There is no integration with this id. | Check the URL. |
We don't reject the request if device.ip is empty (but without an IP there is no geo, and campaigns with geo targeting won't buy the impression), video has no mimes, linearity or protocols, native.request cannot be read, or both site and app are present.
Macros
| Macro | Where | Replace with |
|---|---|---|
${AUCTION_PRICE} | nurl, burl, lurl | The clearing price as a plain number with a decimal point, in the cur currency and the units of the pricing model. Required in nurl and burl. |
${AUCTION_LOSS} | lurl | The OpenRTB loss reason code. |
${AUCTION_MIN_TO_WIN} | lurl | The minimum price that would have won the auction. |
[ERRORCODE] | <Error> in VAST | The VAST error code; the video player fills it in. |
Our URLs contain no other macros, and price encryption is not supported. SSP price macros are not used in adm.
Bid request
"Yes" means that without the field the request gets 400 or almost no one will buy it: without device.ip there is no geo, without device.ua no device, and without tagid and the domain advertiser filters don't work. "Recommended" means fewer bids without it. You can pass fields that are not in the tables: they don't affect the bid. Where 2.5 and 2.6 name a field differently, we understand both, and if both are present, we use the 2.6 field.
BidRequest
| Field | Required | Description |
|---|---|---|
id | yes | string; we return it in BidResponse.id. |
imp | yes | object[]; we read only the first element. |
site, app, dooh | yes | Impression context, one of the objects. dooh is 2.6 only. |
device | yes | We use it to determine geo, device type, OS and browser. |
user | recommended | The user and their ID after cookie syncMatching user IDs between two ad systems.. |
regs | recommended | GDPR flag, see Privacy. |
tmax | recommended | integer, response time in milliseconds, see Limits. |
cur | no | string[]. If passed, it must contain the integration currency, otherwise 204. |
bcat | no | IAB categories whose creatives we don't buy. |
badv | no | Advertiser domains whose creatives we don't buy. |
wlangb (2.6), wlang | no | Language for selecting creatives; the order is below the table. |
test | no | Does not enable a test mode, see Key rules. |
We take the first language found: wlangb or wlang, then content.langb or content.language, then device.langb or device.language. A BCP 47 code is reduced to the language: de-AT → de.
Accepted but not used: bapp, acat, cattax, allimps.
imp
| Field | Required | Description |
|---|---|---|
id | yes | string; we return it in bid.impid. |
banner, video, native | yes | At least one object. Several in one imp mean multiformat. |
tagid | yes | Placement ID; we create a zoneA specific ad slot on a site or in an app, for example a block on a site page. from it. Advertisers target zones and see statistics by them, so keep tagid stable. |
bidfloor | no | float, minimum price, see Price and floor. |
bidfloorcur | no | Currency of bidfloor, ISO 4217 code. |
instl | no | 1 means a fullscreen placement. We accept a number or a string. |
rwdd (2.6), ext.rewarded (2.5) | only for video | 1 means rewarded video. We also accept video.ext.rewarded. |
If tagid is empty or "0", we take the zone ID from site.id, app.id or dooh.id, and if they are missing too, from publisher.ext.subid.
Accepted but not used: secure (markup always uses https), pmp (no deals; dealid never appears in the response), exp, audio (a request with only audio gets 204).
TIP
Interstitial is instl=1 together with banner or video. We return only creatives for fullscreen placement; the markup is the same as for a regular banner or video.
TIP
Multiformat: we buy the formats that are present in imp and enabled for the integration. If several match (for example, native and push for imp.native), all of them compete in the auction, and the response carries the winner's markup. To get one format only, ask the manager to leave only that format enabled for the integration.
banner
| Field | Required | Description |
|---|---|---|
format | recommended | object[], allowed sizes. We discard sizes with a zero. |
w, h | recommended | Size, if there is no format. |
api | no | 5 (MRAID 2) or 6 (MRAID 3) in an app means we can return an MRAID creative. We ignore 3 (MRAID 1). |
Accepted but not used: btype, battr, mimes, wmin, wmax, hmin, hmax.
video
| Field | Required | Description |
|---|---|---|
protocols | recommended | integer[]; we use them to choose the VAST type and version, see VAST selection. |
minduration, maxduration | recommended | Allowed video duration in seconds. |
plcmt (2.6), placement (2.5) | recommended | Placement type: instream, outstream and others. If both are present, we use plcmt. |
startdelay | no | Position in the video: pre-, mid- or post-roll. |
skip, skipafter | no | Whether the video can be skipped and after how many seconds. |
playbackmethod | no | How playback starts. |
companionad, companiontype | no | Companion banner (end card). |
api | no | Supported APIs. In a multiformat imp, we merge the api of all objects. |
Accepted but not used: mimes.
native
| Field | Required | Description |
|---|---|---|
request | yes | string: Native Request 1.1 or 1.2 as a JSON string, without the {"native": …} wrapper. |
ver | no | Native Request version. |
Inside request we read assets, plcmtcnt, plcmttype, context, seq and eventtrackers. Accepted but not used: battr.
| Asset | Native | Push |
|---|---|---|
title | Title | Title |
img, type=3 (main image) | Creative image | Large image |
img, type=1 (icon) | — | Icon |
data, type=2 (description) | — | Notification text |
data, type=12 (button text) | Button text | — |
If a required asset (required: 1) cannot be filled, for example video or data with type=1, we don't bid with the creative. We don't return optional assets that the creative doesn't have.
TIP
Push and popunder come for a regular imp.native (popunder also for imp.banner). The format is set by the integration settings with the manager, not by a request field.
site, app and dooh
| Field | Required | Description |
|---|---|---|
id | recommended | Placement ID, fallback zone ID. |
domain | yes, for site | Placement domain. |
bundle | yes, for app | App ID in the store. |
cat | no | IAB categories of the placement. |
publisher.ext.subid | no | Sub-ID of your source: advertisers see it and can target it. |
content.cat | no | Content categories. |
content.langb (2.6), content.language | no | Content language. |
content.contentrating | no | Age rating on the MPAA scale; we use it to select creatives. |
dooh is 2.6 only; pass it instead of site and app.
device
| Field | Required | Description |
|---|---|---|
ip | yes | We determine geo by IP only. |
ipv6 | no | Used if there is no ip. |
ua | yes | Device type, OS and browser. |
make, model, os, osv | no | Manufacturer, model, OS and OS version. |
langb (2.6), language | no | Device language. |
ifa | no | Advertising ID. We discard an all-zero ID and don't use it when gdpr=1. |
Accepted but not used: geo; we take geo from the IP.
user
| Field | Required | Description |
|---|---|---|
id | recommended | The user ID on your side. |
buyeruid | recommended | Our user ID after sync. |
consent (2.6), ext.consent (2.5) | no | TCF consent string; we don't parse it. |
regs
| Field | Required | Description |
|---|---|---|
gdpr (2.6), ext.gdpr (2.5) | recommended | 1 means GDPR applies to the user. We accept 1, "1" and true. |
coppa, us_privacy, gpp, gpp_sid | no | They don't break the request, see Privacy. |
Bid response
A response with a bid is 200 and a BidResponse.
BidResponse and seatbid
| Field | Required | Description |
|---|---|---|
id | yes | The id of your request. |
cur | yes | The integration currency; does not depend on the request cur. |
seatbid | yes | object[], bids. |
seatbid.seat | yes | Buyer ID (seat). |
Not filled in: bidid, nbr.
bid
| Field | Required | Description |
|---|---|---|
id | yes | Bid ID, a UUID. It is also the id parameter in our notifications. |
impid | yes | imp[0].id of your request. |
price | yes | float, the bid in the cur currency and the units of the pricing model. |
adm | yes | Creative markup, see What comes in adm. |
nurl, burl | yes | Win notice and billing notice. |
lurl | no | Loss notice; not every bid has it, so support it. |
adid, crid | yes | CreativeAn ad inside a campaign: a banner, a native block, a push, a pop or a video. ID. |
cid | yes | Campaign ID. |
adomain | no | string[], advertiser domain. |
cat | no | string[], IAB categories of the creative. |
w, h | no | Creative size; the rule is below the table. |
protocol | only for video | Which VAST we returned. |
apis (2.6), api (2.5) | no | Creative API, for example 6 for MRAID 3. |
langb (2.6), language (2.5) | no | Creative language. |
mtype (2.6) | no | Markup type: 1 is banner and native in a banner slot, 2 is video, 4 is native and push. Not present for popunder. |
dur (2.6) | only for video | Video duration in seconds. |
ext.cpc | only for CPC | Click price, equal to price. |
For a banner, w and h are the size of the HTML creative if it is fixed; otherwise the matching requested size; otherwise the closest by aspect ratio; otherwise the first requested size. For native and push, the size of the main image.
Not filled in: attr, iurl, bundle, dealid, exp, qagmediarating, cattax, slotinpod.
Differences between 2.5 and 2.6
| What | OpenRTB 2.5 | OpenRTB 2.6 |
|---|---|---|
| Creative API | api, a single number | apis, an array |
| Creative language | language | langb |
| Markup type | none: tell by adm (HTML, VAST, JSON) | mtype |
| Video duration | none | dur |
What comes in adm
Show adm unchanged: the impression, viewability and click trackers are already inside. Markup and trackers always use https.
- Banner, interstitial, DOOH: an HTML fragment with a
<div>and asynchronous loading of our JS, which renders the creative in an iframe and sends the trackers itself. The JS must run; the container ID is new in each response. - MRAID: the creative's HTML that loads
mraid.js(provided by the app SDK), with our trackers.bid.apis(bid.apiin 2.5) is6if MRAID 3 was declared, otherwise5. - HTML banners as is: the creative's original HTML and
<img>impression pixels, for third-party tags that don't work in an iframe. We don't track clicks or viewability; image banners and HTML files come with the regular delivery. - Native in a banner slot: HTML, as for a banner, sized to the slot:
mtype=1, andwandhequal the slot size. - Video: VAST XML; the type and version follow the VAST selection table. It contains
<Impression>,<Tracking>forstart, quartiles,completeandskip,<Error>with[ERRORCODE], and InLine also has<ClickThrough>. - Native and push: Native Response 1.1 as a JSON string without the
nativewrapper: assets,link.url,link.clicktrackers,imptrackersandeventtrackers(event1is impression,2is 50% viewability per MRC,3is 100% viewability per MRC,4is 50% video viewability;method1is pixel). - Popunder: Native Response 1.1 with the URL to open in a new window or tab in
link.url; the image comes ifimgwithtype=3was requested and the creative has one. - Popunder over OpenRTB: the URL as a string; open it as a popunder or a new tab. The URL leads to the landing page via a redirect or an intermediate page.
- Multiformat: the markup of the winning format; in 2.6 you can tell it by
mtype, in 2.5 by the contents ofadm.
VAST selection
What is in video.protocols | What we return |
|---|---|
A Wrapper is present: 5 (2.0), 6 (3.0), 8 (4.0), 12 (4.1), 14 (4.2) | VAST Wrapper of the newest declared Wrapper version |
InLine only: 2 (2.0), 3 (3.0), 7 (4.0), 11 (4.1), 13 (4.2) | VAST InLine 3.0 |
| Empty or no field | VAST Wrapper 4.2 |
We don't support DAAST (9, 10). We tell outstream from instream by plcmt (placement in 2.5); their markup is the same.
Price and floor
price,bidfloorand${AUCTION_PRICE}use the integration currency and the units of the pricing model: with CPM, per 1,000 impressions; with CPC, per click. With CPC, the price is duplicated inbid.ext.cpc, see the example.- We don't send a bid below
imp.bidfloor. We don't take any other floorThe minimum bid below which an impression is not sold. into account. - We convert
bidfloorcurto the integration currency; the code is case-insensitive. If there is nobidfloorcuror the code is unknown, we treat the floor as being in the integration currency. - The response
curis always the integration currency. - In the Popunder over OpenRTB variant, with CPM the price is per 1,000 popunders, with CPC per one; there is no
extfield.
Privacy
- GDPR:
regs.gdpr(2.6) orregs.ext.gdpr(2.5). Whengdpr=1, we don't usedevice.ifa. - We don't parse the TCF consent string from
user.consent(2.6) oruser.ext.consent(2.5): we decide onifaby thegdprflag only. regs.coppa,us_privacy,gppandgpp_siddon't break the request. Ask the manager how we take them into account.
Limits
- We count
tmaxfrom the moment we receive the request; account for network latency yourself. If we don't make it in time, we respond204. - If the integration has a custom response time, it takes precedence over
tmax. - The integration has a requests per second limit; requests over it get
204. - For banner and video we respond with one bid; for native, with no more than
plcmtcnt, one by default. - Deals (PMP) are not supported.