Skip to content

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 ​

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 other imp elements: one placement, one request.
  • The creative is always in adm. nurl is only a notification; we don't serve markup from it.
  • ${AUCTION_PRICE} as a plain number. In nurl and burl, pass a price like 0.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: 204 with no body.
  • There is no test mode. We process a request with test=1 as 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. The id parameter 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/json is required; Content-Encoding: gzip if 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-8 and X-OpenRTB-Version: 2.5 or 2.6. In the Popunder over OpenRTB variant, parse the body as JSON without relying on the headers.
Integration variantHow it differs
OpenRTB 2.5Response in 2.5 form, see differences between 2.5 and 2.6.
OpenRTB 2.6Response in 2.6 form; we accept the dooh context.
HTML banners as isLike OpenRTB 2.6, but the HTML banner comes in adm in its original form, without our JS wrapper.
Popunder over OpenRTBWe 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:

text
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 nurl when the bid wins, burl when the impression has happened and can be billed, and lurl when the bid loses. Method: GET or POST.
  • Call them right after the event: we accept notices for a limited time after the bid.
  • Don't change or truncate the id and t parameters, and don't encode the URL again.
  • The impression is counted by the event agreed when you connect: nurl, burl, our impression pixel in adm, or the click with CPC. Call both nurl and burl, 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 lurl you 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, nurl and burl have no price macro; we count at our bid price. We count the impression when the user opens the URL from adm, or by nurl or burl if agreed. A URL opened by a bot is not counted.
ResponseMeaning
200Accepted. A repeated notice also gets 200.
400No 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 ​

CodeMeaningWhat to do
200There is a bid; the body is a BidResponse.Show adm, call the notifications.
204No 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.
400No 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.
403The integration is inactive.Contact the manager.
404There 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 ​

MacroWhereReplace with
${AUCTION_PRICE}nurl, burl, lurlThe 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}lurlThe OpenRTB loss reason code.
${AUCTION_MIN_TO_WIN}lurlThe minimum price that would have won the auction.
[ERRORCODE]<Error> in VASTThe 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 ​

FieldRequiredDescription
idyesstring; we return it in BidResponse.id.
impyesobject[]; we read only the first element.
site, app, doohyesImpression context, one of the objects. dooh is 2.6 only.
deviceyesWe use it to determine geo, device type, OS and browser.
userrecommendedThe user and their ID after cookie syncMatching user IDs between two ad systems..
regsrecommendedGDPR flag, see Privacy.
tmaxrecommendedinteger, response time in milliseconds, see Limits.
curnostring[]. If passed, it must contain the integration currency, otherwise 204.
bcatnoIAB categories whose creatives we don't buy.
badvnoAdvertiser domains whose creatives we don't buy.
wlangb (2.6), wlangnoLanguage for selecting creatives; the order is below the table.
testnoDoes 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 ​

FieldRequiredDescription
idyesstring; we return it in bid.impid.
banner, video, nativeyesAt least one object. Several in one imp mean multiformat.
tagidyesPlacement 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.
bidfloornofloat, minimum price, see Price and floor.
bidfloorcurnoCurrency of bidfloor, ISO 4217 code.
instlno1 means a fullscreen placement. We accept a number or a string.
rwdd (2.6), ext.rewarded (2.5)only for video1 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.

FieldRequiredDescription
formatrecommendedobject[], allowed sizes. We discard sizes with a zero.
w, hrecommendedSize, if there is no format.
apino5 (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 ​

FieldRequiredDescription
protocolsrecommendedinteger[]; we use them to choose the VAST type and version, see VAST selection.
minduration, maxdurationrecommendedAllowed video duration in seconds.
plcmt (2.6), placement (2.5)recommendedPlacement type: instream, outstream and others. If both are present, we use plcmt.
startdelaynoPosition in the video: pre-, mid- or post-roll.
skip, skipafternoWhether the video can be skipped and after how many seconds.
playbackmethodnoHow playback starts.
companionad, companiontypenoCompanion banner (end card).
apinoSupported APIs. In a multiformat imp, we merge the api of all objects.

Accepted but not used: mimes.

native ​

FieldRequiredDescription
requestyesstring: Native Request 1.1 or 1.2 as a JSON string, without the {"native": …} wrapper.
vernoNative Request version.

Inside request we read assets, plcmtcnt, plcmttype, context, seq and eventtrackers. Accepted but not used: battr.

AssetNativePush
titleTitleTitle
img, type=3 (main image)Creative imageLarge 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 ​

FieldRequiredDescription
idrecommendedPlacement ID, fallback zone ID.
domainyes, for sitePlacement domain.
bundleyes, for appApp ID in the store.
catnoIAB categories of the placement.
publisher.ext.subidnoSub-ID of your source: advertisers see it and can target it.
content.catnoContent categories.
content.langb (2.6), content.languagenoContent language.
content.contentratingnoAge rating on the MPAA scale; we use it to select creatives.

dooh is 2.6 only; pass it instead of site and app.

device ​

FieldRequiredDescription
ipyesWe determine geo by IP only.
ipv6noUsed if there is no ip.
uayesDevice type, OS and browser.
make, model, os, osvnoManufacturer, model, OS and OS version.
langb (2.6), languagenoDevice language.
ifanoAdvertising 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 ​

FieldRequiredDescription
idrecommendedThe user ID on your side.
buyeruidrecommendedOur user ID after sync.
consent (2.6), ext.consent (2.5)noTCF consent string; we don't parse it.

regs ​

FieldRequiredDescription
gdpr (2.6), ext.gdpr (2.5)recommended1 means GDPR applies to the user. We accept 1, "1" and true.
coppa, us_privacy, gpp, gpp_sidnoThey don't break the request, see Privacy.

Bid response ​

A response with a bid is 200 and a BidResponse.

BidResponse and seatbid ​

FieldRequiredDescription
idyesThe id of your request.
curyesThe integration currency; does not depend on the request cur.
seatbidyesobject[], bids.
seatbid.seatyesBuyer ID (seat).

Not filled in: bidid, nbr.

bid ​

FieldRequiredDescription
idyesBid ID, a UUID. It is also the id parameter in our notifications.
impidyesimp[0].id of your request.
priceyesfloat, the bid in the cur currency and the units of the pricing model.
admyesCreative markup, see What comes in adm.
nurl, burlyesWin notice and billing notice.
lurlnoLoss notice; not every bid has it, so support it.
adid, cridyesCreativeAn ad inside a campaign: a banner, a native block, a push, a pop or a video. ID.
cidyesCampaign ID.
adomainnostring[], advertiser domain.
catnostring[], IAB categories of the creative.
w, hnoCreative size; the rule is below the table.
protocolonly for videoWhich VAST we returned.
apis (2.6), api (2.5)noCreative API, for example 6 for MRAID 3.
langb (2.6), language (2.5)noCreative language.
mtype (2.6)noMarkup 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 videoVideo duration in seconds.
ext.cpconly for CPCClick 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 ​

WhatOpenRTB 2.5OpenRTB 2.6
Creative APIapi, a single numberapis, an array
Creative languagelanguagelangb
Markup typenone: tell by adm (HTML, VAST, JSON)mtype
Video durationnonedur

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.api in 2.5) is 6 if MRAID 3 was declared, otherwise 5.
  • 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, and w and h equal the slot size.
  • Video: VAST XML; the type and version follow the VAST selection table. It contains <Impression>, <Tracking> for start, quartiles, complete and skip, <Error> with [ERRORCODE], and InLine also has <ClickThrough>.
  • Native and push: Native Response 1.1 as a JSON string without the native wrapper: assets, link.url, link.clicktrackers, imptrackers and eventtrackers (event 1 is impression, 2 is 50% viewability per MRC, 3 is 100% viewability per MRC, 4 is 50% video viewability; method 1 is pixel).
  • Popunder: Native Response 1.1 with the URL to open in a new window or tab in link.url; the image comes if img with type=3 was 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 of adm.

VAST selection ​

What is in video.protocolsWhat 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 fieldVAST 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, bidfloor and ${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 in bid.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 bidfloorcur to the integration currency; the code is case-insensitive. If there is no bidfloorcur or the code is unknown, we treat the floor as being in the integration currency.
  • The response cur is 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 ext field.

Privacy ​

  • GDPR: regs.gdpr (2.6) or regs.ext.gdpr (2.5). When gdpr=1, we don't use device.ifa.
  • We don't parse the TCF consent string from user.consent (2.6) or user.ext.consent (2.5): we decide on ifa by the gdpr flag only.
  • regs.coppa, us_privacy, gpp and gpp_sid don't break the request. Ask the manager how we take them into account.

Limits ​

  • We count tmax from the moment we receive the request; account for network latency yourself. If we don't make it in time, we respond 204.
  • 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.

© Youtarget