OpenRTB 3.0 and AdCOM Companion Specification
January 23, 2023
Executive Summary
The IAB Tech Lab Ad Management API specification is part of the OpenMedia specification suite.
Ad management occurs when a buyer (or a representative party) submits creatives for creative approval, supply platforms approve or disapprove of those creatives, and buyers receive feedback accordingly. Before the publication of this technical standard, supply platforms have relied on proprietary methods and tools for ad management, or none at all.
This process is important for a few reasons: to ensure creatives comply with content guidelines, are malware-free, and function correctly. Creative submission is also a technical necessity for certain emerging formats such as digital out-of-home (DOOH) and programmatic TV. In an ad quality review process, analysts or automated processes check the ad's landing page, tracking tags, text, the creative itself, and more. The exact nature of the review process is up to each supply platform. The results of these checks are made available for buying platforms to consume and modify bidding behavior accordingly.
The Programmatic Supply Chain Working Group has identified a need to standardize the creative submission and ad management process to reduce pain points for buyers and sellers in the digital advertising industry. Using a standard approach allows for ease of integration between buy-side and supply-side platforms. Supply platforms using the standardized Ad Management API gain increased control over the creatives that serve on their platforms. Both supply platforms and demand platforms benefit from increased bidding efficiency, as demand platforms can avoid invalid bids and notify customers of defects with their ads. This can unblock revenue that would otherwise be received if buyers knew that they must make adjustments. Submission of ads in advance also benefits all parties as it reduces approval delays that may exist with current workflows.
The Ad Management API specification support all major scenarios known at time of publication for both bidding and markup delivery. For bidding, this refers to whether supply platforms permit ads to serve by default ("permissive bidding") or require explicit approval before serving ("restrictive bidding"). For markup delivery, this refers to whether the markup is included in each bid or whether bids refer to pre-uploaded markup by ID.
About IAB Tech Lab
The IAB Technology Laboratory is a nonprofit research and development consortium charged with producing and helping companies implement global industry technical standards and solutions. The goal of the Tech Lab is to reduce friction associated with the digital advertising and marketing supply chain while contributing to the safe growth of an industry. The IAB Tech Lab spearheads the development of technical standards, creates and maintains a code library to assist in rapid, cost-effective implementation of IAB standards, and establishes a test platform for companies to evaluate the compatibility of their technology solutions with IAB standards, which for 18 years have been the foundation for interoperability and profitable growth in the digital advertising supply chain.
Learn more about IAB Tech Lab here: https://www.iabtechlab.com/
Original Author of the Ad Management API Specification Proposal
Ian Trider, VP, RTB Platform Operations, Basis and IAB Tech Lab Commit Group Member
IAB Tech Lab Programmatic Supply Chain Commit Group Members https://iabtechlab.com/working-groups/programmatic-supply-chain-commit-group/
IAB Tech Lab Programmatic Supply Chain Working Group Members
https://iabtechlab.com/working-groups/programmatic-supply-chain-working-group/
IAB Tech Lab Contact
For more information, or to get involved, please email support@iabtechlab.com.
Contributors and Technical Governance
Programmatic Supply Chain Working Group members provide contributions to this repository. Participants in the Programmatic Supply Working group must be members of IAB Tech Lab. Technical Governance and code commits for the project are provided by the IAB Tech Lab Programmatic Supply Chain Commit Group.
Learn more about how to submit changes in our working group: So, You'd Like to Propose a Change...
License OpenRTB Specification the IAB Tech Lab is licensed under a Creative Commons Attribution 3.0 License. To view a copy of this license, visit creativecommons.org/licenses/by/3.0/ or write to Creative Commons, 171 Second Street, Suite 300, San Francisco, CA 94105, USA.
Disclaimer THE STANDARDS, THE SPECIFICATIONS, THE MEASUREMENT GUIDELINES, AND ANY OTHER MATERIALS OR SERVICES PROVIDED TO OR USED BY YOU HEREUNDER (THE “PRODUCTS AND SERVICES”) ARE PROVIDED “AS IS” AND “AS AVAILABLE,” AND IAB TECHNOLOGY LABORATORY, INC. (“TECH LAB”) MAKES NO WARRANTY WITH RESPECT TO THE SAME AND HEREBY DISCLAIMS ANY AND ALL EXPRESS, IMPLIED, OR STATUTORY WARRANTIES, INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AVAILABILITY, ERROR-FREE OR UNINTERRUPTED OPERATION, AND ANY WARRANTIES ARISING FROM A COURSE OF DEALING, COURSE OF PERFORMANCE, OR USAGE OF TRADE. TO THE EXTENT THAT TECH LAB MAY NOT AS A MATTER OF APPLICABLE LAW DISCLAIM ANY IMPLIED WARRANTY, THE SCOPE AND DURATION OF SUCH WARRANTY WILL BE THE MINIMUM PERMITTED UNDER SUCH LAW. THE PRODUCTS AND SERVICES DO NOT CONSTITUTE BUSINESS OR LEGAL ADVICE. TECH LAB DOES NOT WARRANT THAT THE PRODUCTS AND SERVICES PROVIDED TO OR USED BY YOU HEREUNDER SHALL CAUSE YOU AND/OR YOUR PRODUCTS OR SERVICES TO BE IN COMPLIANCE WITH ANY APPLICABLE LAWS, REGULATIONS, OR SELF-REGULATORY FRAMEWORKS, AND YOU ARE SOLELY RESPONSIBLE FOR COMPLIANCE WITH THE SAME, INCLUDING, BUT NOT LIMITED TO, DATA PROTECTION LAWS, SUCH AS THE PERSONAL INFORMATION PROTECTION AND ELECTRONIC DOCUMENTS ACT (CANADA), THE DATA PROTECTION DIRECTIVE (EU), THE E-PRIVACY DIRECTIVE (EU), THE GENERAL DATA PROTECTION REGULATION (EU), AND THE E-PRIVACY REGULATION (EU) AS AND WHEN THEY BECOME EFFECTIVE.
- Introduction and Background
- API Conventions
- Endpoints
- Authentication
- Resource Representations
- Webhooks
- Expiration
- Requesting Re-Audit
- Substitution Macros
- Typical Synchronization Flow
- Appendix A: Integration Checklist
- Appendix B: Examples
- Appendix C: API Pagination
- Appendix D: Resources
- Appendix E: Change Log
- Appendix F: Errata
The purpose of this specification is to provide a standardized means for demand and supply partners to communicate with each other regarding ads that will be used in bidding. The specification provides for a RESTful API to be implemented by supply partners.
Exchanges have vastly different policies with regards to creatives, and this specification makes no attempt to enforce any set of business rules. Rather, such rules are a matter for bidders and exchanges to communicate with each other as a part of integration. The terms "required", "recommended", and "optional" in this specification refer only to technical compliance, not business policy. Likewise, "must" and "will" refer to requirements for a technically compliant implementation.
Wherever possible, this specification makes reference to OpenRTB as it is assumed this is the standard "common language" of bidding that will be used between exchanges and bidders. While the most common expected use case is that of a DSP interacting with an ad exchange, the OpenRTB Ad Management API is not limited to this purpose and can be used to transmit ad and audit information between partners in more complex supply chains. Wherever the term "bidder" is used, this should be understood to mean more generically "demand partner", and wherever the term "exchange" is used, this should be understood to mean more generically "supply partner." For example, an ad network may have a server-to-server integration with an ad exchange to source demand. In this case, the ad network is the supply partner and the exchange is the demand partner.
This specification makes use of AdCOM 1.x for the definition of the Ad object and its children.
This specification is not inherently constrained to partners who use OpenRTB during bidding. In fact, this specification is also suitable for management of ads used in non-biddable transactions as well. While this specification is released as a part of the OpenRTB 3.0 framework, implementation of OpenRTB 3.0 is not required to use this specification. It can easily be used alongside OpenRTB 2.x bidding implementations.
NOTE: Out of convenience, this specification will refer to some shorthand terms for expected common scenarios. These are outlined in the following two sections.
In a permissive bidding scenario, the exchange allows a new ad to win impressions until (and if) a point in time occurs at which the ad is deemed to be disapproved. Bidders are expected to stop bidding with disapproved ads, and exchange may discard bid responses using such a creative.
In a restrictive bidding scenario, the exchange does not allow new ads to win impressions until (and if) a point in time occurs at which the ad is deemed to be approved. Exchanges may discard bids made using such a ad until approval.
An exchange using restrictive bidding may choose to allow new ads to enter its audit queue by simply having the bidder start bidding with such an ad ("submission via bidding"), however bids may be discarded by the exchange until it is approved. Submission via bidding allows bidders to participate in auctions even if they have not implemented support for this API, however optimal performance is ensured by doing so.
In this scenario, the bidder is expected to include the markup/URL for an ad (along with its ID) in each bid response.
The ad submitted by the bidder using this API is expected to be a faithful example of creative markup that behaves in a way that is representative of markup that will be used during bidding. It is expected that the exact markup will vary (for example, there will be varying components for an impression tracking URL, cachebusters, click URL, product IDs and images in dynamic creative, etc.). It is up to exchanges to communicate which deviations used during bidding will be deemed to constitute a material change to the creative (and thus may trigger a change in audit status).
In this scenario, the exchange holds the ad markup. During bidding, the bidder makes reference to the markup on file using the "mid" field in the Bid object in the bid response (OpenRTB v3.x) or similar (non-OpenRTB or previous versions) and does not include the actual markup. The exchange provides a means for the bidder to specify custom macros in the markup for which values will be provided at bid time, so that variable components of the markup (impression tracking URLs, cachebusters, click URLs, etc.) may be substituted.
Note that "ad markup" refers to merely the contents of the adm field (for display ads) or similar (e.g. VAST); typically, such markup will contain references to third-party servers for assets, etc.
NOTE: It is expected that exchanges will make clear to their demand partners as a matter of exchange policy whether permissive or restrictive bidding in place and whether bidders should return markup in bid responses or whether exchange-hosted ad markup applies.
There are a number of reasons why this specification was created. Consider the following sets of scenarios that exist for exchanges:
In this scenario, there is an absolute need for an ad management API. This need is currently being filled by proprietary APIs, and DSPs must implement multiple proprietary specs to do business.
In this scenario, when exchanges use "submission via bidding" there is an artificial delay before ads can start to spend -- they are often quarantined and bids for a given ad ID are disallowed from bidding until they have been reviewed by the exchange. The result is that money is "left on the table" while waiting for the audit to clear, campaigns do not begin on time, and (if the exchange and/or bidder is unable or unwilling to implement multiple bids in bid responses) bids are submitted that will be discarded, resulting in opportunity loss as the bidder may have had other viable bids for ads that are already approved. As a result, the rate of discarded bids can grow to be extremely high resulting in significant revenue loss.
The presence of a proprietary ad management API avoids the pitfalls of submission via bidding, but requires costly engineering resources, requiring demand partners to maintain multiple implementations for each exchange.
This pattern is the most common among exchanges today. However, there are still problems that an ad management API helps rectify. It is not unusual for an exchange to block certain ad IDs platform-wide as a violation of their ad quality policy or due to technical reasons. This information is not communicated to the bidder, which continues to bid with an ad that will not be accepted. If the exchange and/or bidder is unable or unwilling to implement multiple bids in bid responses, there is a great deal of potential revenue that is lost due to bids being filtered. This is particularly noteworthy with video, where technical problems with ads occur commonly, and as a result, exchanges implement blocks on defective ads. An ad management API makes it possible for the exchange to provide feedback to the bidder which it can incorporate to modify its bidding (e.g. discontinue bidding with ad IDs that the exchange has deemed to be unacceptable).
New formats are emerging that are beginning to be transactable via real-time bidding. Particularly, digital out-of-home and programmatic TV are here or on the near horizon. These new formats often have stringent ad approval requirements that necessitate an API.
This API adheres to many of the conventions of RESTful APIs. The base protocol used for communication is HTTPS, and JSON is used to represent the body of requests and responses. Requests should be made with an HTTP headers of "Accept: application/json" and "Content-Type: application/json" to indicate that the body of the request will be JSON and that JSON is expected in return. Compression may also be negotiated/used as indicated by HTTP headers (see OpenRTB 3.0 for an example of how this is done).
Breaking changes are restricted to major versions of this specification (1.x, 2.x, etc.).
Almost all fields are optional at a technical level, however exchanges may mandate the presence of certain fields as a business requirement. Both exchanges and bidders must gracefully deal with the presence of unexpected or unknown fields. Exchanges are recommended to store fields regardless of their relevance to the exchange, as they may hold significance to a bidder. For example, on exchanges which use their own ad IDs, bidders may wish to store their ID in the extension object.
It is expected that a given exchange operates using either it's own ad IDs or bidder IDs, but not both, for the prevention of ambiguity.
All requests must result in the manipulated object(s) being returned in response.
HTTP status codes are used by the exchange to express the status of requests made by the bidder:
| Code | Name | Description |
|---|---|---|
| 200 | OK | The request was successful. |
| 400 | Bad Request | The request could not be interpreted successfully. |
| 401 | Unauthorized | The request did not contain correct authentication information. |
| 404 | Not Found | The resource does not exist. |
| 429 | Too Many Requests | The bidder has exceeded the rate limit set by the exchange and must wait before trying again. |
| 500 | Internal Service Error | The exchange has encountered technical difficulties. |
AdCOM objects returned in responses may contain a sparse fieldset to save bandwidth, where this specification indicates this is acceptable (see "Endpoints" below). In this case fields should be assumed by bidders to be unchanged if not present. Bidders can determine changes made by an exchange by comparing to the object it previously sent. Sparse fieldsets must include at a minimum the following fields, if the object in question is sent:
- Ad object
- id
- init (initial ad creation only)
- lastmod
- Audit object
- status
- lastmod
All dates/times must be specified in the format of millis since Unix epoch (January 1, 1970 00:00:00 UTC). If an implementer internally uses a more precise timestamp, values should always be rounded down to the nearest millisecond to so that when queries are made using a filter, ads are not missed due to rounding.
Bidders will interact with the Ad Management API by making HTTP calls to specific endpoints. Exchanges will specify a base URL (denoted using the {baseUrl} placeholder in this document) and a bidder ID representing a given bidder/demand partner (denoted using the {bidderId} placeholder in this document). All endpoints are relative to this base URL. The base URL must include the major version of the specification implemented in the form of "v#". For example, an exchange implementing version 1.1 of this API may define its base URL as https://api.exchange.com/management/v1. For example, assuming a bidder ID of 492 the ads endpoint will be reached at https://api.exchange.com/management/v1/bidder/492/ads.
Per "API Conventions" above, breaking changes require the major version number to be iterated, and partners must deal gracefully with unexpected fields, so the minor version number is not required in the URL and its omission provide ease of upgrade.
| Endpoint | Methods supported | Description |
|---|---|---|
| {baseUrl}/bidder/{bidderId}/ads | GET, POST | GET: returns a collection of ads for a given bidder. This response may be sparse at the exchange's discretion (see "API conventions"). An "auditStart" filter, at a minimum, must be set on the query string to constrain the number of ads returned, else exchanges may choose to return a 400 status code. Exchanges may limit the number of ads in the returned collection at their discretion. If the result set is a subset of available ads, this will be indicated in the result (see "Collection of ads"). Bidders may fetch the remaining ads by calling the URL included in the "nextPage" field, repeating until the bidder has gathered all updates. The available filters are: auditStart: Timestamp, based on "lastmod" value from the Audit object of returned ads, used as the starting point for pagination. See Appendix C: API Pagination for more details. (Required). See API conventions regarding date format and Appendix D: Pagination for details about correctly implementing pagination and using the "auditStart" and "id" fields. Example:
POST: submits a single ad. The body must contain a only an Ad object (and its children). Returns a collection of ads containing the ad submitted, including any fields or child objects provided by the exchange. This response may be sparse at the exchange's discretion (see "API conventions"). |
| {baseUrl}/bidder/{bidderId}/ads/{id} | GET, PUT, PATCH | GET: Returns a collection of ads resource containing a single ad in its entirety. PUT: replaces the ad object in its' entirety, and returns a collection of ads containing the specified ad, including any fields or child objects provided by the exchange. This response may be sparse at the exchange's discretion (see "API conventions"). PATCH: replaces only the specified fields, and returns a collection of ads containing the specified ad, including any fields or child objects provided by the exchange. This response may be sparse at the exchange's discretion (see "API conventions"). |
In this version of the Ad Management API, authentication protocol is left to the discretion of the exchange or SSP implementing the API, and should be discussed with API users a priori.
Resources are represented using JSON.
A collection of ads is an object containing one or more ads with additional metadata.
| Attribute | Type | Description |
|---|---|---|
| count | integer | The number of ads in this collection. |
| more | integer | A boolean flag indicating that this collection is a subset; the number of ads returned has been limited by exchange policy. See "Endpoints" above. May be omitted when not needed. |
| nextPage | string | A URL for the next page of results when "more" is true, null (or not present) otherwise. See API Pagination above for details. E.g. `https://{baseUrl}/bidder/{bidderId}/ads?auditStart=1528221114000&paginationId=421` |
| ads | object array | An array of ad resources. On GET, sorted by oldest to newest date of "lastmod" from the Audit object. |
An ad resource is an object representing each unique ad that will be used by the bidder. It is a AdCOM 1.x ad object with relevant child objects. See the AdCOM specification for details.
Only the bidder may modify the ad object and its' children, excepting the Audit object and these fields from the Ad object:
-
"id": Set by the exchange (only for exchanges who express ads in terms of their IDs)
-
"init": Set by the exchange on initial submission of the ad
-
"lastmod": Set by the exchange on the most recently modification to the ad
Subordinate to the Ad object is a AdCOM 1.x audit object. See the AdCOM specification for details. Among the many objects that may be present subordinate to the Ad object, it is specifically noted in this specification because its behaviour in the context of ad management is worth elaborating on.
Only the exchange may modify the audit object. Upon initial ad upload, the exchange must initialize the "init" and "lastmod" field to the timestamp of the submission of the ad. The "lastmod" field must be updated at any change of this object.
Exchanges may choose to support sending webhook calls to bidders to notify them of changes to ad audit status, and bidders may choose to receive such calls.
It is recommended to use webhooks as a means of reducing the required polling frequency substantially. Bidders should still poll occasionally to ensure that all changes are collected (to account for failures during webhook calls, etc.), but at a much lower frequency (such as once per day).
In this version of the Ad Management API, the method of registration of a webhook URL and authentication protocol is left to the discretion of the exchange or SSP implementing the API. These matters should be discussed with API users a priori.
If an exchange supports webhooks and the exchange and the bidder have arranged to enable webhook calls, the exchange will POST a collection of ads to the bidder's webhook URL upon status change for an ad or ad(s). The JSON in the POST may be sparse, containing only changes. The bidder must respond 204 No Content if the webhook is successfully processed. In the event of failures such as timeouts, non-2xx status codes, etc., it is recommended the exchange make at least 3 further attempts with a delay of 30 seconds between each request before abandoning the attempt. It is recommended that exchanges record permanent failures for offline analysis.
Exchanges may not wish to maintain a record of Ads indefinitely. Accordingly, the idea of "expiration" is supported. Expiration is an audit status that signals that the exchange is due to delete the Ad in future if no action is taken.
The following are to be decided by the exchange, but must be communicated a priori to bidders:
- The criteria for when an Ad's audit status becomes "expired"
- The criteria for when an Ad is deleted
- Whether Ads with an audit status of "expired" may bid or not
Typically, these criteria will be in the form of days, e.g. an exchange may define a policy like:
- Ad expiration: 30 days of inactivity
- Ad deletion: 120 days after expiry
- Expired ad bidding policy: Bidders must explicitly re-activate an ad (or, alternatively, bidding triggers re-activation)
If exchanges require explicit re-activation of expired ads, bidders may do so by touching the ad; a PUT or a PATCH against the ad constitutes a touch.
Whether such re-activated ads can be immediately used or must go through another audit is a matter of exchange policy, and bidders should consult the audit status in the Ad object in the response to the PUT/PATCH request.
Bidders may request that exchanges re-audit ads with an audit status of 4 (Denied) or 5 (Changed; Resubmission Requested) by touching the ad; a PUT or a PATCH against the ad constitutes a touch. Bidders should not request re-audit of ads without addressing the audit feedback returned by exchanges.
Whether exchanges permit re-audit requests for a given ad (or any ads) is a matter of exchange policy; should an exchange refuse such a request, the audit status in the Ad object in the response to the PUT/PATCH request should be left unchanged.
In the "exchange-hosted ad markup", since bidders do not include their ad markup in the bid response, the exchange must provide the facility for custom macros so that the bidder can provide any variable details (such as cachebusters, impression ID, product IDs, etc.) needed to serve the ad. These custom macros are substituted by the exchange when serving. The strings which may be used are addressed by the transaction specification used for bidding, for example OpenRTB 3.0.
The values for these custom macros are supplied by the bidder during bidding.
Authentication is not shown here for brevity.
As ads are created, the bidder places the ads into a queue for submission. The bidder makes one or more HTTP POST calls to:
{baseUrl}/bidder/{bidderId}/ads
... with a body containing a single Ad resource. Exchanges will periodically update the audit object inside the ad with modifications to the status (e.g. to set ads as approved or denied), and any other fields as a result of the exchange's assessment of the ad. Bidders should expect that that fields in the audit object could change at any time.
As ads change audit status, the exchange makes HTTP POST calls to pre-arranged bidder webhook URL, with each call containing a collection of ads (one or more).
Bidders may also choose to periodically poll for updates (thereby preventing missed information if webhook calls fail) by making HTTP GET calls to:
{baseUrl}/bidder/{bidderId}/ads?auditStart={timestamp}
Bidders should record the audit "lastmod" for each ad, and choose an auditStart value based on the most recently observed audit update timestamp.
Alternatively, bidders may query for the status of a particular ad by making an HTTP GET call to:
{baseUrl}/bidder/{bidderId}/ads/{id}
Bidders should make use of the information they receive to change their bidding behaviour appropriately.
If the bidder has made local changes to an ad, the bidder makes an HTTP PATCH or PUT call to:
{baseUrl}/bidder/{bidderId}/ads/{id}
... to update the ad record at the exchange. On an exchange with restrictive bidding, typically, this would result in the ad returning to status 1, "pending audit", but this is a matter of exchange business rules. For example, an exchange might deem only a subset of changes to be significant enough to require a re-audit (such as a change in landing page domain). It is up to exchanges to communicate what deviations constitute a material change to the ad (and thus may trigger a change in audit status).
To facilitate integration, exchanges should provide a document similar to the below to inform bidders about the specifics of an exchange's implementation of this spec.
| Exchange | |
|---|---|
| Base URL | |
| Bidder ID | |
| Version Used | |
| Rate Limit | |
| Max Ads per Response | |
| Markup and Bidding Policy | |
| Ad Retention Policy | (Days to expiry, days to deletion, bidding behaviour for expired ads |
| Ad IDs of Record | (Bidder or Exchange) |
| Attributes Required | |
| Notes | Additional notes of relevance regarding this implementation. |
| Exchange | SuperAds |
|---|---|
| Base URL | https://api.superads.com/management/v1 |
| Bidder ID | 496 |
| Version Used | v1.1 |
| Rate Limit | 100 requests per minute |
| Max Ads per Response | 100 |
| Markup and Bidding Policy | Permissive bidding, ad markup in bid response |
| Ad Retention Policy | Ads expire after 14 days of inactivity and are deleted after 30 days in expired status. Expired ads may be used in bidding and will be automatically re-activated. |
| Ad IDs of Record | Bidder |
| Attributes Required | Required in Ad object: adomain, iurl, one of display or video Required in Display object: w, h |
This exchange is not interested in receiving the markup itself, merely a representative inspection image ('iurl') to be reviewed by auditors. This is representative of the situation on some mobile exchanges at time of publication.
NOTE: Such an implementation would not provide the option for the exchange to scan markup for malicious content. While the API supports such an implementation, a more sophisticated implementation is recommended.
POST https://api.superads.com/management/v1/bidder/496/ads
{
"id": "557391",
"adomain": "advertiser.com",
"iurl": "http://cdn.dsp.com/iurls/557391.gif",
"display": {
"w": 300,
"h": 250
}
}Response:
{
"count": 1,
"ads": [
{
"id": "557391",
"init": 1528221112000,
"lastmod": 1528221112000,
"audit": {
"status": 2,
"lastmod": 1528221112000
}
}
]
}In this case, notifying it that an ad has been disapproved.
POST {hookurl}
{
"count": 1,
"ads": [
{
"id": "557391",
"lastmod": 1528221112000,
"audit": {
"status": 4,
"feedback": "Content disallowed by exchange policy.",
"lastmod": 1528288587000
}
}
]
}The bidder is requesting all ads whose status has changed since the most recent audit status change observed on last poll (for this example, timestamp 1528282813000). In this example, there are more ads that have changed than the maximum the exchange will return in a single call. The bidder follows the URL provided in "nextPage" to get the next page of results.
GET https://api.superads.com/management/v1/bidder/496/ads?auditStart=1528282813000
{
"count": 100,
"more": 1,
"nextPage": "https://api.superads.com/management/v1/bidder/496/ads?auditStart=1528306991000&paginationId=557398",
"ads": [
{
"id": "557391",
"lastmod": 1528221112000,
"audit": {
"status": 4,
"feedback": "Content disallowed by exchange policy.",
"lastmod": 1528288587000
}
},
{
"id": "557533",
"lastmod": 1528289509000,
"audit": {
"status": 3,
"lastmod": 1528289509000
}
},
{ ... },
{
"id": "557398",
"lastmod": 1528222962000,
"audit": {
"status": 3,
"lastmod": 1528306991000
}
}
]
}GET https://api.superads.com/management/v1/bidder/496/ads?auditStart=1528306991000&paginationId=557398
{
"count": 2,
"more": 0,
"ads": [
{
"id": "557231",
"lastmod": 1528227434000,
"audit": {
"status": 4,
"feedback": "Content disallowed by exchange policy.",
"lastmod": 1528307136000
}
},
{
"id": "557599",
"lastmod": 1528042889000,
"audit": {
"status": 3,
"lastmod": 1528307223000
}
}
]
}As this is the last page of results, "nextPage" is not included by the exchange and "more" is 0.
| Exchange | AdvancedAds |
|---|---|
| Base URL | https://api.advancedads.com/admgmt/v1 |
| Bidder ID | 34 |
| Version Used | v1.1 |
| Rate Limit | 100 requests per minute |
| Max Ads per Response | 100 |
| Markup and Bidding Policy | Restrictive bidding, ad markup in bid response |
| Ad Retention Policy | Ads expire after 14 days of inactivity and are deleted after 30 days in expired status. Bidders must explicitly re-activate expired ads. |
| Ad IDs of Record | Bidder |
| Attributes Required | Required in Ad: adomain, cat, one of display or video Required in Display: one of adm or banner, one of w + h or wratio + hratio, type Required in Banner: img, link Required in Video: one of adm or curl, api, mime, type |
POST https://api.advancedads.com/admgmt/v1/bidder/34/ads
{
"id": "557391",
"cat": "653",
"adomain": "ford.com",
"display": {
"w": 300,
"h": 250,
"secure": 1,
"adm": "<!-- Markup -->"
}
}Response:
{
"count": 1,
"ads": [
{
"id": "557391",
"init": 1528221112000,
"lastmod": 1528221112000,
"audit": {
"status": 1,
"lastmod": 1528221112000
}
}
]
}Given the bidding policy of the exchange and the initial audit status returned, the bidder cannot use this ad in bidding until it receives an update to the audit status.
GET https://api.advancedads.com/admgmt/v1/bidder/34/ads?auditStart=1528282813000
{
"count": 4,
"more": 0,
"ads": [
{ ... },
{
"id": "557391",
"lastmod": 1528221112000,
"audit": {
"status": 3,
"feedback": "Corrected category. Added missing attribute.",
"corr": {
"cat": "1",
"attr": 6
},
"lastmod": 1528288587000
}
}
]
}In the above scenario, the exchange has approved the ad but has updated it to reflect that, in the its opinion, the ad should be classified as category Automotive, and has auto-play in-banner video. The equivalent webhook call would be similar (see above example).
The bidder may find an ad to have an audit status of 6 (Expired) either upon polling for changes or through a webhook call. Given the policy of this exchange, such an ad is not eligible for bidding. If the bidder wishes to use the ad again, it can simply touch the ad to trigger its re-activation.
PATCH https://api.advancedads.com/admgmt/v1/bidder/34/ads/557391
{}Response:
{
"count": 1,
"ads": [
{
"id": "557391",
"init": 1528221112000,
"lastmod": 1529052323000,
"audit": {
"status": 1,
"lastmod": 1529052323000
}
}
]
}When it comes to implementing pagination, there are subtleties that implementers must consider to ensure correct implementation, otherwise an infinite loop or missing ads could occur.
In order to address this, Ad Management API uses a timestamp + ID pattern similar to that described here. The beginning timestamp for ads returned in the collection of ads is given by the "auditStart" query parameter. This timestamp is based on "lastmod" from the Audit object of the ads. The "paginationId" query parameter is the beginning ID for ads returned, and is used for fetching subsequent pages.
The following needs to be covered to ensure correct implementation:
- The collection of ads returned for each page does not contain records repeated from the prior page (unless the timestamp for last modification has changed since the last request)
- No ads are skipped even if there is an identical timestamp for multiple ads.
- Ads returned in a collection of ads must be sorted by the "lastmod" timestamp ascending and the "paginationId" ascending, in that order.
-
- While examples here use numeric values for "paginationId", this is not required. For example, in a given integration between a DSP and exchange, the DSP's ad IDs might be used, and these might be alphanumeric strings. All that is essential is that sort is consistent.
- When only "auditStart" is specified for the request, any ads with a "lastmod" greater than the specified timestamp will be returned (up to the maximum of number of ads an exchange is willing to return per page).
- When "auditStart" and "paginationId" are both specified for the request, any ads with a) "lastmod" equal to the specified timestamp and "paginationId" greater than the specified ID or b) "lastmod" greater than the specified timestamp will be returned (up to the exchange's maximum per page).
Interactive Advertising Bureau Technology Laboratory (IAB Tech Lab)
www.iabtechlab.com
OpenMedia Specification Stack
https://iabtechlab.com/openmedia
AdCOM Project on Github
https://github.com/InteractiveAdvertisingBureau/AdCOM
OpenRTB v3.0 Specification
https://github.com/InteractiveAdvertisingBureau/openrtb
This appendix serves as a brief summary of changes to the specification. These changes pertain only to the substance of the specification and not routine document formatting, information organization, or content without technical impact. For that, see Appendix F: Errata.
| Version | Changes |
| 1.1 | Enhanced pagination: As specified in v1.0, an infinite loop could occur while attempting to paginate through results. This could occur if there were more ads with an identical last modification timestamp than an exchange will return per page. To address this, non-breaking enhancements have been added for a more sophisticated approach to pagination. |
| 1.0 | Initial release. |
This appendix catalogues any error corrections which have been made to this document after its versioned release. The body of the document has been updated accordingly.
Only minor fixes, such as clarifications or corrections to descriptions, may be treated as errata. Improvements or material changes are summarized in the change log.
Granular details of the changes can be seen by reviewing the commit history of the document.
There are no errata at this time.