About the Traffic API

This article describes the DSP Traffic API and core traffic objects and their relationships.

Overview

The Oath Ad Platforms DSP enables you to programmatically monitor, create, and manage advertising campaigns via resources that are exposed through the DSP Traffic API.

Oath DSP developers and partners can use these resources to manage advertisers, campaigns, lines, audiences, creatives, and more.

An resource is an object exposed through an endpoint. Resources are generally defined by multiple properties. These properties may be defined as integers, strings, arrays, or objects.

Campaign Hierarchy

Oath Ad Platforms DSP advertising campaigns and configurations may be defined at several levels.

Most resources are defined at the seat or advertiser level and are available to child elements.

|dsp| Advertising Campaign Hierarchy

Fig. 1 Oath Ad Platforms DSP Advertising Campaign Hierarchy

Seat-level configurations are available to all advertisers. Advertiser-level are only available to the advertiser.

  • A seat is a licensed account that is held by an ad agency, trading desk, or direct advertiser that enables that organziation to participate in the real-time bidding marketplace. Many core resources are defined at the seat level.
  • An advertiser is a demand-side partner that lists ads on the Oath Ad Platforms DSP and purchases inventory from exchanges in the broader marketplace. Resources defined at the advertiser level are available to every campaign belonging to that advertiser. An advertiser may be the parent of one or more campaigns.
  • A campaign is an advertiser-level goal that defines a strategy for delivering ads within a set time period. Campaigns are defined by start and end dates, budgets, frequency cap settings, an optional demographic targeting data provider, and campaign goals. A campaign may consist of one or more lines.
  • A line is a part of a campaign that specifies an advertising strategy. A line is defined by a single goal and one or more ads, budgets, targeting rules. Many line-level settings are constrained by campaign-level configurations.

Configuration Levels

Digital advertising campaign components may be defined at different levels of the campaign hierarchy.

The table identifies the level in the campaign hierarchy at which various advertisting campaign resources and configurations are specified.

Level Configuration
Seat
  • Account Groups
  • Advertisers
  • Audiences
  • Beacons
  • Contextuals
  • Site and App Lists
Advertiser
  • Audiences
  • Beacons
  • Contextuals
  • Creatives
  • Site and App Lists
  • User Groups
Campaign
  • Lines
  • Campaign Budgets
  • Campaign Goals
  • Campaign Schedules
Line
  • Bidding
  • Bid Multipliers
  • Billing
  • Budgets
  • Goals
  • Pacing
  • Schedules
  • Targeting
  • Ads

Many resources may be defined at both the seat leve and the advertiser level.

  • Resources specified at the seat-level are available for line targeting to any advertiser belonging to that seat.
  • Resources specified at the advertiser-level are only available for line targeting to a single seat.

Campaign-level budget and schedule configurations constrain line-level configurations.

Resources

The Oath Ad Platforms DSP RESTful API specifies a set of objects that you can use to create, manage, and retrieve seat-level and advertiser-level traffic data. These objects are resources for storing and retrieving information about the various aspects of digital advertising campaigns.

The DSP Traffic API documentation is organized by resource.

The diagram displays a high-level the relationships between key traffic objects, shows whether one or many child objects are allowed, and indicates if child objects are mandatory or optional.

Relationships between core |traffic| resources

Fig. 2 Core DSP Traffic API Resource Relationships

We recommend that you carefully study this diagram so that you will understand the relationships between DSP Traffic API objects.

Note

The diagram is not comprehensive and does not show all resources available through the DSP Traffic API.

Ad
The ad resource identifies a creative that is associated with a line.
Account Group
An account group is a set of advertisers grouped by region, brand, business unit, or another category that makes sense to your organization. Account groups are optional.
Audience
An audience is a collection of consumers with similar interests, habits, or online and offline behaviors. Audiences may be defined at the seat level or the advertiser level.
Beacons
A beacon is an object that represents a Yahoo Dot tag, a standard code snippet that can be used to communicate information about how consumers interact with sites. Beacons may be defined at the seat level or the advertiser level.
Bid Multiplier
A bid multiplier is a line-level resource that that specifies the relative weight that should be given to targeted ad placement opportunities.
Contextual
A contextual is a resource enables advertisers to target consumers by matching their interests and habits with a publisher’s content–that is, the context of the ad placement. The contextual specifies multiple parameters that identify both the consumer and the ad context. Contextuals may be defined at the seat level or the advertiser level.
Creative
A creative is an object that defines the image or video asset that is the foundation of an ad. The creative identifies the file type (image or video file), the advertising environment (native or web), and the file hosting information (Oath or third-party).
Deal
A deal is a set of terms reflecting an agreement between an exchange and an advertiser that is executed programmatically via a deal ID. The Oath Ad Platforms DSP supports two types of deals: shared deals and spot buy deals.
Exchange
An exchange is the supply partners that is integrated with Oath Ad Platforms DSP via the OpenRTB API.
Site List
A site list is an object used to blacklist or whitelist apps and URLs for your display, video, and native ads.
Targeting
Line-level targeting rules specify how the ads served by a line ads are delivered to consumers. Lines can target specific exchanges, deals, locations, demographics, ad positions, frequency, audiences, devices, days of the week, apps, URLs, page relevancy, mobile carriers, and languages.
User Group
A user group is a collection of users grouped together for the purposes of A/B testing.

Public Names of Resources

The public names used for Oath Ad Platforms DSP traffic objects is sometimes different than the name used for these objects in the DSP Traffic API.

Throughout the DSP Traffic API documentation the name of the resource is preferred over the the public name. For example, the term beacon is used instead of the term pixel, which is used in the Oath Ad Platforms DSP console.

The table maps the public name to the resource endpoint.

Public Name Resource Endpoint
Seat /traffic/seats
Advertiser Group /traffic/accountgroups
Advertiser /traffic/advertisers
Campaign /traffic/campaigns
Composite Audience /traffic/audiences/composite
Conversion Rule Audience /traffic/audiences/conversion_rule
Device ID Audience /traffic/audiences/device_id
Email Address Audience /traffic/audiences/email_address
Lookalike Audience /traffic/audiences/lookalike
Mail Domain Audience /traffic/audiences/mrt
Mail Event Audience /traffic/audiences/mail_event
Point of Interest Audience /traffic/audiences/poi
Search Keyword Audience /traffic/audiences/srt
Pixel /traffic/beacons
Contextual /traffic/contextuals
Site Lists and App Lists /traffic/sitelists
User Group /traffic/usergroups
Exchange /traffic/exchanges
Deal /traffic/deals
Creative /traffic/creatives
Ad /traffic/ads
Line /traffic/lines
Bid Multiplier /traffic/lines/{lineID}/bidmultiplier
Targeting /traffic/lines/{lineID}/targeting