<!-- https://docs.youtarget.com/rtb/en/ssp/openrtb.html -->

# OpenRTB specification

> How to sell traffic to Youtarget via OpenRTB 2.5 and 2.6: formats, endpoint, notifications, response codes, macros, request and response fields, price and floor.

How to sell traffic to Youtarget via [OpenRTB](https://docs.youtarget.com/rtb/en/glossary/openrtb.md) 2.5 and 2.6. Request–response pairs are on the [OpenRTB examples](./examples/banner.md) page.

## Specifications

- [OpenRTB 2.5](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf) and [OpenRTB 2.6](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/2.6.md): the version is chosen for the integration when you connect.
- [Native 1.2](https://www.iab.com/wp-content/uploads/2018/03/OpenRTB-Native-Ads-Specification-Final-1.2.pdf): Native Request 1.1 or 1.2 in the request, Native Response 1.1 in the response.
- [VAST 4.2](https://iabtechlab.com/wp-content/uploads/2019/06/VAST_4.2_final_june26.pdf): we return VAST Wrapper 2.0–4.2 and VAST InLine 3.0.
- One currency per integration, agreed when you connect.
- Pricing models: [CPM](https://docs.youtarget.com/rtb/en/glossary/cpm.md) (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](./examples/banner.md), including MRAID in apps and DOOH (2.6 only).
- Interstitial: [example](./examples/interstitial.md).
- Video: [example](./examples/video.md), including rewarded and fullscreen.
- Native: [example](./examples/native.md).
- Push: [example](./examples/push.md).
- Popunder: [example](./examples/popunder.md).
- Multiformat: [example](./examples/multiformat.md).
- 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 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 variant | How it differs |
| --- | --- |
| OpenRTB 2.5 | Response in 2.5 form, see [differences between 2.5 and 2.6](#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`:

```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](../common/reconciliation.md).
- 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.

| 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 sync](https://docs.youtarget.com/rtb/en/glossary/cookie-sync.md). |
| `regs` | recommended | GDPR flag, see [Privacy](#privacy). |
| `tmax` | recommended | `integer`, response time in milliseconds, see [Limits](#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](#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 [zone](https://docs.youtarget.com/rtb/en/glossary/zone.md) from it. Advertisers target zones and see statistics by them, so keep `tagid` stable. |
| `bidfloor` | no | `float`, minimum price, see [Price and floor](#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](#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](../common/cookie-sync.md). |
| `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](#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](#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 | [Creative](https://docs.youtarget.com/rtb/en/glossary/creative.md) 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.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](#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.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`, `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](./examples/more.md#native-with-cpc-pricing).
- We don't send a bid below `imp.bidfloor`. We don't take any other [floor](https://docs.youtarget.com/rtb/en/glossary/bid-floor.md) 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.
