Server-to-Server (S2S) Calls

Adagio supports Server-to-Server (S2S) integrations for in-app inventory monetization via the OpenRTB 2.5 and 2.6 protocol.

This document outlines the process for sending BidRequests and handling BidResponses, including the required parameters and Adagio-specific requirements.

We support both versions for backward compatibility. Refer to the official IAB documentation:

If a parameter is not explicitly mentioned below it should be considered as unsupported.

1. S2S Headers

1.1 OpenRTB Version

The OpenRTB Version should be passed in the header of a bid request with a custom HTTP header.

x-openrtb-version: 2.5
x-openrtb-version: 2.6

1.2 Endpoints Integrations

Adagio supports regional endpoints for optimal latency and compliance. Use the endpoint corresponding to your primary traffic location or the location of the server from which you're calling Adagio.

Serious risk of underperformance: Failing to route your request to the correct regional endpoint will result in increased latency and missed opportunity to benefit from demand partner's localized campaigns.

Region

URL

Method

City

Data Center

AMER

https://mp-las.4dex.io/ortb/{PUBLISHER_ID}

POST

Las Vegas

GCP us-west4

EMEA

https://mp-ams.4dex.io/ortb/{PUBLISHER_ID}

POST

Amsterdam

GCP europe-west4

APAC

https://mp-tyo.4dex.io/ortb/{PUBLISHER_ID}

POST

Tokyo

GCP asia-northeast1

Your PUBLISHER_ID can be found under Settings > General in the Adagio Manager.

1.3 Data compression (Gzip)

Adagio ONLY supports Compressed JSON (gzip) for bid requests and bid responses.

It is mandatory to use Compressed JSON to reduce the amount of data exchanged between you and Adagio, as this decreases latency times between servers, and traffic listening costs for all parties involved.

Configure compressed JSON bid requests and enable compressed responses:

Compress your HTTP request body with gzip

Add a Content-Encoding: gzip HTTP header to indicate that the request is compressed

Add an Accept-Encoding: gzip header to indicate that you can accept a compressed response

Bid responses include a Content-Encoding: gzip HTTP header to indicate compression. To distinguish between JSON and Compressed JSON formats, check for this header. If present, decompress the HTTP body before processing.

2. Important oRTB parameters

This sections tries to offer a quick overview over all the parameters that bear a particular importance to a successful monetization but you'll find in following sections the list of all supported parameters.

2.1 Required parameters

AdRequests that do not include these parameters won't be monetized, we've only listed the parameters that are specific to Adagio

bidrequest.imp[].tagid
bidrequest.app.bundle
bidrequest.regs.*

2.2 Recommended parameters

Including the parameters below has been shown to increase the monetization performance of your inventory

⚡️ Highly recommended

bidrequest.tmax

bidrequest.imp[].gpid
bidrquest.imp.ext.skadn: for iOS 14+

bidrequest.app.storeurl

bidrequest.device.ifa

bidrequest.device.ext.ifa_type

if open measurement is present :
- bidrequest.imp[].api = 7
- bidrequest.source.ext.omidpn (string): OM SDK partner name.
- bidrequest.source.ext.omidpv (string): OM SDK version

✅ Recommended

bidrequest.app.cat
bidrequest.app.paid
bidrequest.app.privacypolicy
bidrequest.app.ver
bidrequest.app.ext.category
bidrequest.app.ext.pagetype
bidrequest.imp[].metric
bidrequest.imp[].displaymanager
bidrequest.imp[].displaymanagerver
bidrequest.device.*: all sub-fields are considered as bringing value to the demand
bidrequest.device.geo

3. Publisher's BidRequests

The BidRequest object is the root of an OpenRTB request. It contains all the attributes required to describe the ad opportunity, the environment, the user, and any additional context needed for bidding.

3.1 `bidrequest` object

Attribute

Type

Required

Description

id

string

Required

ID of the bid request, assigned by the exchange, and unique for the exchange’s subsequent tracking of the responses. The exchange may use different values for different recipients.

imp

object array

Required

Array of Imp objects representing the impressions offered. At least 1 Imp object is required.

app

object

Recommended

Details via App object about the publisher’s app (i.e., non-browser applications). Only applicable and recommended for apps.

device

object

Recommended

Details via a Device object about the user’s device to which the impression will be delivered.

user

object

Recommended

Details via a User object about the human user of the device; the advertising audience.

test

integer; default 0

Optional

Indicator of test mode in which auctions are not billable, where 0 = live mode, 1 = test mode.

at

integer; default 2

Optional

Auction type, where 1 = First Price, 2 = Second Price. We only support 2 = Second Price (other values are overridden before broadcasting to demand partners).

tmax

integer

Recommended

Maximum time in milliseconds the exchange allows for bids to be received including Internet latency to avoid timeout. This value supersedes any a priori guidance from the exchange. (refer to Timeout requirement (tmax)for recommended values)

cur

string array

Optional

Array of allowed currencies for bids on this bid request (refer to Ensure Supported Currencies for supported currency symbols). If no currency is specified, default is USD.

acat

string array

Optional

Allowed advertiser categories using the specified category taxonomy. The taxonomy to be used is defined by the cattax field. If no cattax field is supplied IAB Content Taxonomy 1.0 is assumed. Only one of acat or bcat should be present.

bcat

string array

Optional

Blocked advertiser categories using the specified category taxonomy. The taxonomy to be used is defined by the cattax field. If no cattax field is supplied IAB Content Taxonomy 1.0 is assumed. Only one of acat or bcat should be present.

cattax

integer; default 1

Optional

The taxonomy in use for bcat. Refer to the AdCOM 1.0 list List: Category Taxonomies for values. Values other than 1 are strongly discouraged, please contact your CSM if you use them.

badv

string array

Optional

Block list of advertisers by their domains (e.g., “ford.com”). A maximum of 50 domains can be blocked.

bapp

string array

Optional

Block list of applications by their app store IDs. For mobile apps in Google Play Store, these should be bundle or package names (e.g. com.foo.mygame). For apps in Apple App Store, these should be a numeric ID.

source

object

Recommended

A source object that provides data about the inventory source and which entity makes the final decision.

regs

object

Required, if applicable

A regs object that specifies any industry, legal, or governmental regulations in force for this request.

ext

object

Optional

Placeholder for exchange-specific extensions to OpenRTB.

ext.placementtype

string

Optional

Indicates whether the user receives a reward for viewing the ad, when set to "rewarded". Refer to 4.3 Rewarded Adsfor all means to signal rewarded inventory.

3.2 `source` object

Field

Type

Req

Description

fd

integer

Recommended

Denotes who makes the final sell decision: 0 = exchange, 1 = upstream platform (e.g., header bidding). Usually this should be set to 1.

tid

string

Recommended

Transaction ID shared across all participants in the bid request.

schain

object

Recommended

IAB SupplyChain object outlining the full supply path and completeness. Refer to official documentation for more information

ext

object

Optional

Placeholder for exchange-specific extensions to OpenRTB.

ext.omidpn

string

Recommended

Identifier of the OM SDK integration. This is the same as the “name” parameter of the OMID Partner object.

ext.omidpv

string

Recommended

Version of the OM SDK integration. This is the same as the “versionString” parameter of the OMID Partner object.

3.3 `regs` object

Field

Type

Req

Description

coppa

integer

Required, if applicable

1 if COPPA applies (for children under 13), 0 otherwise. Refer to section 7.5 in official documentation.

gdpr or ext.gdpr

integer

Required, if applicable

1 if GDPR applies (EU/UK user), 0 if not. If 1, do fill user.consent (refer to 3.14 user object ).

us_privacy or ext.us_privacy

string

Required, if applicable

CCPA/US-privacy consent string. See IAB US Privacy String specifications.

gpp

string

Required, if applicable

Contains the Global Privacy Platform’s consent string. See the Global Privacy Platform specification for more details.

gpp_sid

integer array

Optional

Array of the section(s) of the string which should be applied for this transaction. Generally will contain one and only one value, but there are edge cases where more than one may apply. See the GPP Section Information for more details.

3.4 `imp` object

Field

Type

Required

Description

id

string

Required

A unique identifier for this impression within the content of the bid request (typically, starts with 1 and increments).

tagid

string

Required

Identifier for specific ad placement or ad tag that was used to initiate the auction. Refer to Limit number of tagid per appfor constraints.

metric

object array

Recommended

An array of Metric object. These metrics can offer insight into the impression to assist with decisioning such as average recent viewability, click-through rate, etc. Refer to official documentation for more information

banner

object

Required if banner ad

A banner object is required if this impression is offered as a banner ad opportunity.

video

object

Required if video ad

A video object is required if this impression is offered as a video ad opportunity.

native

object

Required if native ad

A native object is required if this impression is offered as a native ad opportunity.

displaymanager

string

Recommended

Name of ad mediation partner, SDK technology, or player responsible for rendering ad (typically video or mobile). Used by some ad servers to customize ad code by partner. Recommended for video and/or apps.

displaymanagerver

string

Recommended

Version of ad mediation partner, SDK technology, or player responsible for rendering ad (typically video or mobile). Used by some ad servers to customize ad code by partner. Recommended for video and/or apps.

instl

integer; default 0

Recommended

1 = the ad is interstitial or full screen, 0 = not interstitial. For video mediatype, if instl = 1, plcmt should be equal to 3

bidfloor

float; default 0

Optional

Minimum bid for this impression expressed in CPM.

bidfloorcur

string; default "USD"

Optional

Currency specified using ISO-4217 alpha codes. This may be different from bid currency returned by bidder if this is allowed by the exchange. This currency sets the default for all floors specified in the Imp object. Refer to our list of supported currencie s.

clickbrowser

integer

Optional

Indicates the type of browser opened upon clicking the creative in an app, where 0 = embedded, 1 = native. Note that the Safari View Controller in iOS 9.x devices is considered a native browser for purposes of this attribute.

secure

integer

Optional

Flag to indicate if the impression requires secure HTTPS URL creative assets and markup, where 0 = non-secure, 1 = secure. If omitted, the secure state is unknown, but non-secure HTTP support can be assumed.

rwdd

integer; default 0

Optional

Indicates whether the user receives a reward for viewing the ad, where 0 = no, 1 = yes. Refer to 4.3 Rewarded Adsfor all means to signal rewarded inventory.

ssai

integer; default 0

Optional

Indicates if server-side ad insertion (e.g., stitching an ad into an audio or video stream) is in use and the impact of this on asset and tracker retrieval, where 0 = status unknown, 1 = all client-side (i.e., not server-side), 2 = assets stitched server-side but tracking pixels fired client-side, 3 = all server-side.

exp

integer

Recommended

Advisory as to the number of seconds that may elapse between the auction and the actual impression.

dt

float

Optional

Timestamp when the item is estimated to be fulfilled (e.g. when a DOOH impression will be displayed) in Unix format (i.e., milliseconds since the epoch).

ext

object

Optional

Placeholder for exchange-specific extensions to OpenRTB.

ext.gpid

string

Recommended

Global Placement ID (cf. The TradeDesk's doc).

ext.rewarded

integer

Optional

Indicates whether the user receives a reward for viewing the ad, where 0 = no, 1 = yes. Refer to 4.3 Rewarded Adsfor all means to signal rewarded inventory.

ext.is_rewarded_inventory

integer

Optional

Indicates whether the user receives a reward for viewing the ad, where 0 = no, 1 = yes. Refer to 4.3 Rewarded Adsfor all means to signal rewarded inventory.

est.skadn

object

Recommended for Apple mobile Operating systems

If a DSP has at least one SKAdNetworkItem in the publisher app’s Info.plist we would include a new object in the bid request that provides the necessary information to create a signature. Object would only be present if the OS version (iOS 14.0+) supports SKAdNetwork. Refer to IAB Community Extensions docs for more information and our section below.

3.5 `banner` object

Field

Type

Required

Description

format

object array

Recommended

Array of format objects representing the banner sizes permitted. If none are specified, then use of the h and w attributes is highly recommended.

w

integer

Recommended if no format

Exact width in device-independent pixels (DIPS); recommended if no Format objects are specified.

h

integer

Recommended if no format

Exact height in device-independent pixels (DIPS); recommended if no Format objects are specified.

btype

integer array

Optional

Blocked banner ad types. Values: 1 = XHTML Text Ad, 2 = XHTML Banner Ad, 3 = JavaScript Ad, 4 = iframe.

battr

integer array

Optional

Blocked creative attributes. Refer to List: Creative Attributes in AdCOM 1.0. A maximum of 50 attributes can be specified.

pos

integer

Optional

Ad position on screen. Refer to List: Placement Positions in AdCOM 1.0.

mimes

string array

Optional

Content MIME types supported. Popular MIME types may include “image/jpeg” and “image/gif”.

topframe

integer

Optional

Indicates if the banner is in the top frame as opposed to an iframe, where 0 = no, 1 = yes.

expdir

integer array

Optional

Directions in which the banner may expand. Refer to List: Expandable Directions in AdCOM 1.0.

api

integer array

Recommended

List of supported API frameworks for this impression. Refer to List: API Frameworks in AdCOM 1.0. If an API is not explicitly listed, it is assumed not to be supported. Defaults to [1.0] unless both imp.ext.omidpn and imp.ext.omidpv are missing, in which case api is removed (cf. 4.2 Open Measurement (OMID))

id

string

Recommended if used with video as companion

Unique identifier for this banner object. Recommended when Banner objects are used with a Video object (Section 3.6 video object) to represent an array of companion ads. Values usually start at 1 and increase with each object; should be unique within an impression.

vcm

integer

Optional

Relevant only for Banner objects used with a Video object (Section 3.6 video object) in an array of companion ads. Indicates the companion banner rendering mode relative to the associated video, where 0 = concurrent, 1 = end-card.

ext

object

Optional

Placeholder for exchange-specific extensions to OpenRTB.

3.6 `video` object

Attribute

Type

Required

Description

mimes

string array

Required

Content MIME types supported (e.g., "video/mp4"). When omitted, Adagio will fallback to ["video/mp4","video/webm"].

minduration

integer; default 1

Recommended

Minimum video ad duration in seconds. This field is mutually exclusive with rqddurs; only one of minduration and rqddurs may be in a bid request.

maxduration

integer; default 100

Recommended

Maximum video ad duration in seconds. This field is mutually exclusive with rqddurs; only one of maxduration and rqddurs may be in a bid request.

startdelay

integer; default 0

Recommended

Indicates the start delay in seconds for pre-roll, mid-roll, or post-roll ad placements. Refer to List: Start Delay Modes in AdCOM 1.0.

protocols

integer array

Recommended

Array of supported video protocols. Refer to List: Creative Substypes - Audio/Video in AdCOM 1.0.

w

integer

Recommended

Width of the video player in device-independent pixels (DIPS).

h

integer

Recommended

Height of the video player in device-independent pixels (DIPS).

placement

integer; DEPRECATED

Deprecated

Video placement type for the impression. Refer to Section 5.9 of oRTB 2.5 specs. Deprecated as of OpenRTB 2.6-202303. Use plcmt instead.

plcmt

integer

Recommended

Video placement type for the impression. Refer to List: Plcmt Subtypes - Video in AdCOM 1.0.

linearity

integer

Optional (Recommended if linearity = 1)

Indicates if the impression must be linear, nonlinear, etc. If none specified, assume all are allowed. Refer to List: Linearity Modes in AdCOM 1.0. Note that this field describes the expected VAST response and not whether a placement is in-stream, out-stream, etc. For that, see plcmt.

skip

integer

Optional

Indicates if the player will allow the video to be skipped, where 0 = no, 1 = yes. If a bidder sends markup/creative that is itself skippable, the Bid object should include the attr array with an element of 16 indicating skippable video. Refer to List: Creative Attributes in AdCOM 1.0.

skipmin

integer; default 0

Optional

Videos of total duration greater than this number of seconds can be skippable; only applicable if the ad is skippable.

skipafter

integer; default 0

Optional

Number of seconds a video must play before skipping is enabled; only applicable if the ad is skippable.

sequence

integer; default 0 DEPRECATED

Deprecated

Deprecated as of OpenRTB 2.6. Use slotinpod

battr

integer array

Optional

Blocked creative attributes. Refer to List: Creative Attributes in AdCOM 1.0.

maxextended

integer

Optional

Maximum extended ad duration if extension is allowed. If blank or 0, extension is not allowed. If -1, extension is allowed, and there is no time limit imposed. If greater than 0, then the value represents the number of seconds of extended play supported beyond the maxduration value.

minbitrate

integer

Optional

Minimum bit rate in Kbps (kilobits per second). Default is 10 if not defined in the request.

maxbitrate

integer

Optional

Maximum bit rate in Kbps (kilobits per second). Default is 3000 is not defined in the request

boxingallowed

integer; default 1

Optional

Indicates if letter-boxing of 4:3 content into a 16:9 window is allowed, where 0=no, 1=yes.

playbackmethod

integer array

Optional

Playback methods that may be in use. If none are specified, any method may be used. Refer to List: Playback Methods in AdCOM 1.0. Only one method is typically used in practice. As a result, this array may be converted to an integer in a future version of the specification. It is strongly advised to use only the first element of this array in preparation for this change.

playbackend

integer

Optional

The event that causes playback to end. Refer to List: Playback Cessation Modes in AdCOM 1.0.

delivery

integer array

Optional

Supported delivery methods (e.g., streaming, progressive). If none specified, assume all are supported. Refer to List: Delivery Methods in AdCOM 1.0.

pos

integer

Optional

Ad position on screen. Refer to List: Placement Positions in AdCOM 1.0.

companionad

object array

Optional

Array of banner objec ts if companion ads are available.

api

integer array

Recommended

List of supported API frameworks for this impression. Refer to List: API Frameworks in AdCOM 1.0. If an API is not explicitly listed, it is assumed not to be supported. Defaults to [1.0] unless both imp.ext.omidpn and imp.ext.omidpv are missing, in which case api is removed (cf. 4.2 Open Measurement (OMID))

companiontype

integer array

Recommended if companionad not empty

Supported VAST companion ad types. Refer to List: Companion Types in AdCOM 1.0. Recommended if companion Banner objects are included via the companionad array. If one of these banners will be rendered as an end-card, this can be specified using the vcm attribute with the particular banner (Section 3.2.6).

ext

object

Optional

Placeholder for exchange-specific extensions to OpenRTB.

ext.rewarded

integer

Optional

Indicates whether the user receives a reward for viewing the ad, where 0 = no, 1 = yes. Refer to 4.3 Rewarded Adsfor all means to signal rewarded inventory.

ext.is_rewarded

integer

Optional

Indicates whether the user receives a reward for viewing the ad, where 0 = no, 1 = yes. Refer to 4.3 Rewarded Adsfor all means to signal rewarded inventory.

ext.videotype

string

Optional

Indicates whether the user receives a reward for viewing the ad, when set to "rewarded". Refer to 4.3 Rewarded Adsfor all means to signal rewarded inventory.

ext.placementtype

string

Optional

Indicates whether the user receives a reward for viewing the ad, when set to "rewarded". Refer to 4.3 Rewarded Adsfor all means to signal rewarded inventory.

3.7 `native` object

FIeld

Type

Required

Description

request

string

Required

Request payload complying with the Native Ad Specification. The root node of the payload, "native", was dropped in the Native Ads Specification 1.1. For Native 1.0, this is a JSON-encoded string consisting of a unnamed root object, with a single subordinate object named 'native', which is the Native Markup Request object, section 4.1 of OpenRTB Native 1.0 specification. For Native 1.1 and higher, this is a JSON-encoded string consisting of an unnamed root object which is itself the Native Markup Request Object, section 4.1 of OpenRTB Native 1.1+ .

ver

string

Recommended

Version of the Dynamic Native Ads API to which request complies; highly recommended for efficient parsing.

api

integer array

Recommended

List of supported API frameworks for this impression. Refer to List: API Frameworks in AdCOM. If an API is not explicitly listed, it is assumed not to be supported. Defaults to [1.0] unless both imp.ext.omidpn and imp.ext.omidpv are missing, in which case api is removed (cf. 4.2 Open Measurement (OMID)).

battr

integer array

Optional

Blocked creative attributes. Refer to List: Creative Attributes in AdCOM.

ext

object

Optional

Placeholder for exchange-specific extensions to OpenRTB.

3.8 `format` object

It is recommended that either the w/h pair or the wratio/hratio/wmin set (i.e., for Flex Ads) be specified.

Field

Type

Description

w

integer

Width in device-independent pixels (DIPS).

h

integer

Height in device-independent pixels (DIPS).

wratio

integer

Relative width when expressing size as a ratio.

hratio

integer

Relative height when expressing size as a ratio.

wmin

integer

The minimum width in device-independent pixels (DIPS) at which the ad will be displayed the size is expressed as a ratio.

ext

object

Placeholder for exchange-specific extensions to OpenRTB.

3.9 `app` object

Attribute

Type

Required

Description

id

string

Recommended

Exchange-specific app ID.

name

string

Optional

App name.

bundle

string

Required

The store ID of the app in an app store. For mobile apps in Google Play Store, these should be bundle or package names (e.g. com.foo.mygame). For apps in Apple App Store, these should be a numeric ID (e.g. 324684580).

domain

string

Recommended

Domain of the app developer (e.g., "mygame.foo.com") on which the app-ads.txt can be found.

storeurl

string

Recommended

App store URL for an installed app; for IQG 2.1 compliance.

cattax

integer; default 1

Optional

The taxonomy in use. Refer to the AdCOM List: Category Taxonomies for values. Values other than 1 are strongly discouraged, please contact your CSM if you use them.

cat

string array

Recommended

Array of IAB Tech Lab content categories of the app. The taxonomy to be used is defined by the cattax field. If no cattax field is supplied Content Category Taxonomy 1.0 is assumed.

sectioncat

string array

Optional

Array of IAB Tech Lab content categories that describe the current section of the app. The taxonomy to be used is defined by the cattax field.

pagecat

string array

Optional

Array of IAB Tech Lab content categories that describe the current page or view of the app. The taxonomy to be used is defined by the cattax field.

ver

string

Recommended

Application version.

privacypolicy

integer

Recommended

Indicates if the app has a privacy policy, where 0 = no, 1 = yes.

paid

integer

Recommended

0 = app is free, 1 = the app is a paid version.

publisher

object

Required

Details about the Publisher of the app. See publisher object.

content

object

Optional

Details about the Content within the app. See content object.

keywords

string

Optional

Comma separated list of keywords about the app. Only one of keywords or kwarray may be present.

kwarray

string array

Optional

Array of keywords about the app. Only one of keywords or kwarray may be present.

inventorypartnerdomain

string

Optional

A domain to be used for inventory authorization in the case of inventory sharing arrangements between an app owner and content owner. This field is typically used by authorization crawlers to establish the domain of the content owner, who has the right to monetize some portion of ad inventory within the app. The content owner's domain should be listed in the app owner's app-ads.txt file as an inventorypartnerdomain. Authorization for supply from the inventorypartnerdomain will be published in the ads.txt file on the root of that domain. Refer to the ads.txt 1.1 spec for more details.

ext

object

Recommended

Placeholder for exchange-specific extensions to OpenRTB.

ext.category

string

Recommended

Category of the content displayed in the page.

ext.pagetype

string

Recommended

Describes what kind of content will be present in the page.

3.10 `publisher` object

FIeld

Type

Required

Description

id

string

Recommended

Exchange-specific seller ID. Every ID must map to only a single entity that is paid for inventory transacted via that ID. Corresponds to a seller_id of a seller in the exchange’s sellers.json file.

name

string

Optional

Seller name

cattax

integer; default 1

Optional

The taxonomy in use. Refer to the AdCOM List: Category Taxonomies for values.

cat

string array

Optional

Array of IAB Tech Lab content categories of the publisher. The taxonomy to be used is defined by the cattax field. If no cattax field is supplied Content Category Taxonomy 1.0 is assumed.

domain

string

Optional

Highest level domain of the seller (e.g., "seller.com").

ext

object

Optional

Placeholder for exchange-specific extensions to OpenRTB.

3.11 `content` object

field

Type

Description

id

string

Publisher-provided ID uniquely identifying the content.

episode

integer

Episode number.

title

string

Content title. Video Examples: “Search Committee” (television), “A New Hope” (movie), or “Endgame” (made for web). Non-Video Example: “Why an Antarctic Glacier Is Melting So Quickly” (Time magazine article).

series

string

Content series. Video Examples: “The Office” (television), “Star Wars” (movie), or “Arby ‘N’ The Chief” (made for web). Non-Video Example: “Ecocentric” (Time Magazine blog).

season

string

Content season (e.g., “Season 3”).

artist

string

Artist credited with the content.

genre

string

Genre that best describes the content (e.g., rock, pop, etc).

gtax

int; default 9

The taxonomy in use. Refer to list List: Category Taxonomies in AdCOM 1.0 for values. If no gtax field is supplied rows listed, Content Category Taxonomy 3.1 is assumed

genres

string array

Unique ID(s) for the genre of the content as listed in the taxonomy defined by the gtax field. If no gtax field is supplied, subset of rows listed in CTV Genre Mapping of Content Category Taxonomy 3.1 are assumed. See Section 7.13 of Implementation Guidance for additional detail.

album

string

Album to which the content belongs; typically for audio.

isrc

string

International Standard Recording Code conforming to ISO- 3901.

producer

object

Refer to official documentation for more information

url

string

URL of the content, for buy-side contextualization or review.

cattax

integer; default 1

The taxonomy in use. Refer to list List: Category Taxonomies in AdCOM 1.0 for values.

cat

string array

Array of IAB Tech Lab content categories that describe the content. The taxonomy to be used is defined by the cattax field. If no cattax field is supplied Content Category Taxonomy 1.0 is assumed.

prodq

integer

Production quality. Refer to List: Production Qualities in AdCOM 1.0.

context

integer

Type of content (game, video, text, etc.). Refer to List: Content Contexts in AdCOM 1.0.

contentrating

string

Content rating (e.g., MPAA).

userrating

string

User rating of the content (e.g., number of stars, likes, etc.).

qagmediarating

integer

Media rating per IQG guidelines. Refer to List: Media Ratings in AdCOM 1.0.

keywords

string

Comma separated list of keywords describing the content. Only one of keywords or kwarray may be present.

kwarray

string array

Array of keywords about the content. Only one of keywords or kwarray may be present.

livestream

integer

0 = not live, 1 = content is live (e.g., stream, live blog).

sourcerelationship

integer

0 = indirect, 1 = direct.

len

integer

Length of content in seconds; appropriate for video or audio.

language

string

Content language using ISO-639-1-alpha-2. Only one of language or langb should be present.

langb

string

Content language using IETF BCP 47. Only one of language or langb should be present.

embeddable

integer

Indicator of whether the content is embeddable (e.g., an embeddable video player), where 0 = no, 1 = yes.

data

object array

Additional content data. Each Data object (refer to IAB Section 3.2.21) represents a different data source.

network

object

Details about the network (refer to IAB Section 3.2.23) the content is on.

channel

object

Details about the channel (refer to IAB Section 3.2.24) the content is on.

ext

object

Placeholder for exchange-specific extensions to OpenRTB.

3.12 `device` object

Field

Type

Required

Description

geo

object

Recommended

Location of the device assumed to be the user’s current location defined by a Geo object

dnt

integer

Recommended

Standard “Do Not Track” flag as set in the header by the browser, where 0 = tracking is unrestricted, 1 = do not track.

lmt

integer

Recommended

“Limit Ad Tracking” signal commercially endorsed (e.g., iOS, Android), where 0 = tracking is unrestricted, 1 = tracking must be limited per commercial guidelines.

ua

string

Recommended

Browser user agent string. This field represents a raw user agent string from the browser. If present, sua will be preferred by bidders.

sua

object

Recommended

Structured user agent information defined by a UserAgent object. If both ua and sua are present in the bid request, sua should be considered the more accurate representation of the device attributes. Refer to official documentation for more information.

ip

string

Recommended

IPv4 address closest to device.

ipv6

string

IPv6 address closest to device.

devicetype

integer

Recommended

The general type of device. Refer to List: Device Types in AdCOM 1.0.

make

string

Recommended

Device make (e.g., “Apple”).

model

string

Recommended

Device model (e.g., “iPhone”).

os

string

Recommended

Device operating system (e.g., “iOS”).

osv

string

Recommended

Device operating system version (e.g., “3.1.2”).

hwv

string

Recommended

Hardware version of the device (e.g., “5S” for iPhone 5S).

h

integer

Recommended

Physical height of the screen in pixels.

w

integer

Recommended

Physical width of the screen in pixels.

ppi

integer

Screen size as pixels per linear inch.

pxratio

float

Recommended

The ratio of physical pixels to device-independent pixels (DIPS).

js

integer

Recommended

Support for JavaScript, where 0 = no, 1 = yes.

geofetch

integer

Optional

Indicates if the geolocation API will be available to JavaScript code running in the banner, where 0 = no, 1 = yes.

flashver

string

Optional

Version of Flash supported by the browser.

language

string

Recommended

Browser language using ISO-639-1-alpha-2. Only one of language or langb should be present.

langb

string

Recommended

Browser language using IETF BCP 47. Only one of language or langb should be present.

carrier

string

Recommended

Carrier or ISP (e.g., “VERIZON”) using exchange curated string names which should be published to bidders a priori.

mccmnc

string

Optional

Mobile carrier as the concatenated MCC-MNC code (e.g., “310-005” identifies Verizon Wireless CDMA in the USA). Refer to https://en.wikipedia.org/wiki/Mobile_country_code for further examples. Note that the dash between the MCC and MNC parts is required to remove parsing ambiguity. The MCC-MNC values represent the SIM installed on the device and do not change when a device is roaming. Roaming may be inferred by a combination of the MCC-MNC, geo, IP and other data signals.

connectiontype

integer

Recommended

Network connection type. Refer to List: Connection Types in AdCOM 1.0.

ifa

string

Recommended

ID sanctioned for advertiser use in the clear (i.e., not hashed) and must never be (or be based on) a hardware-specific ID but rather obtained from a call to an advertising API provided by the device's OS.

ext

object

Required See ext.ifa_type

Placeholder for exchange-specific extensions to OpenRTB.

ext.ifa_type

string

Required if ifa present

Identify the source of the IFA (cf. oRTB docs for possible values)

3.13 `geo` object

Attribute

Type

Required

Description

lat

float

Recommended

Latitude from -90.0 to +90.0, where negative is south.

lon

float

Recommended

Longitude from -180.0 to +180.0, where negative is west.

type

integer

Recommended if lat/long present

Source of location data; recommended when passing lat/lon. Refer to List: Location Types in AdCOM 1.0. When type = 2, it's highly recommended to also set ipservice.

accuracy

integer

Recommended if lat/long present and type = 1

Estimated location accuracy in meters. Note that this is the accuracy as reported from the device. Consult OS specific documentation (e.g., Android, iOS) for exact interpretation.

lastfix

integer

Optional

Number of seconds since this geolocation fix was established. Note that devices may cache location data across multiple fetches. Ideally, this value should be from the time the actual fix was taken.

ipservice

integer

Recommended if lat/long present and type = 2

Service or provider used to determine geolocation from IP address if applicable (i.e., type = 2). Refer to List: IP Location Services in AdCOM 1.0.

country

string

Recommended if lat/long omitted

Country code using ISO-3166-1-alpha-3.

region

string

Recommended if lat/long omitted

Region code using ISO-3166-2; 2-letter state code if USA.

regionfips104

string

Optional

Region of a country using FIPS 10-4 notation. While OpenRTB supports this attribute, it was withdrawn by NIST in 2008.

metro

string

Optional

Google metro code; similar to but not exactly Nielsen DMAs.

city

string

Recommended if lat/long omitted

City using United Nations Code for Trade & Transport Locations. Refer to UNECE documentation.

zip

string

Optional

ZIP or postal code.

utcoffset

integer

Optional

Local time as the number +/- of minutes from UTC.

ext

object

Optional

Placeholder for exchange-specific extensions to OpenRTB.

3.14 `user` object

Field

Type

Required

Description

buyeruid

string

Optional

Buyer-specific ID for the user as mapped by the exchange for the buyer. Shouldn't be applicable to App traffic given the absence of cookie based userID syncs.

keywords

string

Optional

Comma separated list of keywords, interests, or intent. Only one of keywords or kwarray may be present.

kwarray

string array

Optional

Array of keywords about the user. Only one of keywords or kwarray may be present.

customdata

string

Optional

Optional feature to pass bidder data that was set in the exchange’s cookie. Shouldn't be applicable to App traffic given the absence of cookie based userID syncs.

geo

object

Optional

Location of the user’s home base defined by a Geo object (Section 3.2.19). This is not necessarily their current location.

data

object array

Optional

Additional user data. Each Data object (Refer to IAB Section 3.2.21) represents a different data source.

consent or ext.consent

string

Required if regs.gdpr or regs.ext.gdpr = 1

When GDPR regulations are in effect this attribute contains the Transparency and Consent Framework’s Consent String data structure.

eids or ext.eids

object array

Recommended

Standardized way to carry external identity signals across the ad ecosystem. Refer toServer-to-Server (S2S) Calls

ext

object

cf. above consent and eids

Placeholder for exchange-specific extensions to OpenRTB.

4. Supported Extensions

4.1 External IDs (EIDs)

External IDs (EIDs) allow DSPs to recognize users across different supply sources, improving match rates, bid relevance, and overall revenue performance.

We support the transmission of any EIDs within the user.eids or user.ext.eids object of your OpenRTB bid request, such as UID2.0, Ramp ID, ID5, and others.

Be sure to include the following parameters in your eids:

source (string)
uids[].id (string)
uids[].atype (int)

"user": {
  "ext": {
  "eids": [
    {
      "source": "x-device-vendor-x.com",
      "uids": [
        {
          "id": "yyy",
          "atype": 1
        }
      ]
    }
  ]
}

"user": {
  "eids": [
    {
      "source": "x-device-vendor-x.com",
      "uids": [
        {
          "id": "yyy",
          "atype": 1
        }
      ]
    }
  ]
}

4.2 Open Measurement (OMID)

Supporting OMID not only ensures compliance with industry standards but also increases the likelihood of receiving bids and achieving stronger monetization, as it is considered a mark of quality and transparency by buyers. Buyers prioritise publishers who provide the SDK as it increass their confidence that the campaigns will be seen and engaged with by real users.

The Open Measurement SDK (OMID), standardized by the IAB Tech Lab, enables reliable ad verification and viewability measurement across web and in-app environments. To declare OMID compatibility in an OpenRTB request, specific fields must be included to indicate the OM API support, the SDK partner name, and the SDK version in use.

imp[].api = 7
source.ext.omidpn (string): OM SDK partner name.
source.ext.omidpv (string): OM SDK version.

4.3 Rewarded Ads

Rewarded ads provide users with in-app incentives (such as extra lives, currency, or premium content) in exchange for viewing a full ad.

Adagio supports any of these approaches (backwards compatibility) to ensure proper recognition of rewarded placements, maximizing eligibility for bids and improving monetization:

Supported Rewarded Ads signals

bidrequest.imp[].rwdd = 1

bidrequest.imp[].video.ext.rewarded = 1

bidrequest.imp[].video.ext.is_rewarded = 1

bidrequest.imp[].video.ext.videotype = "rewarded"

bidrequest.imp[].video.ext.placementtype = "rewarded"

bidrequest.imp[].ext.rewarded = 1

bidrequest.imp[].ext.is_rewarded_inventory = 1

bidrequest.ext.placementtype = "rewarded"

4.4 Supported Currencies

Adagio uses exchange rates from the European Central Bank to perform currency conversions. Below the list of currencies supported in Bid Requests and Bid Responses:

List of currencies supported in Bid Requests and Bid Responses

Symbol

Country

Name

AUD

🇦🇺

Australian Dollar

BGN

🇧🇬

Bulgarian Lev

BRL

🇧🇷

Brazilian Real

CAD

🇨🇦

Canadian Dollar

CHF

🇨🇭

Swiss Franc

CNY

🇨🇳

Chinese Yuan Renminbi

CZK

🇨🇿

Czech Koruna

DKK

🇩🇰

Danish Krone

GBP

🇬🇧

British Pound Sterling

HKD

🇭🇰

Hong Kong Dollar

HUF

🇭🇺

Hungarian Forint

IDR

🇮🇩

Indonesian Rupiah

ILS

🇮🇱

Israeli Shekel

INR

🇮🇳

Indian Rupee

ISK

🇮🇸

Icelandic Krona

JPY

🇯🇵

Japanese Yen

KRW

🇰🇷

South Korean Won

MXN

🇲🇽

Mexican Peso

MYR

🇲🇾

Malaysian Ringgit

NOK

🇳🇴

Norwegian Krone

NZD

🇳🇿

New Zealand Dollar

PHP

🇵🇭

Philippine Peso

PLN

🇵🇱

Polish Zloty

RON

🇷🇴

Romanian Leu

SEK

🇸🇪

Swedish Krona

SGD

🇸🇬

Singapore Dollar

USD

🇺🇸

United States Dollar

THB

🇹🇭

Thai Baht

TRY

🇹🇷

Turkish Lira

ZAR

🇿🇦

South African Rand

4.5 SKAdNetwork for Apple Apps

Adagio supports the the documented community extension needed to use the SKAdNetwork capabilities in iOS 14+

Adagio is still investigating some optimisation around the use of this extension but:

Many demand partners have expressed the positive performance impact of including it in the bidstream
All of it's content is forwarded to demand partners as provided in the BidRequests

Buyers prioritize publishers who support SKAdNetwork because it enables their campaign performance monitoring measurement and therefore better target their ads and reduce fraud.

5. Adagio BidResponses

The BidResponse contains one or more SeatBids, each with Bids specifying creative details, price, and targeting. Mandatory fields must follow the OpenRTB spec, while optional fields can improve targeting, analytics, and performance with Adagio’s DSP partners.

Adagio populates as many fields as possible among those listed below. The actual content of each response depends on:

the information provided in the original ad request,
the data returned by bidders in their bid responses.

5.1 `bidresponse` object

Field

Type

Description

id

string

ID of the of the bidRequest to which this is a response

seatbid

array of objects

Array of seatbid objects; with at least 1 entry is a bid is to be made.

bidid

string

Bidder generated response ID to assist with logging/tracking.

cur

string; default "USD"

Bid currency. Refer to 4.4 Supported Currencies

nbr

integer

Reason for not bidding. Due to cost optimisation, Adagio uses HTML request's headers error codes instead of nbr codes in their body.

5.2 `seatbid` object

Field

Type

Description

seat

string

ID of the demand partner seat on Adagio's platform.

bid

array of objects

Array of bid objects for impressions.

5.3 `bid` object

Field

Type

Description

id

string

Bidder-generated bid ID.

impid

string

ID of the impression being bid on.

price

float

Bid price CPM in currency specified.

adm

string

Optional means of conveying ad markup (e.g., HTML, VAST XML) in case the bid wins; supersedes the win notice if markup is included in both. Substitution macros (Refer to IAB Section 4.4) may be included.

crid

string

Creative ID to assist with ad quality checking .

nurl

string

Win notice URL called by the exchange if the bid wins (not necessarily indicative of a delivered, viewed, or billable ad); optional means of serving ad markup. Substitution macros (Refer to IAB Section 4.4) may be included in both the URL and optionally returned markup.

burl

string

Billing notice URL called by the exchange when a winning bid becomes billable based on exchange-specific business policy (e.g., typically delivered, viewed, etc.). Substitution macros (Refer to IAB Section 4.4) may be included.

lurl

string

Loss notice URL called by the exchange when a bid is known to have been lost based on exchange-specific business policy (e.g., typically delivered, viewed, etc.). Substitution macros (Refer to IAB Section 4.4) may be included.

adid

string

ID of a preloaded ad to be served if the bid wins

bundle

string

App bundle or package name.

cat

string array

Creative IAB category. The taxonomy to be used is defined by the cattax field.

cattax

integer; default 1

The taxonomy in use. Refer to List: Category Taxonomies for values.

attr

integer array

Creative attributes.

language

string

Language of creative (ISO-639-1).

adomain

string array

Advertiser domain for block list checking (e.g., “ford.com”). This can be an array of for the case of rotating creatives.

apis

integer array

List of supported APIs for the markup. If an API is not explicitly listed, it is assumed to be unsupported. Refer to List: API Frameworks in AdCOM 1.0.

protocol

integer

Video response protocol of the markup if applicable. Refer to List: Creative Subtypes - Audio/Video in AdCOM 1.0.

exp

integer

Advisory as to the number of seconds the bidder is willing to wait between the auction and the actual impression. Violating this might result in ignored billable impression or IVT.

dur

integer

Duration of the video creative in seconds if applicable.

mtype

integer

Type of the creative markup so that it can properly be associated with the right sub-object of the BidRequest.Imp. Values: 1 = Banner 2 = Video, 3 = Audio 4 = Native

w

integer

Width of the creative in device-independent pixels (DIPS).

h

integer

Height of the creative in device-independent pixels (DIPS).

wratio

integer

Relative width of the creative when expressing size as a ratio.

hratio

integer

Relative height of the creative when expressing size as a ratio.

References

PreviousOpenRTB for Apps NextBid Request and Bid Response Examples

Last updated 18 hours ago

Was this helpful?

1. S2S Headers

1.1 OpenRTB Version

1.2 Endpoints Integrations

1.3 Data compression (Gzip)

2. Important oRTB parameters

2.1 Required parameters

2.2 Recommended parameters

3. Publisher's BidRequests

3.1 bidrequest object

3.2 source object

3.3 regs object

3.4 imp object

3.5 banner object

3.6 video object

3.7 native object

3.8 format object

3.9 app object

3.10 publisher object

3.11 content object

3.12 device object

3.13 geo object

3.14 user object

4. Supported Extensions

4.1 External IDs (EIDs)

4.2 Open Measurement (OMID)

4.3 Rewarded Ads

4.4 Supported Currencies

4.5 SKAdNetwork for Apple Apps

5. Adagio BidResponses

5.1 bidresponse object

5.2 seatbid object

5.3 bid object

References

3.1 `bidrequest` object

3.2 `source` object

3.3 `regs` object

3.4 `imp` object

3.5 `banner` object

3.6 `video` object

3.7 `native` object

3.8 `format` object

3.9 `app` object

3.10 `publisher` object

3.11 `content` object

3.12 `device` object

3.13 `geo` object

3.14 `user` object

5.1 `bidresponse` object

5.2 `seatbid` object

5.3 `bid` object