Skip to content

Bid Responses


The maximum size of the bid response is 4KB.

No Bids

To communicate a no-bid response, pass an empty response with a status code of 204.

Win/Loss/Billing Notifications

AppLovin RTB calls the win, loss, and billing notice URLs that the requester supplies in the request’s nurl, lurl, and burl fields respectively. AppLovin RTB calls the win URL when the auction completes and AppLovin sends the ad to the device. It calls the loss URL either during the auction, if the associated ad fails to load properly, or after a different winning ad loads. It calls the billing URL when the device renders the ad—that is, when the video starts playing, or, for graphic ads, when the device displays the ad.

The requester may embed macros into the specification of these notification URLs. AppLovin RTB substitutes appropriate values for those macros in the URL before AppLovin RTB requests the URL. The following list shows the macros that the requester may embed in these URLs:

These macros are case-sensitive; specify them in ALL CAPS. Enclose these macros in ${…} (e.g. ${AUCTION_ID}).

AUCTION_BID_IDID of the bid, from the BidResponse.bidid attribute.
AUCTION_IDID of the bid request, from the attribute.
AUCTION_LOSSLoss reason code, as found in Table 5.25 of the OpenRTB 2.5 spec. Only sent on lurl. Note that loss code “103 Lost to a Bid for a PMP Deal” is used when the impression is won by a Direct Sold campaign at a higher priority.
AUCTION_MINIMUM_BID_TO_WINSecond highest bid price. If there is no winner, floor price is sent. Is only sent on nurl. Value passed is 0 when there is only one bid: the winning bid.
AUCTION_PRICEThe auction clearing price. Uses the same currency and units as the bid. May be up to six decimals.

Example Win Bid URL with Macros${AUCTION_ID}&price=${AUCTION_PRICE}

Ad Markup Standard

DSP bidders must include ad markup in the bid response. AppLovin RTB does not support returning the ad markup in response to the win notice.

Your ad markup must comply with AppLovin’s RTB ad markup standard. AppLovin’s RTB servers check the ad markup’s compliance as soon as they receive the bid. Then they perform the following sanity checks on the ad markup:

  • Ad markup is properly escaped.
  • Ad markup is URL-encoded, except for VAST ads.
  • HTML of the ad markup is a snippet.
  • When you bid with a rich media ad, put the content of the node in a CDATA construct. CDATA in XML requires no encoding whatsoever. However if you pass an XML document in a JSON-context, you must apply JSON syntax and escaping rules, as follows:
    • All double quotes are escaped as \".
    • Apostrophes are not escaped.
    • The XML doc is stripped of all tab and newline characters. (The Example VAST Ad Markup below is formatted for easy readability. Do not send extra whitespace in your actual ad markup.)

To verify that an ad markup snippet is valid JSON content (along with its CDATA), you can pass that snippet into the on-line JSONLint validator.

SDK bidders are not required to pass ad markup because all creatives should be rendered via your SDK. SDK bidders may use the admarkup field to pass custom data, which can be configured to be returned to your SDK at load time via the adapters.

Bid Response Components

There are three components to the bid response:

top-level object
collection of bids made by the bidder on behalf of a specific seat
an offer to buy a specific impression under certain business terms

Bid Response Object

bididstringBidder-generated response ID to assist with logging/
curstringCurrently only accepts, and defaults to, "USD".no
idstringID of the bid request to which this is a response (this must match
nbrintegerReason for not bidding. Refer to List 5.24 of the OpenRTB 2.5 spec.recommended
seatbidobject arrayArray of seatbid objects. One or more are required if a bid is to be made.yes

Seatbid Object

bidobject arrayArray of bid objects; one or more are required if a bid is to be made.yes
seatstringID of the bidder seat on whose behalf this bid is made. A bid response may contain bids from multiple “seats” or contain multiple bids from the same seat. Must be an alphanumeric string, maximum 40 characters, ideally minimum 8 characters. Not currently

Bid Object

adid (string)ID of a preloaded ad to be served if the bid
adm (string)The main means of conveying ad markup in case the bid wins. Supersedes the win notice if markup is included in both. Substitution macros may be included. Refer to supported macros. For native ad format adm_native is supported.yes
adomain (string array)An array of advertiser domain names. AppLovin RTB uses only the first domain in the array. Advertiser domains must match the top-level domain name for the advertiser landing page, not the full landing page URL. For app store landing pages, adomain should match the app owner’s top-level domain name, not the full app store URL. The value of adomain must not contain “http://”, “https://”, or any “/” (slash) characters. Example: (but not or
api (integer)See OpenRTB Spec 2.5 Table
apis (integer array)List of supported API frameworks for this impression. One of the following:
  • 1—VPAID1.0*
  • 2—VPAID2.0*
  • 3—MRAID-1
  • 4—ORMMA*
  • 5—MRAID-2
  • 6—MRAID-3
  • 7—OMID-1
* not supported on ALX
attr (integer array)Required when applicable. Creative attributes, an array of values taken from this list:
  • 1—Audio Ad (Auto-Play)
  • 2—Audio Ad (User Initiated)
  • 3—Expandable (Automatic)
  • 4—Expandable (User Initiated–Click)
  • 5—Expandable (User Initiated–Rollover)
  • 6—In-Banner Video Ad (Auto-Play)
  • 7—In-Banner Video Ad (User Initiated)
  • 8—Pop (e.g. Over, Under, or Upon Exit)
  • 9—Provocative or Suggestive Imagery
  • 10—Shaky, Flashing, Flickering, Extreme Animation, Smileys
  • 11—Surveys
  • 12—Text Only
  • 13—User Interactive (e.g. Embedded Games)
  • 14—Windows Dialog or Alert Style
  • 15—Has Audio On/Off Button
  • 16—Ad Provides Skip Button (e.g.VPAID-rendered skip button on pre-roll video)
  • 17—Adobe Flash
When present, this must be accurate and reflect the actual creative, otherwise it is a policy violation. This field is not required for serving VAST video but is required for serving HTML or MRAID in-banner video.
bundle (string)The advertiser’s application iTunes ID or Android package name. If this is not an application install ad, leave this field blank. Do not pass the publisher’s application bundle or AppLovin RTB will reject the response.Examples: on Android, 628677149 on iOS.required if ext.skadn is present; recommended in all cases
burl (string)Billing notice URL called by the exchange when a winning bid becomes billable. DSPs must use burl for impression and spend tracking. AppLovin only investigates discrepancies when burl is used for tracking.yes
cat (string array)IAB content categories of the creative. Refer to section 5.1 of the OpenRTB 2.5 spec.yes
cid (string)Campaign ID to assist with ad quality checking. The collection of creatives for which iurl should be representative.recommended
crid (string)Uniquely identifies a creative for a campaign. Do not assign a new creative ID to the same creative just to indicate that the creative is appearing in a new impression.yes
dealid (string)Reference to the from the bid request if this bid pertains to an inventory package. Do not pass unless bidding against an inventory package.yes, for inventory packages
ext (object)Placeholder for bidder-specific extensions to
ext.crtype (string)This field describes the type of ad you are serving. Valid values are:
  • HTML
  • MRAID 1.0
  • MRAID 2.0
  • MRAID 3.0
  • native
  • VAST 2.0
  • VAST 3.0
  • VAST 4.0
  • VAST 4.1
  • VAST 4.2
AppLovin can hardcode the crtype for you if you buy only one crtype. Contact your AppLovin account manager if you would like to do this. Passing crtype in bid.crtype is also supported.
ext.clicktrackers (string array)Click tracking URLs (first- and third-party) to be consistently tracked when AppLovin records the click event. This does not apply to native.yes, if running HTML ads + SKAD (SKAdNetwork)
ext.duration (integer)Video duration, in seconds.yes, for CTV inventory
ext.imptrackers (string array)Impression tracking URL to be used by third-party tracking needs. This does not apply for native. See native object
ext.skadn (object)Parameters required to support Apple’s SKAdNetwork attribution API, via loadProduct().no
ext.skadn.campaign (string)Campaign ID (2.0–3.0) or Source ID (4.0+). This should be an integer between 1 and 100 for SKAdNetwork versions 2.0–3.0, or between 0 and 9999 for versions 4.0+, expressed as a string.if ext.skadn is present
ext.skadn.fidelities[] (object array)Supports multiple fidelity types introduced in SKAdNetwork v2.2.if ext.skadn is present
….fidelities[«n»].fidelity (integer)The fidelity-type of the attribution to track.if ext.skadn is present
….fidelities[«n»].nonce (string)An ID unique to each ad response. Refer to Apple’s documentation for the proper UUID format requirements.if ext.skadn is present
….fidelities[«n»].signature (string)SKAdNetwork signature as specified by Apple.if ext.skadn is present
….fidelities[«n»].timestamp (string)Unix time in milliseconds, string used at the time of signature.if ext.skadn is present
ext.skadn.itunesitem (string)ID of advertiser’s app in Apple’s app store. Should match ext.skadn is present (string)Ad network identifier used in signature. Should match one of the items in the skadnetids array in the request.if ext.skadn is present
ext.skadn.nonce (string)An ID unique to each ad response. Refer to Apple’s documentation for the proper UUID format requirements. Note: With the release of SKAdNetwork v2.2, this field is deprecated in favor of ext.skadn.fidelities[«n»].nonce which supports multiple fidelity-types.if ext.skadn is present
ext.skadn.productpage (string)Custom Product Page ID (available as of SDK 11.1.1).no
ext.skadn.signature (string)SKAdNetwork signature as specified by Apple. Note: With the release of SKAdNetwork 2.2, this field is deprecated in favor of ext.skadn.fidelities[«n»].signature which supports multiple fidelity-types.if ext.skadn is present
ext.skadn.skoverlay (object)Parameters to control a potential SKOverlay. The overlay can be triggered (with delay, or 0 for no delay) after video starts, companion ad renders, or user dismisses the overlay but the ad remains open. Note: AppLovin does not track clicks on SKOverlay, as Apple does not provide a click
….skoverlay.position (integer)Position of the overlay. 0 = bottom, 1 = bottomRaised. Defaults to
….skoverlay.dismissable (integer)Whether or not the user can dismiss the overlay (1 means it can be dismissed, 0 means it is static on the screen). Defaults to
….skoverlay.video_delay (integer)Number of seconds after the video starts to show the overlay. Keep this unset (null) to not trigger based on video
….skoverlay.companion_delay (integer)Number of seconds after the companion ad renders to show the overlay. Keep this unset (null) to not trigger based on companion ad render.if ext.skadn.skoverlay is present
….skoverlay.sk_dismiss_delay (integer)Number of seconds after the presented StoreKit screen is dismissed before showing the overlay. Keep this unset (null) to not trigger based on StoreKit dismiss (available as of SDK 11.3.4). if ext.skadn.skoverlay is present
ext.skadn.sourceapp (string)ID of publisher’s app in Apple’s app store. Should match BidRequest.imp.ext.skad.sourceapp.if ext.skadn is present
ext.skadn.timestamp (string)Unix time in milliseconds string used at the time of signature. Note: With the release of SKAdNetwork 2.2, this field is deprecated in favor of ext.skadn.fidelities[«n»].timestamp which supports multiple fidelity-types.if ext.skadn is present
ext.skadn.version (string)Version of SKAdNetwork desired. Must be 2.0 or above.if ext.skadn is present
ext.vendor (string array)Name of viewability vendor(s) that measure viewability for the ad that is shown. You should only declare viewability vendors in the bid response when you collect viewability measurement for an impression. Set to "ias" for Integral Ad Science (IAS). Set to "moat" for Moat. Buyers are required to respond with the vendor in the bid response when they return a display campaign for viewability. Does not apply to Open Measurement Viewability.for campaigns that measure viewability
h (integer)Height of the creative in density-independent pixels.recommended
id (string)Bidder-generated bid ID to assist with logging/tracking.yes
impid (string)ID of the Impression object in the related bid request.yes
lurl (string)Loss notice URL called by the exchange when a bid is known to be lost. Substitution macros may be included. Refer to supported
nurl (string)Win notice URL called by the exchange if the bid wins the impression opportunity.recommended
price (float)Bid price expressed as CPM, although the actual transaction is for a unit impression only. Note that while the type indicates float, integer math is highly recommended when handling currencies (for example, BigDecimal in Java).yes
protocol (integer)Video response protocol of the markup if applicable. See OpenRTB Spec 2.5 Table 5.8 for
w (integer)Width of the creative in density-independent pixels.recommended

Tracking Fields

The following table shows the tracking fields available to demand-side platforms, and their recommended uses. TrackerMethodRecommended Use
  • HTML Fired client-side
  • VAST<ImpressionTracker> node Fired server-side. X-Device-IP and X-Device-User-Agent are sent as headers in the server-to-server callbacks:
    Actual user device IP address
    Actual user device UA
  • HTML: Invalid Traffic (IVT) tracking
  • VAST: Impression tracking by partners
.adm.native.eventtrackersFired client-side
  • Invalid Traffic (IVT) tracking
  • Open Measurement SDK (OMSDK)
  • Impression tracking by partners
Supports img and js tags as defined in “methods” in 7.7 Event Tracking Methods Table of Open RTB 1.2 Native Ads Spec.DSPs are encouraged to use native.eventtrackers rather than native.imptrackers or native.jstracker as those fields are pending deprection by IAB (in favor of eventtrackers).
.adm.native.imptrackersFired client-side (deprecated in favor of eventtrackers)Invalid Traffic (IVT) tracking
.adm.native.jstrackerFired client-side (deprecated in favor of eventtrackers)Open Measurement SDK (OMSDK) client-sideClick tracking (optional)
.burlFired server-side. X-Device-IP and X-Device-User-Agent are sent as headers in the server-to-server callbacks:
Actual user device IP address
Actual user device UA
Impression and spend tracking for the buyer (DSP)
.ext.imptrackersFired server-side. X-Device-IP and X-Device-User-Agent are sent as headers in the server-to-server callbacks:
Actual user device IP address
Actual user device UA
Impression tracking by partners

Example Bid Response

"id": "5e1eb292d6b7ea9cf3da74ddb385996a62d3a6e9",
"seatbid": [
"bid": [
"id": "8JxH4DHN4KMF21Vd",
"impid": "1",
"price": 15,
"adid": "1093919",
"adm": "<a href=\"https://click.url/click/8JxH4DHN4KMF21Vd?uid=05D02DC6-0132-4C2C-A879-79BB026BE3F8&partner=applovin&ts=2018-07-09T18-19-01Z&ad=1093919\"><img src=\"\" height=\"50\" width=\"320\" alt=\"\"/></a>",
"adomain": [
"bundle": "123123123",
"iurl": "",
"cid": "12345",
"crid": "crid123",
"cat": [
"h": 50,
"w": 320,
"ext": {
"crtype": "HTML",
"imptrackers": [
"bidid": "8JxH4DHN4KMF21Vd",
"cur": "USD"

Example Native Ad Response

"adm":"{\"native\":{\"assets\":[{\"id\":100,\"title\":{\"text\":\"Test Ad\"}},{\"id\":200},{\"id\":300,\"img\":{\"h\":null,\"url\":\"\",\"w\":null}},{\"id\":310,\"img\":{\"h\":80,\"url\":\"\",\"w\":80}},{\"data\":{\"value\":\"Test Ad Subline\"},\"id\":420},{\"data\":{\"value\":\"Continue\"},\"id\":430},{\"data\":{\"value\":\"4.5\"},\"id\":410}],\"imptrackers\":[\"\"],\"link\":{\"url\":\"\"}}}\n",
"ext": {
"id": "1",
"impid": "1",
"iurl": "",
"price": 1.0