Before traffic moves
Preflight is a joint operating agreement
An OpenRTB integration is not ready simply because two systems can exchange JSON. The partnership also needs a shared understanding of what inventory or demand is involved, which protocol rules and extensions apply, how traffic will be controlled, which signals must be present, and how both sides will reconcile delivery.
A useful preflight answers those questions in writing before production traffic begins. It reduces avoidable ambiguity: the supply team knows what the buyer can evaluate, the demand team knows what the seller can consistently provide, and both technical teams know where to look when results diverge. The goal is not to predict an outcome. It is to make the test interpretable.
Use this guide alongside the parties’ own security, privacy, legal and commercial review. It complements—not replaces—the IAB Tech Lab OpenRTB standards and the version-specific material in the official OpenRTB 2.x repository.
01 · Opportunity definition
Describe the partnership before describing the endpoint
Start with a one-page traffic profile. The reader should be able to understand the direction of traffic, intended environments and practical limits without opening a technical specification. If this profile is vague, an otherwise correct integration can still send traffic that the other side cannot use.
Role and traffic direction
- Name the party sending bid requests and the party returning bids.
- State whether the relationship is direct, intermediary or contains more than one selling node.
- Identify the business and technical owner on each side, including an escalation contact.
Inventory and demand scope
- List the formats under consideration: banner, video, native or audio, as applicable.
- Separate web, mobile app, connected TV and other environments instead of treating them as interchangeable.
- Document priority geographies, devices, app or site categories and any explicit exclusions.
Traffic profile
- Share realistic QPS ranges, peak patterns and the method used to shape traffic.
- Clarify whether requests are sampled, filtered or duplicated across endpoints.
- Record any account, campaign, seat, deal or inventory controls used for the test.
Test purpose
- Write the question the test is meant to answer: connectivity, format fit, usable scale or another defined objective.
- Choose observable acceptance checks and a review date.
- Keep expansion separate from launch; scaling should follow a joint review of evidence.
For environment-specific planning, pair this profile with AdSelect’s guidance for CTV advertising partnerships, programmatic video or in-app advertising.
02 · Technical contract
Make implementation choices explicit
“OpenRTB supported” is not a complete specification. Both teams need to name the OpenRTB version, transport behavior and any extensions or intentional deviations. The cleanest handoff is a short integration sheet plus representative request and response examples that have been reviewed by both sides.
Protocol and serialization
Record the exact OpenRTB version each side will send and accept. Confirm JSON encoding, content type, HTTP method, compression support and the expected handling of unknown fields. If protobuf or another representation is being considered, treat it as a separate agreement rather than an assumption. List every custom extension with its owner, schema, allowed values and fallback behavior.
Endpoint and access
Document separate test and production URLs where available, HTTPS requirements, authentication headers, IP allowlisting, DNS expectations and source IP ranges. Decide how credentials will be exchanged and rotated outside the article or ticket that documents the integration. Include a health-check or connectivity procedure that does not require live auction volume.
Timing and response behavior
Align on the timeout budget and how it relates to the request’s tmax value. Specify how no-bids, malformed requests, authentication failures, rate limits and server errors are represented. Define retry behavior carefully: automatic retries can create duplicate auctions or unexpected load if request identifiers and idempotency assumptions are not understood.
03 · Field map
Map the fields that make the opportunity usable
A field map should distinguish required, conditionally required, optional and unavailable signals. It should also record the source of each value. That prevents a buyer from assuming a populated field is publisher-declared when it was inferred, enriched or copied from another system.
Auction envelope
Confirm unique request IDs, impression arrays, auction type where relevant, accepted currencies, blocked categories or advertisers, source information and timeout handling. Define whether one request may contain several impressions and whether an impression may advertise more than one eligible media type under the chosen version.
Inventory context
For web, review site identity, page or domain and publisher information. For apps and CTV, review app name, bundle, store URL and publisher information. Confirm how content, channel, language and placement context are populated, and do not substitute an app bundle or domain that does not identify the actual property.
Impression and format
Document the supported banner, video, native or audio objects and the fields that determine eligibility. Examples include size or format arrays, MIME types, duration, placement, protocols, API frameworks, secure delivery and blocked attributes. Use the names and enumerations from the declared OpenRTB version.
Device and user context
Agree which device, operating-system, user-agent, IP, language, geolocation and identifier fields may be present, their precision, and the conditions under which they must be omitted. Do not treat missing identifiers as a transport defect until privacy choices, device limits and the stated inventory environment have been considered.
Deals and private controls
If deals are in scope, test the placement of deal IDs, bid-floor behavior, auction type, eligible seats and any targeting constraints. Confirm whether open-auction and deal traffic can coexist in the same request and how the response should identify the selected deal.
Bid and creative response
Align on price and currency, creative markup or reference, advertiser domain, campaign and creative identifiers, categories, attributes, dimensions, duration and notification URLs as applicable. State which response fields are mandatory for policy checks and reporting, even if the base specification marks them optional.
A practical field-map format
For every important field, capture: JSON path, direction, requirement level, allowed values, example, source of truth, privacy condition and behavior when absent. Review the map against actual samples, not only documentation. This turns abstract compatibility into a testable contract.
04 · Privacy, path and quality
Verify what the traffic represents and what may travel with it
Technical compatibility does not establish permission, ownership or quality. These questions need their own review, tied to the specific inventory source and the markets included in the test.
Privacy signals
List the jurisdictions and privacy frameworks relevant to the proposed traffic. Agree how applicable regulatory and consent signals are conveyed in the chosen OpenRTB version, what happens when they are absent or invalid, and which uses are allowed for the data received.
Privacy teams should approve the implementation. A bid request containing a field is not, by itself, proof that every downstream use is permitted.
Supply-path transparency
Confirm publisher or app identity, the seller’s relationship to the inventory, ads.txt or app-ads.txt authorization where applicable, sellers.json entries and the SupplyChain representation used in requests. The identities and relationship declarations should agree across these sources.
If a required record is not yet published or does not match, pause and resolve the discrepancy before interpreting test results. Supply-path records are not decoration; they help a buyer understand who is selling and through which nodes.
Inventory and creative quality
Document the traffic filters applied before the endpoint, the creative review performed after a bid, and the evidence available for the source. If third-party measurement is provided, identify the measured property, provider, date range and metric definition. Evidence for one source or period should not be generalized to all traffic.
Agree blocked categories, advertiser domains, creative attributes, landing-page rules and malware or policy escalation paths. Review AdSelect’s inventory quality approach for a source-specific evaluation framework.
05 · Reporting and operations
Define the numbers before comparing them
Two reports can both be internally correct and still disagree because they count different events, close on different time zones or apply different filters. A preflight reporting dictionary makes discrepancies diagnosable.
Measurement dictionary
Define requests received, valid requests, bids, eligible bids, wins, impressions and other applicable events. Record whether timestamps represent send time, receive time or event time. Name the reporting time zone, currency, rounding rule and latency window.
Join keys and evidence
Identify the request, impression, bid, creative and deal IDs that can be used to trace a sample auction. Agree a secure process for sharing redacted payloads and logs. Set retention windows so evidence is still available when a discrepancy is reviewed.
Alerts and ownership
Assign an owner for connectivity, traffic quality, creative policy and reporting. Agree alert thresholds for error rates, timeouts, unexpected QPS and major volume changes. State who can pause traffic and how both sides will be notified.
Change management
Record how endpoint, protocol, extension, filtering and account changes will be announced and tested. A versioned change log is more reliable than assumptions carried across chat threads. Re-run the relevant part of preflight after a material change.
06 · Controlled test
Open the endpoint in deliberate stages
A controlled test should expose enough traffic to validate behavior while limiting operational risk. The exact volumes and duration depend on the opportunity; the sequence below is more important than a universal number.
- 01
Connectivity
Validate DNS, TLS, authentication, content type, compression and basic HTTP behavior with synthetic or tightly limited requests.
- 02
Payload validation
Inspect real samples for required objects, enumerations, privacy signals, supply-path data and format-specific fields. Resolve structural errors before adding volume.
- 03
Limited live traffic
Enable a defined inventory, geography or account slice with a conservative QPS cap. Watch latency, error distribution, bid eligibility and policy blocks.
- 04
Reconciliation
Compare reports using the agreed dictionary. Trace representative auctions end to end and document unresolved gaps.
- 05
Quality review
Review inventory, creative and supply-path evidence for the tested slice. Separate configuration problems from source-specific findings.
- 06
Joint decision
Choose to pause, correct, continue at the same scope or expand. Record the rationale, owner, next review and any new limits.
07 · Final readiness check
Do not open production traffic until these answers are written
Traffic direction, party roles and named owners are documented.
Formats, environments, geographies, exclusions and test purpose are defined.
OpenRTB version, extensions, endpoint access and transport behavior are agreed.
Representative request, bid, no-bid and error examples have been reviewed.
Required request and response fields have owners, examples and absence rules.
Applicable privacy signals and permitted data use have been approved.
Seller identity, authorization and supply-path records have been checked.
Inventory and creative quality controls are tied to the tested source.
Metrics, time zone, currency, identifiers and discrepancy workflow are aligned.
Traffic caps, pause authority, alerts, test stages and review date are recorded.
The preflight output
A strong preflight produces five small artifacts: an opportunity profile, an integration sheet, a field map, a reporting dictionary and a test plan. Together, they give both parties a shared reference for implementation, troubleshooting and the decision to scale.
Primary references
Read the official specification
Version-sensitive field definitions and implementation notes should be checked against the current source material.
Continue the review
Related AdSelect resources
Useful for your next partnership?
Share this checklist with the supply, demand and technical owners before the first endpoint review.