/
2.6.md
4267 lines (3712 loc) · 196 KB
/
2.6.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
# About the IAB Tech Lab <a name="techlab"></a>
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. Further details about the IAB Technology Lab can be found at www.iabtechlab.com
### Significant Contributors to the 2.6 version specification
Stanislav Belov, Software Engineer, Google; Allen Dove, CTO, Magnite; Steven Katz, Senior Principal Architect, Yahoo!; Curt Larson, Chief Product Officer, Sharethrough; Dr. Neal Richter, Director of Science, Amazon Advertising; Jud Spencer, Principal Software Engineer, The Trade Desk; Ian Trider, VP, RTB Platform Operations, Basis Technologies; Rob Hazan, Sr. Director Product Management, Index Exchange; James Wilhite, VP Product, Publica; Jean-Luc Wasmer, VP Partnership Operations, Triton Digital; Sam Mansour, Principle Product Manager, Oracle; Scott Kay, Engineering Manager, Xandr; Emma Fenlon, Sr. Manager, Exchange Quality, Yahoo!; Liam Whiteside, Head of Ad Technology, Global; Don Marti, VP Ecosystem Innovation, Café Media; Aron Schatz, Director Product Management, Double Verify; Jake Jolly, Product Manager, Google; Amit Shetty, VP Product, Pixalate; Tim Harvey, Founder, Knitting Media; Jason Shao, CTO, Place Exchange; Chris Coupland, Platform Operations Manager, Basis Technologies; Simon Trasler, SVP, Magnite;
### IAB Tech Lab Lead:
Hillary Slattery, Director of Product, IAB Tech Lab
### License <a name="license"></a>
This specification is licensed under a Creative Commons Attribution 3.0 License. To view a copy of this license, visit creativecommons.org/licenses/by/3.0/ http://creativecommons.org/licenses/by/3.0/ or write to Creative Commons, 171 Second Street, Suite 300, San Francisco, CA 94105, USA.
### Disclaimer <a name="disclaimer"></a>
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.
# TABLE OF CONTENTS
- [About the IAB Tech Lab](#techlab)
- [License](#license)
- [Disclaimer](#disclaimer)
## [Getting Started](#started)
## [1. Introduction](#intro)
- [1.1 - Mission / Overview](#mission)
- [1.2 - History of OpenRTB](#history)
- [1.3 - Version History](#versionhistory)
- [OpenRTB Real-Time Bidding API](#realtimebidding)
- [OpenRTB Display Block List Branch](#displayblock)
- [1.4 - Resources](#resources)
- [1.5 - Terminology](#terminology)
## [2. OpenRTB Basics](#rtbbasics)
- [2.1 - Transport](#transport)
- [2.2 - Security](#security)
- [2.3 - Data Format](#dataformat)
- [2.4 - Data Encoding](#dataencoding)
- [2.5 - OpenRTB Version HTTP Header](#httpheader)
- [2.6 - Versioning Behavior](#versioningbehavior)
- [2.7 - Privacy](#privacy)
- [2.8 - Relationship to Brand Safety Certified](#relationshiptocertified)
- [2.9 - Customization and Extensions](#customization)
## [3. Bid Request Specification](#bidspecification)
- [3.1 - Object Model](#objectmodel)
- [3.2 - Object Specifications](#objectspecs)
- [3.2.1 - Object: BidRequest](#objectbidrequest)
- [3.2.2 - Object: Source](#objectsource)
- [3.2.3 - Object: Regs](#objectregs)
- [3.2.4 - Object: Imp](#objectimp)
- [3.2.5 - Object: Metric](#objectmetric)
- [3.2.6 - Object: Banner](#objectbanner)
- [3.2.7 - Object: Video](#objectvideo)
- [3.2.8 - Object: Audio](#objectaudio)
- [3.2.9 - Object: Native](#objectnative)
- [3.2.10 - Object: Format](#objectformat)
- [3.2.11 - Object: Pmp](#objectpmp)
- [3.2.12 - Object: Deal](#objectdeal)
- [3.2.13 - Object: Site](#objectsite)
- [3.2.14 - Object: App](#objectapp)
- [3.2.15 - Object: Publisher](#objectpublisher)
- [3.2.16 - Object: Content](#objectcontent)
- [3.2.17 - Object: Producer](#objectproducer)
- [3.2.18 - Object: Device](#objectdevice)
- [3.2.19 - Object: Geo](#objectgeo)
- [3.2.20 - Object: User](#objectuser)
- [3.2.21 - Object: Data](#objectdata)
- [3.2.22 - Object: Segment](#objectsegment)
- [3.2.23 - Object: Network](#objectnetwork)
- [3.2.24 - Object: Channel](#objectchannel)
- [3.2.25 - Object: SupplyChain](#objectsupplychain)
- [3.2.26 - Object: SupplyChainNode](#objectsupplychainnode)
- [3.2.27 - Object: EID](#objecteid)
- [3.2.28 - Object: UID](#objectuid)
- [3.2.29 - Object: UserAgent](#objectuseragent)
- [3.2.30 - Object: BrandVersion](#objectbrandversion)
- [3.2.31 - Object: Qty](#objectqty)
- [3.2.32 - Object: DOOH](#objectdooh)
## [4. Bid Response Specification](#bidresponsespec)
- [4.1 - Object Model](#4.2objectmodel)
- [4.2 - Object Specifications](#objectspecs)
- [4.2.1 - Object: BidResponse](#objectbidresponse)
- [4.2.2 - Object: SeatBid](#objectseatbid)
- [4.2.3 - Object: Bid](#objectbid)
- [4.3 - Ad Serving Options](#adservingoptions)
- [4.3.1 - Markup Served on the Win Notice](#markupservedonwin)
- [4.3.2 - Markup Served in the Bid](#markupservedinbid)
- [4.3.3 - Comparison of Ad Serving Approaches](#comparisonofapproaches)
- [4.4 - Substitution Macros](#substitutionmacros)
- [4.4.1 - Notes on the macro ${AUCTION_MIN_TO_WIN}](#notesonmacro)
## [5. Enumerated Lists Specification](#enumeratedlistsspec)
## [6. Bid Request/Response Samples](#bidrequestresponsesamples)
- [6.1 - GitHub Repository](#githubrepo)
- [6.2 - Bid Requests](#6.4bidrequests)
- [6.2.1 - Example 1 – Simple Banner](#simplebanner)
- [6.2.2 - Example 2 – Expandable Creative](#expandablecreative)
- [6.2.3 - Example 3 – Mobile](#example3mobile)
- [6.2.4 - Example 4 – Video](#example4video)
- [6.2.5 - Example 5 – PMP with Direct Deal](#pmpwdirectdeal)
- [6.2.6 - Example 6 – Native Ad](#example6nativead)
- [6.3 - Bid Responses](#6.3bidresponses)
- [6.3.1 - Example 1 – Ad Served on Win Notice](#ex1adservedwin)
- [6.3.2 - Example 2 – VAST XML Document Returned Inline](#vastxml)
- [6.3.3 - Example 3 – Direct Deal Ad Served on Win Notice](#directdealadonwin)
- [6.3.4 - Example 4 – Native Markup Returned Inline](#nativemarkupreturnedinline)
## [7. Implementation Notes](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/implementation.md#7-implementation-notes-)
- [7.1 - No-Bid Signaling](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/implementation.md#71-no-bid-signaling-)
- [7.2 - Impression Expiration](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/implementation.md#72-impression-expiration-)
- [7.3 - PMP & Direct Deals](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/implementation.md#73-pmp--direct-deals-)
- [7.4 - Skippability](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/implementation.md#74-skippability-)
- [7.5 - Regs Resources](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/implementation.md#75-regs-resources-)
- [7.6 - Pod Bidding for Video and Audio](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/implementation.md#76-pod-bidding-for-video-and-audio-)
- [7.7 - Network vs Channel Example Cases](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/implementation.md#77-network-vs-channel-example-cases-)
- [7.8 - Counting Billable Events and Tracked Ads](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/implementation.md#78-counting-billable-events-and-tracked-ads-)
- [7.9 - Digital Out-Of-Home](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/implementation.md#79---digital-out-of-home-)
## [Appendix A. Additional Information](#appendixa)
## [Appendix B. Specification Change Log](#appendixb)
## Getting Started <a name="started"></a>
This specification contains a detailed explanation of an RTB (Real-Time Bidding) interface. Not all objects are “required,” and each object may contain several optional parameters. As that term is used herein, “required” attributes are designated as such if their omission would technically break the protocol. This means that it is technically possible for two implementers to conduct a minimally viable transaction if all required attributes are included, and impossible without them. This does not, however, mean that including only required attributes will be satisfactory to implementers for business reasons. For example, a request with only required attributes does not supply any context about what is being bid on, such as whether it is for a site or app, or which site/app it is for. While the transaction is technically possible, in practice, market participants will likely find this to be unsatisfactory.
Some optional attributes are denoted "recommended." As that term is used herein “recommended” means that their inclusion is customary and, thus, likely to be expected by most implementers. While they are not required for a minimally viable transaction to occur, the market norm is to include such attributes; implementers may be unwilling to transact unless these attributes are included. The designation as "recommended" is based on awareness of these market norms and should not be interpreted as a suggestion by IAB Tech Lab that an implementer propagate any specific attribute. Implementers should determine which attributes they will make available based on discussion with their business partners, and in a manner consistent with applicable law.
<table>
<tr>
<td><strong>Example Type</strong></td>
<td><strong>Attribute</strong></td>
<td><strong>Type</strong></td>
<td><strong>Description</strong></td>
</tr>
<tr>
<td rowspan="2">Examples of required attributes.<br> Grouped at the tops of tables for convenience</td>
<td><code>id</code></td>
<td>string;<br> required</td>
<td>...</td>
</tr>
<tr>
<td><code>imp</code></td>
<td>object array;<br> required</td>
<td>...</td>
</tr>
<tr>
<td rowspan="2">Examples of recommended attributes.<br> Grouped after required attributes.</td>
<td><code>site</code></td>
<td>object;<br>recommended</td>
<td>...</td>
</tr>
<tr>
<td><code>app</code></td>
<td>object;<br>recommended</td>
<td>...</td>
</tr>
<tr>
<td rowspan="4">Examples of optional attributes with and without defaults.<br> Attributes are assumed optional unless explicitly qualified as required or recommended.</td>
<td><code>test</code></td>
<td>integer;<br>default 0</td>
<td>...</td>
<tr>
<td><code>at</code></td>
<td>integer;<br>default 2</td>
<td>...</td>
</tr>
<tr>
<td><code>tmax</code></td>
<td>integer;</td>
<td>...</td>
</tr>
<tr>
<td><code>wseat</code></td>
<td>string array</td>
<td>...</td>
</tr>
</table>
*Example of how Required, Recommended and Optional attributes are presented.*
**IMPORTANT:** Since **recommended** attributes are not required, they may not be available from all supply sources. It is suggested that all parties to OpenRTB trasnaction develop an integration checklist to identify which attributes the supply side supports in the bid request, and which attributes the demand side requires for ad decisioning.
# 1. Introduction <a name="intro"></a>
## 1.1 - Mission / Overview <a name="mission"></a>
The mission of OpenRTB is to spur growth in Real-Time Bidding (RTB) marketplaces by providing open industry standards for communication between buyers of advertising and sellers of publisher inventory. There are several aspects to these standards including but not limited to the actual real-time bidding protocol, information taxonomies, offline configuration synchronization, and many more.
This document specifies a standard for the Real-Time Bidding Interface that grew out of previous OpenRTB collaboration on the “block list project” and the “OpenRTB Mobile” project. These protocol standards aim to simplify the connection between suppliers of publisher inventory (i.e., exchanges, networks working with publishers, and sell-side platforms) and competitive buyers of that inventory (i.e., bidders, demand side platforms, or networks working with advertisers).
The overall goal of OpenRTB is and has been to create a *lingua franca* for communicating between buyers and sellers. The intent is not to regulate exactly how each business operates. It aims to make integration between parties easier, so that innovation can happen at a deeper-level at each of the businesses in the ecosystem.
## 1.2 - History of OpenRTB <a name="history"></a>
OpenRTB was launched as a pilot project between three demand-side platforms (DataXu, MediaMath, and Turn) and three sell-side platforms (Admeld, PubMatic, and The Rubicon Project) in November 2010. The first goal was to standardize communication between parties for exchanging block lists. Version 1.0 of the OpenRTB block list specification was released in December 2010.
After a positive response from the industry, Nexage approached the OpenRTB project with a proposal to create an API specification for OpenRTB focusing on the actual real-time bid request/response protocol and specifically to support mobile advertising. The mobile subcommittee was formed between companies representing the buy-side (DataXu, Fiksu, and [X+1]) and companies representing the sell- side (Nexage, Pubmatic, Smaato, and Jumptap). This project resulted in the OpenRTB Mobile 1.0 specification, which was released in February 2011.
Following the release of the mobile specification, a video subcommittee was formed with video ad exchanges (BrightRoll and Adap.tv) collaborating with DataXu and ContextWeb to incorporate support for video. The goal was to incorporate support for display, video, and mobile in one document. This effort resulted in OpenRTB 2.0, which was released as a unified standard in June 2011.
Due to very widespread adoption by the industry, OpenRTB was adopted as an IAB Tech Lab standard in January 2012 with the release of version 2.1.
## 1.3 - Version History <a name="versionhistory"></a>
**OpenRTB Real-Time Bidding API** <a name="realtimebidding"></a>
2.6 - Introduces Ad Pods for CTV transactions, a structured User-Agent object and other minor enhancements.
2.5 - Support for header bidding, billing and loss notifications, Flex Ads, Payment ID, tactic ID, impression metrics, out-stream video, and many more minor enhancements.
2.4 - Support for Audio ad units and the largest set of minor to moderate enhancements in v2.x history.
2.3 - Support for Native ad units and multiple minor enhancements.
2.2 - New enhancements for private marketplace direct deals, video, mobile, and regulatory signals.
2.1 - Revisions for IQG compliance, minor enhancements, and corrections.
2.0 - Combines display, mobile, and video standards into a unified specification.
1.0 - Original Release of OpenRTB Mobile.
**OpenRTB Display Block List Branch** <a name="displayblock"></a>
1.2 - Publisher Preferences API (proposed).
1.1 - Minor edits to include real-time exchange of creative attributes.
1.0 - Original Release of OpenRTB block list specifications.
## 1.4 - Resources <a name="resources"></a>
Updates to the specification are made through the IAB Tech Lab’s [Programmatic Supply Chain Working Group](https://iabtechlab.com/working-groups/programmatic-supply-chain-working-group/). Contact techlab@iabtechlab.com to join the working group and participate in Slack discussions.
## 1.5 - Terminology <a name="terminology"></a>
The following terms are used throughout this document specifically in the context of the OpenRTB Interface and this specification.
<table>
<tr>
<td><strong>Term </strong></td>
<td><strong>Definition </strong></td>
</tr>
<tr>
<td><code>RTB</code></td>
<td>Bidding for individual impressions in real-time (i.e., while a consumer is waiting).</td>
</tr>
<tr>
<td><code>Exchange</code></td>
<td>A service that conducts an auction among bidders per impression.</td>
</tr>
<tr>
<td><code>Bidder</code></td>
<td>An entity that competes in real-time auctions to acquire impressions.</td>
</tr>
<tr>
<td><code>Seat</code></td>
<td>An advertising entity (e.g., advertiser, agency) that wishes to obtain impressions and uses bidders to act on their behalf; a customer of a bidder and usually the owner of the advertising budget.</td>
</tr>
<tr>
<td><code>Publisher</code></td>
<td>An entity that operates one or more sites.</td>
</tr>
<tr>
<td><code>Site</code></td>
<td>Ad supported content including web and applications unless otherwise specified.</td>
</tr>
<tr>
<td><code>Deal</code></td>
<td>A pre-arranged agreement between a Publisher and a Seat to purchase impressions under certain terms.</td>
</tr>
</table>
## 2. OpenRTB Basics <a name="rtbbasics"></a>
The following figure illustrates the OpenRTB interactions between an exchange and its bidders. Ad requests originate at publisher sites or applications. For each inbound ad request, bid requests are broadcast to bidders, responses are evaluated under prevailing auction rules, and a winner is selected. The winning bidder is notified of the auction win via a win notice. Ad markup can either be included in the bid prospectively or in response to the win notice. A separate billing notice is also available to accommodate varying policies enacted by exchanges which are beyond the scope of the OpenRTB specification (e.g., billing on device delivery, viewability, etc.). The win notice informs the bidder’s pricing algorithms of a success, whereas the billing notice indicates that spend should actually be applied. A loss notification is also available to inform the bidder of the reason their bid did not win.
The URLs for win, billing, and loss notices and the ad markup itself can contain any of several standard macros that enable the exchange to communicate critical data to the bidder (e.g., clearing price).
![](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/864a56706b106eda94c03abefaa01dd43544864c/assets/Figure1%20OpenRTB.png)
*Figure 2: Reference Model - Request Sequence.*
This specification focuses on the real-time interactions of bid request and response and the win, billing, and loss notices. Related specifications include:
- [AdCOM](https://github.com/InteractiveAdvertisingBureau/AdCOM/blob/master/AdCOM%20v1.0%20FINAL.md): The Advertising Common Object Model, a companion specification that defines common objects and values expected to be used across many IAB Tech Lab specifications. As of OpenRTB 2.6, all enumerated lists used by OpenRTB 2.6 are kept in AdCOM to enable more rapid iteration.
- [OpenRTB Ad Management API](https://github.com/InteractiveAdvertisingBureau/AdManagementAPI/blob/master/Ad%20Management%20API%201.0%20FINAL.md): A companion specification for facilitating creative review between bidders and exchanges.
Other interactions (e.g., block list synchronization, traffic control, etc.) are candidates for future OpenRTB initiatives or alternate projects.
## 2.1 - Transport <a name="transport"></a>
The base protocol between an exchange and its bidders is HTTP. Specifically, HTTP POST is required for bid requests to accommodate greater payloads than HTTP GET and facilitate the use of binary representations. Win notices may be either POST or GET at the discretion of the exchange.
Calls returning content (e.g., any bid response, a win notice that returns markup) should return HTTP code 200. Calls returning no content in response to valid requests (e.g., an empty bid response which is one option for indicating no-bid, a win notice that does not return markup) should return HTTP 204.
Invalid calls (e.g., a bid request containing a malformed or corrupt payload) should return HTTP 400 with no content.
**BEST PRACTICE**: One of the simplest and most effective ways of improving connection performance is to enable HTTP Persistent Connections, also known as Keep-Alive. This has a profound impact on overall performance by reducing connection management overhead as well as CPU utilization on both sides of the interface.
## 2.2 - Security <a name="security"></a>
HTTPS is not technically required for a functioning OpenRTB implementation. However, HTTPS is increasingly customary. It is strongly recommended that exchanges and bidders use only HTTPS.
## 2.3 - Data Format <a name="dataformat"></a>
JSON (JavaScript Object Notation) is the suggested format for bid request and bid response data payloads. JSON was chosen for its combination of human readability and compactness. The data payloads are described in Section 3 and Section 4.
Optionally, an exchange may also offer binary representations (e.g., compressed JSON, ProtoBuf, Avro, etc.), which can be more efficient in terms of transmission time and bandwidth. The IAB Tech Lab may offer reference implementations for these or other formats. When available, the use of these reference implementations is highly recommended to reduce exchange-specific variations.
The bid request specifies the representation as a mime type using the Content-Type HTTP header. The mime type for the standard JSON representation is “application/json” as shown. The format of the bid response must be the same as the bid request.
```Content-Type: application/json```
If alternative binary representations are used, the exchange or SSP should specify the Content-Type appropriately. For example: “Content-Type: avro/binary” or “Content-Type: application/x-protobuf”. If the content-type is missing, the bidder should assume the type is application/json, unless a different default has been selected by an exchange.
As a convention, the absence of an attribute has a formal meaning. In most cases, this indicates that the value is unknown, unless otherwise specified.
## 2.4 - Data Encoding <a name="dataencoding"></a>
Compressing data sent between exchanges and bidders can be very beneficial. Compression greatly reduces the size of data transferred and thus saves network bandwidth for both exchanges and bidders. To realize these savings fully, compression should be enabled for both the bid request sent by the exchange and the bid response returned by the bidder.
Compression can be enabled on the bid response using standard HTTP 1.1 mechanisms. Most webservers already support gzip compression of response content and as such it is an ideal choice. For an exchange to signal they would like the response to be compressed, it should set the standard HTTP 1.1 Accept-Encoding header. The encoding value used should be “gzip”.
```accept-encoding: gzip```
This header represents to bidders an indication by the exchange that it is capable of accepting gzip encoding for the response. If the bidder server supports this and is correctly configured, it will automatically respond with content that is gzip encoded. This will be indicated using the standard HTTP 1.1 Content-Encoding header.
```content-encoding: gzip```
To enable compression on the bid request, it must first be agreed upon between the exchange and the bidder that this is supported. This is similar to when a custom data format is used since the exchange has to know both format and encoding before sending the bid request. If the bidder supports it, the exchange should indicate it is sending a gzip compressed bid request by setting the HTTP 1.1 Content- Encoding header. The encoding value used should be "gzip".
```content-enconding: gzip```
If this header is not set then it is assumed that the request content isn’t encoded. In HTTP 1.1, the Content-Encoding header is usually only used for response content. However, by using this header for the request content as well we are able to indicate a request is compressed regardless of the data format used. This is useful since even binary data formats can benefit from being compressed.
## 2.5 - OpenRTB Version HTTP Header <a name="httpheader"></a>
The OpenRTB Version should be passed in the header of a bid request with a custom header parameter. This will allow bidders to recognize the version of the message contained before attempting to parse the request.
Additionally, it is recommended albeit optional that bidders place an identically formatted message in the HTTP header of the response with the protocol version the bidder has implemented. The message may contain a different version number than the request header.
*x-openrtb-version: 2.6*
This version should be specified as `<major>.<minor>` (e.g., 2.6).
## 2.6 - Versioning Behavior <a name="versioningbehavior"></a>
As of OpenRTB 2.6-202211, OpenRTB's version number is only incremented on breaking changes. In other words, OpenRTB 2.7 should be considered a distinct version from OpenRTB 2.6 when there is a need for distinguishing versions. For example, a demand source might regard the version header when parsing a bid request received from a supply source. See OpenRTB Principles.
The current version of the OpenRTB specification is updated approximately once a month if there are non-breaking improvements to be released such as new fields, objects, or values in enumerated lists. Errata, such as clarifications or corrections to descriptions not materially impacting the specification itself, are also addressed during monthly updates. See Errata.
Release branches are created for each monthly release and the history of these can be reviewed on GitHub. The master branch for the repository will always reflect the most recent release, whereas ongoing development work occurs in the 'develop' branch.
This versioning policy is a break from historical practice for OpenRTB 2.x. In versions of OpenRTB prior to 2.6, major version numbers represent breaking changes and minor version numbers represent non-breaking changes.
This means:
- Bidders and exchanges must tolerate receiving new or unexpected fields and enumerated list values gracefully, treating them as unknown or ignoring them
- Bidders and exchanges should freely transmit new fields or enumerated list values
For example, if a new field or object is introduced in a future version of OpenRTB 2.6, exchanges should immediately start transmitting it to bidders, if the exchange chooses to implement support for that field. Bidders should start consuming it at their discretion, if it is relevant to them. Neither party needs to explicitly negotiate an "upgrade" to the latest release, but rather should discuss specific fields of interest as they become available.
New minor versions of OpenRTB 2.6 may introduce additional optional ways of handling things. For example, burl field was introduced in OpenRTB 2.5. Use of `burl` (instead of including a pixel in markup in `adm` field) is a breaking change for a specific exchange <> bidder integration, but this is a result of a decision between these parties to switch impression counting methodology and not a result of OpenRTB 2.5 itself. Partners should discuss such situations before making breaking changes to their integrations.
## 2.7 - Privacy <a name="privacy"></a>
Without limiting the scope of the Disclaimer, the OpenRTB specification does include several features to support implementer’s communication of information regarding consumer privacy, including, but not limited to:
- The status of do not track headers (Section 3.2.18)
- Presence of site/app privacy policies (Section 3.2.13 and Section 3.2.14)
- Regulations or laws that the transmitter of a bid request believes are applicable (Section 3.2.3)
- Consent and opt-out information strings for the user (Global Privacy Platform, US Privacy String and Transparency and Consent Framework consent strings) (Section 3.2.3 and Section 3.2.20)
As noted in the Disclaimer, each implementer is responsible to ensure that their implementation complies with any applicable laws, regulations, or self-regulatory frameworks.
## 2.8 - Relationship to Brand Safety Certified <a name="relationshiptocertified"></a>
OpenRTB is fully compatible with the Brand Safety Certified available here: [https://www.tagtoday.net/brand-safety](https://www.tagtoday.net/brand-safety) .
## 2.9 - Customization and Extensions <a name="customization"></a>
The OpenRTB spec allows for exchange specific customization and extensions of the specification. Any object may contain extensions. To keep extension fields consistent across platforms, they should consistently be named `ext`.
In order to better support common and well known extensions, IAB Tech Lab is now hosting these extensions at our Github repository : https://github.com/InteractiveAdvertisingBureau/openrtb/tree/master/extensions
# 3. Bid Request Specification <a name="bidspecification"></a>
RTB transactions are initiated when an exchange or other supply source sends a bid request to a bidder. The bid request consists of the top-level bid request object, at least one impression object, and may optionally include additional objects providing impression context.
## 3.1 - Object Model <a name="objectmodel"></a>
Following is the object model for the bid request. The top-level object (i.e., in JSON the unnamed outer object) is denoted as `BidRequest` in the model. Of its direct subordinates, only `Imp` is technically required since it is fundamental to describing the impression being sold and it requires at least one of `Banner` (which may allow multiple formats), `Video`, `Audio`, and `Native` to define the type of impression (i.e., whichever one or more the publisher is willing to accept; although a bid will be for exactly one of those specified). An impression can optionally be subject to a private marketplace.
![](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/a29f4b1060c04813270dbf13607bba0403409068/assets/ORTB%20ERD.png)
*Figure 3: Bid Request object model.*
Other subordinates to the `BidRequest` provide various forms of information to assist bidders in making targeting and pricing decisions.
Not shown in the model figure is an extensions object. This is an object of undefined structure that can be added to any other object to convey exchange-specific extensions to the standard. Exchanges using these objects are responsible for publishing their extensions to their bidders.
The following table summarizes the objects in the Bid Request model and serves as an index into the detailed definitions in the subsections that follow.
<table>
<tr>
<td><strong>Object </strong></td>
<td><strong>Section </strong></td>
<td><strong>Description</strong></td>
</tr>
<tr>
<td><code>BidRequest</code></td>
<td>3.2.1</td>
<td>Top-level object.</td>
</tr>
<tr>
<td><code>Source</code></td>
<td>3.2.2</td>
<td>Request source details on post-auction decisioning (e.g., header bidding).</td>
</tr>
<tr>
<td><code>Regs</code></td>
<td>3.2.3</td>
<td>Regulatory conditions in effect for all impressions in this bid request.</td>
</tr>
<tr>
<td><code>Imp</code></td>
<td>3.2.4</td>
<td>Container for the description of a specific impression; at least 1 per request.</td>
</tr>
<tr>
<td><code>Metric</code></td>
<td>3.2.5</td>
<td>A quanitifiable often historical data point about an impression.</td>
</tr>
<tr>
<td><code>Banner</code></td>
<td>3.2.6</td>
<td>Details for a banner impression (incl. in-banner video) or video companion ad.</td>
</tr>
<tr>
<td><code>Video</code></td>
<td>3.2.7</td>
<td>Details for a video impression.</td>
</tr>
<tr>
<td><code>Audio</code></td>
<td>3.2.8</td>
<td>Container for audio impression.</a>.</td>
</tr>
<tr>
<td><code>Native</code></td>
<td>3.2.9</td>
<td>Container for a native impression conforming to the Dynamic Native Ads API.</td>
</tr>
<tr>
<td><code>Format</code></td>
<td>3.2.10</td>
<td>An allowed size of a banner.</td>
</tr>
<tr>
<td><code>Pmp</code></td>
<td>3.2.11</td>
<td>Collection of private marketplace (PMP) deals applicable to this impression.</td>
</tr>
<tr>
<td><code>Deal</code></td>
<td>3.2.12</td>
<td>Deal terms pertaining to this impression between a seller and buyer.</td>
</tr>
<tr>
<td><code>Site</code></td>
<td>3.2.13</td>
<td>Details of the website calling for the impression.</td>
</tr>
<tr>
<td><code>App</code></td>
<td>3.2.14</td>
<td>Details of the application calling for the impression.</td>
</tr>
<tr>
<td><code>Pubisher</code></td>
<td>3.2.15</td>
<td>Entity that controls the content of and distributes the site or app.</td>
</tr>
<tr>
<td><code>Content</code></td>
<td>3.2.16</td>
<td>Details about the published content itself, within which the ad will be shown.</td>
</tr>
<tr>
<td><code>Producer</code></td>
<td>3.2.17</td>
<td>Producer of the content; not necessarily the publisher (e.g., syndication).</td>
</tr>
<tr>
<td><code>Device</code></td>
<td>3.2.18</td>
<td>Details of the device on which the content and impressions are displayed.</td>
</tr>
<tr>
<td><code>Geo</code></td>
<td>3.2.19</td>
<td>Location of the device or user's home base depending on the parent object.</td>
</tr>
<tr>
<td><code>User</code></td>
<td>3.2.20</td>
<td>Human user of the device; audience for advertising.</td>
</tr>
<tr>
<td><code>Data</code></td>
<td>3.2.21</td>
<td>Collection of additional user targeting data from a specific data source.</td>
</tr>
<tr>
<td><code>Segment</code></td>
<td>3.2.22</td>
<td>Specific data point about a user from a specific data source.</td>
</tr>
<tr>
<td><code>Network</code></td>
<td>3.2.23</td>
<td>Network on which an ad will be displayed.</td>
</tr>
<tr>
<td><code>Channel</code></td>
<td>3.2.24</td>
<td>Channel on which an ad will be displayed.</td>
</tr>
<tr>
<td><code>SupplyChain</code></td>
<td>3.2.25</td>
<td>Chain of nodes from beginning to end representing the entities involved in the direct flow of payment for inventory.</td>
</tr>
<tr>
<td><code>SupplyChainNode</code></td>
<td>3.2.26</td>
<td>Nodes defining the identity of an entity participating in the supply chain of a bid request.</td>
</tr>
<tr>
<td><code>EIDs</code></td>
<td>3.2.27</td>
<td>Extended identifiers support.</td>
</tr>
<tr>
<td><code>UIDs</code></td>
<td>3.2.28</td>
<td>Extended identifiers user id support.</td>
</tr>
<tr>
<td><code>UserAgent</code></td>
<td>3.2.29</td>
<td>Structured user agent information.</td>
</tr>
<tr>
<td><code>BrandVersion</code></td>
<td>3.2.30</td>
<td>Name and version information for a browser or similar software component.</td>
</td>
</td>
</tr>
<tr>
<td><code>Qty</code></td>
<td>3.2.31</td>
<td>A means of passing a multiplier in the bid request, representing the total quantity of impressions for adverts that display to more than one person.</td>
</td>
</td>
</tr>
<tr>
<td><code>DOOH</code></td>
<td>3.2.32</td>
<td>Details of the Digital Out of Home inventory calling for the impression.</td>
</td>
</td>
</tr>
</table>
# 3.2 - Object Specifications <a name="objectspecs"></a>
### 3.2.1 - Object: BidRequest <a name="objectbidrequest"></a>
The top-level bid request object contains a globally unique bid request or auction ID. This `id` attribute is required as is at least one impression object (Section 3.2.4). Other attributes in this top-level object establish rules and restrictions that apply to all impressions being offered.
There are also several subordinate objects that provide detailed data to potential buyers. Among these are the `Site`, `App` and `DOOH`objects, which describe the type of published media in which the impression(s) appear. These objects are highly recommended, but only one applies to a given bid request depending on whether the media is browser-based web content, a non-browser application, or Digital Out of Home inventory respectively.
<table>
<tr>
<td><strong>Attribute </strong></td>
<td><strong>Type </strong></td>
<td><strong>Description</strong></td>
</tr>
<tr>
<td><code>id</code></td>
<td>string; required</td>
<td>Unique ID of the bid request, provided by the exchange.</td>
</tr>
<tr>
<td><code>imp</code></td>
<td>object array; required</td>
<td>Array of <code>Imp</code> objects (Section 3.2.4) representing the impressions offered. At least 1 <code>Imp</code> object is required.</td>
</tr>
<tr>
<td><code>site</code></td>
<td>object; recommended</td>
<td>Details via a <code>Site</code> object (Section 3.2.13) about the publisher’s website. Only applicable and recommended for websites.</td>
</tr>
<tr>
<td><code>app</code></td>
<td>object; recommended</td>
<td>Details via an <code>App</code> object (Section 3.2.14) about the publisher’s app (i.e., non-browser applications). Only applicable and recommended for apps.</td>
</tr>
<tr>
<td><code>dooh</code></td>
<td>object</td>
<td>This object should be included if the ad supported content is a Digital Out-Of-Home screen. A bid request with a DOOH object must not contain a site or app object.</td>
</tr>
<tr>
<td><code>device</code></td>
<td>object; recommended</td>
<td>Details via a <code>Device</code> object (Section 3.2.18) about the user’s device to which the impression will be delivered.</td>
</tr>
<tr>
<td><code>user</code></td>
<td>object; recommended</td>
<td>Details via a <code>User</code> object (Section 3.2.20) about the human user of the device; the advertising audience.</td>
</tr>
<tr>
<td><code>test</code></td>
<td>integer; default 0</td>
<td>Indicator of test mode in which auctions are not billable, where 0 = live mode, 1 = test mode.</td>
</tr>
<tr>
<td><code>at</code></td>
<td>integer; default 2</td>
<td>Auction type, where 1 = First Price, 2 = Second Price Plus. Exchange-specific auction types can be defined using values 500 and greater.</td>
</tr>
<tr>
<td><code>tmax</code></td>
<td>integer</td>
<td>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.</td>
</tr>
<tr>
<td><code>wseat</code></td>
<td>string array</td>
<td>Allowed list of buyer seats (e.g., advertisers, agencies) allowed to bid on this impression. IDs of seats and knowledge of the buyer’s customers to which they refer must be coordinated between bidders and the exchange *a priori*. At most, only one of <code>wseat</code> and <code>bseat</code> should be used in the same request. Omission of both implies no seat restrictions.</td>
</tr>
<tr>
<td><code>bseat</code></td>
<td>string array</td>
<td>Block list of buyer seats (e.g., advertisers, agencies) restricted from bidding on this impression. IDs of seats and knowledge of the buyer’s customers to which they refer must be coordinated between bidders and the exchange *a priori*. At most, only one of <code>wseat</code> and <code>bseat</code> should be used in the same request. Omission of both implies no seat restrictions.</td>
</tr>
<tr>
<td><code>allimps</code></td>
<td>integer; default 0</td>
<td>Flag to indicate if Exchange can verify that the impressions offered represent all of the impressions available in context (e.g., all on the web page, all video spots such as pre/mid/post roll) to support road-blocking. 0 = no or unknown, 1 = yes, the impressions offered represent all that are available.</td>
</tr>
<tr>
<td><code>cur</code></td>
<td>string array</td>
<td>Array of allowed currencies for bids on this bid request using ISO-4217 alpha codes. Recommended only if the exchange accepts multiple currencies.</td>
</tr>
<tr>
<td><code>wlang</code></td>
<td>string array</td>
<td>Allowed list of languages for creatives using ISO-639-1-alpha-2. Omission implies no specific restrictions, but buyers would be advised to consider <code>language</code> attribute in the <code>Device</code> and/or <code>Content</code> objects if available. Only one of <code>wlang</code> or <code>wlangb</code> should be present.</td>
</tr>
<tr>
<td><code>wlangb</code></td>
<td>string array</td>
<td>Allowed list of languages for creatives using IETF BCP 47I. Omission implies no specific restrictions, but buyers would be advised to consider language attribute in the <code>Device</code> and/or <code>Content</code> objects if available. Only one of <code>wlang</code> or <code>wlangb</code> should be present.</td>
</tr>
<tr>
<td><code>bcat</code></td>
<td>string array</td>
<td>Blocked advertiser categories using the specified category taxonomy. <br>The taxonomy to be used is defined by the <code>cattax</code> field. If no <code>cattax</code> field is supplied IAB Content Taxonomy 1.0 is assumed.</td>
</tr>
<tr>
<td><code>cattax</code></td>
<td>integer; default 1</td>
<td>The taxonomy in use for bcat. Refer to the AdCOM 1.0 list <a href="https://github.com/InteractiveAdvertisingBureau/AdCOM/blob/master/AdCOM%20v1.0%20FINAL.md#list_categorytaxonomies">List: Category Taxonomies</a> for values.</td>
</tr>
<tr>
<td><code>badv</code></td>
<td>string array</td>
<td>Block list of advertisers by their domains (e.g., “ford.com”).</td>
</tr>
<tr>
<td><code>bapp</code></td>
<td>string array</td>
<td>Block list of applications by their app store IDs. See <a href="https://iabtechlab.com/wp-content/uploads/2020/08/IAB-Tech-Lab-OTT-store-assigned-App-Identification-Guidelines-2020.pdf">OTT/CTV Store Assigned App Identification Guidelines</a> for more details about expected strings for CTV app stores. 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.</td>
</tr>
<tr>
<td><code>source</code></td>
<td>object</td>
<td>A Source object (Section 3.2.2) that provides data about the inventory source and which entity makes the final decision.</td>
</tr>
<tr>
<td><code>regs</code></td>
<td>object</td>
<td>A Regs object (Section 3.2.3) that specifies any industry, legal, or governmental regulations in force for this request.</td>
</tr>
<tr>
<td><code>ext</code></td>
<td>object</td>
<td>Placeholder for exchange-specific extensions to OpenRTB.</td>
</td>
</td>
</tr>
</table>
### 3.2.2 - Object: Source <a name="objectsource"></a>
This object describes the nature and behavior of the entity that is the source of the bid request upstream from the exchange. The primary purpose of this object is to define post-auction or upstream decisioning when the exchange itself does not control the final decision. A common example of this is header bidding, but it can also apply to upstream server entities such as another RTB exchange, a mediation platform, or an ad server combines direct campaigns with 3rd party demand in decisioning.
<table>
<tr>
<td><strong>Attribute </strong></td>
<td><strong>Type </strong></td>
<td><strong>Description</strong></td>
</tr>
<tr>
<td><code>fd</code></td>
<td>integer, recommended</td>
<td>Entity responsible for the final impression sale decision, where 0 = exchange, 1 = upstream source.</td>
</tr>
<tr>
<td><code>tid</code></td>
<td>string; recommended</td>
<td>Transaction ID that must be common across all participants in this bid request (e.g., potentially multiple exchanges).</td>
</tr>
<tr>
<td><code>pchain</code></td>
<td>string; recommended</td>
<td>Payment ID chain string containing embedded syntax described in the TAG payment ID Protocol v1.0.</td>
</tr>
<tr>
<td><code>schain</code></td>
<td>object; recommended</td>
<td>This object represents both the links in the supply chain as well as an indicator whether or not the supply chain is complete. Details via the <code>SupplyChain</code> object (section 3.2.25).</td>
</tr>
<tr>
<td><code>ext</code></td>
<td>object</td>
<td>Placeholder for exchange-specific extensions to OpenRTB.</td>
</td>
</td>
</tr>
</table>
### 3.2.3 - Object: Regs <a name="objectregs"></a>
This object contains any legal, governmental, or industry regulations that the sender deems applicable to the request. See Section 7.5 for more details on the flags supporting Coppa, GDPR and others.
<table>
<tr>
<td><strong>Attribute </strong></td>
<td><strong>Type </strong></td>
<td><strong>Description</strong></td>
</tr>
<tr>
<td><code>coppa</code></td>
<td>integer</td>
<td>Flag indicating if this request is subject to the COPPA regulations established by the USA FTC, where 0 = no, 1 = yes. Refer to Section 7.5 for more information.</td>
</tr>
<tr>
<td><code>gdpr</code></td>
<td>integer</td>
<td>Flag that indicates whether or not the request is subject to GDPR regulations 0 = No, 1 = Yes, omission indicates unknown. Refer to Section 7.5 for more information.</td>
</tr>
<tr>
<td><code>us_privacy</code></td>
<td>string</td>
<td>Communicates signals regarding consumer privacy under US privacy regulation. See <a href="https://github.com/InteractiveAdvertisingBureau/USPrivacy/blob/master/CCPA/US%20Privacy%20String.md">US Privacy String specifications</a>. Refer to Section 7.5 for more information.</td>
</tr>
<tr>
<td><code>gpp</code></td>
<td>string</td>
<td>Contains the Global Privacy Platform’s consent string. See the <a href="https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform">Global Privacy Platform specification</a> for more details.</td>
</tr>
<tr>
<td><code>gpp_sid</code></td>
<td>integer array</td>
<td>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. GPP Section 3 (Header) and 4 (Signal Integrity) do not need to be included. See the <a href="https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Sections/Section%20Information.md">GPP Section Information</a> for more details.</td>
</tr>
<tr>
<td><code>ext</code></td>
<td>object</td>
<td>Placeholder for exchange-specific extensions to OpenRTB.</td>
</td>
</td>
</tr>
</table>
### 3.2.4 - Object: Imp <a name="objectimp"></a>
This object describes an ad placement or impression being auctioned. A single bid request can include multiple `Imp` objects, a use case for which might be an exchange that supports selling all ad positions on a given page. Each `Imp` object has a required ID so that bids can reference them individually.
The presence of `Banner` (Section 3.2.6), `Video` (Section 3.2.7), and/or `Native` (Section 3.2.9) objects subordinate to the `Imp` object indicates the type of impression being offered. The publisher can choose one such type which is the typical case or mix them at their discretion. However, any given bid for the impression must conform to one of the offered type.
<table>
<tr>
<td><strong>Attribute </strong></td>
<td><strong>Type </strong></td>
<td><strong>Description</strong></td>
</tr>
<tr>
<td><code>id</code></td>
<td>string; required</td>
<td>A unique identifier for this impression within the content of the bid request (typically, starts with 1 and increments.</td>
</tr>
<tr>
<td><code>metric</code></td>
<td>object array</td>
<td>An array of <code>Metric</code> object (section 3.2.5).</td>
</tr>
<tr>
<td><code>banner</code></td>
<td>object</td>
<td>A <code>Banner</code> object (section 3.2.6); required if this impression is offered as a banner ad opportunity.</td>
</tr>
<tr>
<td><code>video</code></td>
<td>object</td>
<td>A <code>Video</code> object (Section 3.2.7); required if this impression is offered as a video ad opportunity.</td>
</tr>
<tr>
<td><code>audio</code></td>
<td>object</td>
<td>An <code>Audio</code> object (Section 3.2.8); required if this impression is offered as an audio ad opportunity.</td>
</tr>
<tr>
<td><code>native</code></td>
<td>object</td>
<td>A <code>Native</code> object (Section 3.2.9); required if this impression is offered as a native ad opportunity.</td>
</tr>
<tr>
<td><code>pmp</code></td>
<td>object</td>
<td>A <code>Pmp</code> object (Section 3.2.11) containing any private marketplace deals in effect for this impression.</td>
</tr>
<tr>
<td><code>displaymanager</code></td>
<td>string</td>
<td>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. <br>Recommended for video and/or apps.</td>
</tr>
<tr>
<td><code>displaymanagerver</code></td>
<td>string</td>
<td>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. <br>Recommended for video and/or apps.</td>
</tr>
<tr>
<td><code>instl</code></td>
<td>integer; default 0</td>
<td>1 = the ad is interstitial or full screen, 0 = not interstitial.</td>
</tr>
<tr>
<td><code>tagid</code></td>
<td>string</td>
<td>Identifier for specific ad placement or ad tag that was used to initiate the auction. This can be useful for debugging of any issues, or for optimization by the buyer.</td>
</tr>
<tr>
<td><code>bidfloor</code></td>
<td>float; default 0</td>
<td>Minimum bid for this impression expressed in CPM.</td>
</tr>
<tr>
<td><code>bidfloorcur</code></td>
<td>string; default "USD"</td>
<td>Currency specified using ISO-4217 alpha codes. This may be different from bid currency returned by bidder if this is allowed by the exchange.</td>
</tr>
<tr>
<td><code>clickbrowser</code></td>
<td>integer</td>
<td>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.</td>
</tr>
<tr>
<td><code>secure</code></td>
<td>integer</td>
<td>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.</td>
</tr>
<tr>
<td><code>iframebuster</code></td>
<td>string array</td>
<td>Array of exchange-specific names of supported iframe busters.</td>
</tr>
<tr>
<td><code>rwdd</code></td>
<td>integer; default 0</td>
<td>Indicates whether the user receives a reward for viewing the ad, where 0 = no, 1 = yes. Typically video ad implementations allow users to read an additional news article for free, receive an extra life in a game, or get a sponsored ad-free music session. The reward is typically distributed after the video ad is completed.</td>
</tr>
<tr>
<td><code>ssai</code></td>
<td>integer; default 0</td>
<td>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.</td>
</tr>
<tr>