Serving an ad
Serves an ad based on the placement tag (tagid) and request payload (AdRequest).
Selects the most appropriate ad using campaign, creative, and bidding strategy data.
Returns the final ad determined through DSP response and internal mediation logic.
curl --request POST \
--url https://your_a2_service/app/v0/ad/{tagid} \
--header 'Content-Type: application/json' \
--data '{
"user": {
"gender": "M",
"id": "account-187acvbvz",
"yob": 1988
},
"version": "0.1.0"
}'
curl --request POST \
--url https://your_a2_service/app/v0/ad/{tagid} \
--header 'Content-Type: application/json' \
--data '
{
"version": "<string>",
"device": {
"ext": "<unknown>",
"geo": {
"accuracy": 123,
"city": "<string>",
"country": "<string>",
"ext": "<unknown>",
"ipservice": 1,
"lastfix": 1,
"lat": 123,
"lon": 123,
"metro": "<string>",
"region": "<string>",
"regionfips104": "<string>",
"type": 1,
"utcoffset": 123,
"zip": "<string>"
},
"ip": "<string>",
"ua": "<string>"
},
"user": {
"buyeruid": "<string>",
"ext": "<unknown>",
"gender": "M",
"geo": {
"accuracy": 123,
"city": "<string>",
"country": "<string>",
"ext": "<unknown>",
"ipservice": 1,
"lastfix": 1,
"lat": 123,
"lon": 123,
"metro": "<string>",
"region": "<string>",
"regionfips104": "<string>",
"type": 1,
"utcoffset": 123,
"zip": "<string>"
},
"id": "<string>",
"keywords": "<string>",
"yob": 1
}
}
'{
"ad": {
"display": {
"banner": {
"img": "https://example.com/image.jpg"
},
"h": 1024,
"w": 768
},
"id": "b56dc3bf-935d-4ee6-b1ed-f31bfc02be91"
},
"ext": {
"ad_log": "YTU2ZDY2ZjctNDM4ZS00OTVjLWJiYTAtMjI4Mzk2MjQ0ZWVkfDA2NDI4NjYwLWY2NDMtNGVmNS05MzgzLTZjZmE1OGYxOGI2OXxjNTZkYzNiZi05MzVkLTRlZTYtYjFlZC1mMzFiZmMwMmJlOTF8NGJlMmQ4ZTYtYThhMS00NzI2LWEzMjAtNjkyNTYzMDkwZTQyfDllZjY2ZGM4LTBlMmMtNDlmMS05NDU3LWFmYmUwZGQ2ZjU3M3w1NTgxNmIzOTcxMWY5YjVhY2YzYjkwZTMxM2VkMjllNTE2NjU2MjNm",
"message": "success"
},
"version": "0.1.0"
}Path Parameters
The ID of the placement.
Get from the advertising manager.
Body
AdRequest is used for requesting an ad.
AdRequest is used for requesting an ad.
Version of the SDK API.
Device object for the current ad request.
Show child attributes
Show child attributes
Placeholder for advertising-system specific extensions to this object
Location of the device assumed to be the user’s current location defined by a Geo object
Show child attributes
Show child attributes
1, 2, 3, 4 x >= 01, 2, 3 IPv4 address closest to device.
Browser user agent string. This field represents a raw user agent string from the browser. For backwards compatibility, exchanges are recommended to always populate ‘ua’ with the User-Agent string, when available from the end user’s device, even if an alternative representation, such as the User-Agent Client-Hints, is available and is used to populate ‘sua’. No inferred or approximated user agents are expected in this field. If a client supports User-Agent Client Hints, and ‘sua’ field is present, bidders are recommended to rely on ‘sua’ for detecting device type, browser type and version and other purposes that rely on the user agent information, and ignore ‘ua’ field. This is because the ‘ua’ may contain a frozen or reduced user agent string.
User object for the current ad request.
Show child attributes
Show child attributes
Buyer-specific ID for the user as mapped by the exchange for the buyer.
Placeholder for exchange-specific extensions to OpenRTB.
Gender, where “M” = male, “F” = female, “O” = known to be other (i.e., omitted is unknown).
M, F, O Location of the user’s home base defined by a Geo object (Section 3.2.19). This is not necessarily their current location.
Show child attributes
Show child attributes
1, 2, 3, 4 x >= 01, 2, 3 Exchange-specific ID for the user.
Comma separated list of keywords, interests, or intent. Only one of ‘keywords’ or ‘kwarray’ may be present.
Year of birth as a 4-digit integer.
x >= 0Response
Successfully served an ad
Version of the SDK API.
Ad object.
Show child attributes
Show child attributes
ID of the creative; unique at least throughout the scope of a vendor (e.g., an exchange or buying platform). Note that multiple instances of the same ad when used in transactions must have the same ID.
Array of content categories describing the ad using IDs from the taxonomy indicated in cattax. Implementer should ensure compliance with regional legislation around data usage and sharing.
The taxonomy in use for the cat attribute. Refer to List: Category Taxonomies.
IABTechLabAdProductTaxonomy1_0, IABTechLabAudienceTaxonomy1_1, IABTechLabContentCategoryTaxonomy2_1, IABTechLabContentCategoryTaxonomy2_2, IABTechLabContentCategoryTaxonomy3_0, IABTechLabAdProductTaxonomy2_0 Creative Subtype Object that indicates this is a display ad and provides additional detail as such.
Show child attributes
Show child attributes
VPAID1_0, VPAID2_0, MRAID1_0, ORMMA, MRAID2_0, MRAID3_0, OMID1_0, SIMID1_0, SIMID1_1 Structured banner image object for banner creatives.
Show child attributes
Show child attributes
This object identifies the native asset as a link asset and is used to define navigation for call-to-action or other activations (i.e., clicks). A link asset can be independent or associated with the overall native ad (i.e., a default for all assets).
HTML, AMPHTML, StructuredImageObject, StructuredNativeObject Show child attributes
Show child attributes
1, 2 1, 2, 3, 4, 5 VPAID1_0, VPAID2_0, MRAID1_0, ORMMA, MRAID2_0, MRAID3_0, OMID1_0, SIMID1_0, SIMID1_1 Optional A2-specific extensions.
Absolute height of the creative in device independent pixels (DIPS).
x >= 0x >= 0Mime type of the ad (e.g., “image/jpeg”).
Structured native object for native ads.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
This object identifies the native asset as a data asset. A data asset is used for all miscellaneous elements such as brand name, ratings, stars, review count, downloads, price, counts, etc. It is purposefully generic to support native elements not currently contemplated by this specification.
This object identifies the native asset as a image asset. Image assets are use for such elements as the actual creative images and icons.
Show child attributes
Show child attributes
x >= 01, 2, 3 x >= 0This object identifies the native asset as a link asset and is used to define navigation for call-to-action or other activations (i.e., clicks). A link asset can be independent or associated with the overall native ad (i.e., a default for all assets).
0, 1 This object identifies the native asset as a title asset, which is essentially just a plain text string with specified length.
This object identifies the native asset as a link asset and is used to define navigation for call-to-action or other activations (i.e., clicks). A link asset can be independent or associated with the overall native ad (i.e., a default for all assets).
Absolute width of the creative in device independent pixels (DIPS).
x >= 0x >= 0Optional A2 specific extensions.
URL without cache-busting to an image that is representative of the ad content for cursory level ad quality checking.
Language of the creative using ISO-639-1-alpha-2. In practice, vendors using this object may elect an alternate standard (e.g., BCP-47) in which case this must be communicated beforehand. The non-standard code “xx” may also be used if the creative has no linguistic content (e.g., a banner with just a company logo).
Creative Subtype Object that indicates this is a video ad and provides additional detail as such.
Show child attributes
Show child attributes
VPAID1_0, VPAID2_0, MRAID1_0, ORMMA, MRAID2_0, MRAID3_0, OMID1_0, SIMID1_0, SIMID1_1 VAST1_0, VAST2_0, VAST3_0, VAST1_0Wrapper, VAST2_0Wrapper, VAST3_0Wrapper, VAST4_0, VAST4_0Wrapper, DAAST1_0, DAAST1_0Wrapper, VAST4_1, VAST4_1Wrapper, VAST4_2, VAST4_2Wrapper x >= 0Error code if the request failed.
Optional A2 specific extensions.
Was this page helpful?
curl --request POST \
--url https://your_a2_service/app/v0/ad/{tagid} \
--header 'Content-Type: application/json' \
--data '
{
"version": "<string>",
"device": {
"ext": "<unknown>",
"geo": {
"accuracy": 123,
"city": "<string>",
"country": "<string>",
"ext": "<unknown>",
"ipservice": 1,
"lastfix": 1,
"lat": 123,
"lon": 123,
"metro": "<string>",
"region": "<string>",
"regionfips104": "<string>",
"type": 1,
"utcoffset": 123,
"zip": "<string>"
},
"ip": "<string>",
"ua": "<string>"
},
"user": {
"buyeruid": "<string>",
"ext": "<unknown>",
"gender": "M",
"geo": {
"accuracy": 123,
"city": "<string>",
"country": "<string>",
"ext": "<unknown>",
"ipservice": 1,
"lastfix": 1,
"lat": 123,
"lon": 123,
"metro": "<string>",
"region": "<string>",
"regionfips104": "<string>",
"type": 1,
"utcoffset": 123,
"zip": "<string>"
},
"id": "<string>",
"keywords": "<string>",
"yob": 1
}
}
'{
"ad": {
"display": {
"banner": {
"img": "https://example.com/image.jpg"
},
"h": 1024,
"w": 768
},
"id": "b56dc3bf-935d-4ee6-b1ed-f31bfc02be91"
},
"ext": {
"ad_log": "YTU2ZDY2ZjctNDM4ZS00OTVjLWJiYTAtMjI4Mzk2MjQ0ZWVkfDA2NDI4NjYwLWY2NDMtNGVmNS05MzgzLTZjZmE1OGYxOGI2OXxjNTZkYzNiZi05MzVkLTRlZTYtYjFlZC1mMzFiZmMwMmJlOTF8NGJlMmQ4ZTYtYThhMS00NzI2LWEzMjAtNjkyNTYzMDkwZTQyfDllZjY2ZGM4LTBlMmMtNDlmMS05NDU3LWFmYmUwZGQ2ZjU3M3w1NTgxNmIzOTcxMWY5YjVhY2YzYjkwZTMxM2VkMjllNTE2NjU2MjNm",
"message": "success"
},
"version": "0.1.0"
}