Skip to end of metadata
Go to start of metadata

Campaign Service

A campaign is a way to organize a set of targeting parameters within AppNexus in combination with the Profile Service. The campaign object includes parameters such as flight dates and associated creatives whereas profiles target user and inventory parameters such as geography, segment, frequency, domain, and category.

On This Page

REST API

Add a new campaign:

Modify an existing campaign:

View a specific campaign for one of your advertisers:

View all of the campaigns for one of your advertisers:

View multiple campaigns by ID using a comma-separated list:

Helpful Filters

  • You can filter for campaigns based on when they first and last served. This is particularly useful when you are approaching your object limit and need to identify campaigns that can be deleted from the system. For more details, see First Run / Last Run.
  • You can filter for campaigns that are not serving due to various conditions. For more details, see Alerts.

Search for campaigns with IDs or names containing certain characters:

Delete a campaign:

Deletion is permanent and cannot be reverted. Although deleted campaigns continue to be available in reporting, you will no longer have visibility into their specific settings (e.g., cost budget and targeting).

Find out which fields you can filter and sort by:

JSON Fields

General

Field

Type (Length)

Description

Default

Required On

id

int

The ID of the campaign

 

PUT, in query string

state

enum

The state of the campaign. Possible values: "active" or "inactive".

"active"

 
parent_inactiveboolean

Read-only. If true, the campaign is inactive due to the parent line item being inactive, and the campaign's state is overridden (i.e., if "parent_inactive": "true" and "state": "active", then the campaign is inactive).

To return this field, the advertiser_id must be included in the querystring.

false 

code

string (100)

A custom code for the campaign. The code may only contain alphanumeric characters, periods, underscores or dashes. The code you enter is not case-sensitive (upper- and lower-case characters are treated the same). No 2 objects at the same level (e.g., line items or campaigns) can use the same code per advertiser. For example, 2 lines items cannot both use code "XYZ", but a single line item and its child campaign can. 

  

name

string (255)

The name of the campaign.

 

POST

short_name

string (50)

The name used by the Imp Bus

  

advertiser_id

int

The ID of the advertiser to which the campaign belongs.

 

POST/PUT, in query string

profile_id

int

You may associate an optional profile_id with this campaign. A profile is a generic set of rules for targeting inventory. See the Profile Service for details.

  

line_item_id

int

The ID of the line item to which the campaign is associated.

No more than 500 campaigns can be associated to a single line item.

 

POST

start_date

timestamp

The date and time when the campaign should start serving. Null corresponds to "immediately". This value reflects the Advertiser's time zone.

null

 

end_date

timestamp

The date and time when the campaign should stop serving. Null corresponds to "indefinitely". This value reflects the Advertiser's time zone.

null

 

creatives

array

The list of creative IDs or codes associated to the campaign. Update only requires id or code to be passed in but GET request will include more creative fields for convenience. e.g.

For more information, see Creatives below.

  

creative_groups

array of IDs

You may wish to bucket a group of creatives and then add them to a campaign all at once. Create groups through the Line Item Service.

  

timezone

enum

The timezone of the campaign. See API Timezones for details and accepted values. If no timezone is set, this will default to the advertiser's timezone, which defaults to the member's timezone, which defaults to EST5EDT. Campaign daily budgets are reset at midnight in the timezone of the campaign, so this field determines that time.

Any PUT calls to the advertiser service which include set_child_timezone=true in the query string will cause any timezone settings on the lower level objects (e.g., insertion orders, line items, campaigns) to be overridden with the latest timezone value for that advertiser.

The advertiser's timezone

 

last_modified

timestamp

The time of last modification to this campaign.

  

supply_type

string

Read-only. The types of supply targeted by this campaign, as defined by the supply_type_targets field in the associated profile. This string can contain one or more of the following values, separated by commas: web, mobile_web, mobile_app, and facebook_sidebar.

  
supply_type_actionenumRead-only. Whether the types of supply are "included" or "excluded" from targeting, as defined by the supply_type_action field in the associated profile.  

inventory_type

enum

The type of inventory targeted by this campaign. Possible values: "real_time", "direct", or "both". "Real-time" includes all third-party inventory not managed by your network that has been enabled for reselling (including external supply partners such as Microsoft Advertising Exchange and Google AdX. "Direct" includes only inventory managed by your network.

"real_time"

 

roadblock_creatives

boolean

Only serve this campaign if all creatives attached to it, are able to serve on one page load.

Roadblocking is only enabled for direct inventory. If you attempt to set roadblock_creatives to true for an inventory_type other than direct, the API will return an error.

  

roadblock_type

enum

There are several types of roadblocks available. Allowed values are "no_roadblock", "normal_roadblock" (where the number of creatives is greater than or equal to the number of placements), "partial_roadblock" (where the number of creatives is less than or equal to the number of placements), and "exact_roadblock" (where the number of creatives is equal to the number of available placements).

"no_roadblock"

 

stats

object

The stats object has been deprecated (as of October 17, 2016). Use the Report Service to obtain statistical information instead.

  

all_stats

array

The stats object has been deprecated (as of October 17, 2016). Use the Report Service to obtain statistical information instead.

  

comments

string

Comments about the campaign.

  

labels

array of objects

The optional labels applied to the campaign. One label is currently available: "Test/Control". See Labels below for more details.

You can report on campaign labels with the Network Analytics, Network Advertiser Analytics, and Advertiser Analytics reports. For example, if you use the "Test/Control" label to specify the user group you are targeting (as defined by the user_group_targets field in the associated profile), you could run the Network Analytics report filtered by "user_group_for_campaign" to focus on the campaigns that target a particular user group, or grouped by "user_group_for_campaign" to rank the performance of your user groups.

  

broker_fees

array

The fees that the network must pay to brokers when serving an ad. These fees are in addition to the cost of the inventory and are typically for data, ad serving, or creative hosting. They can either be a percentage of the media cost or a flat CPM. See Broker Fees below for more details.

  

click_url

string (1000)

The (optional) landing page URL for non-3rd party image and flash creatives

  
valuationobjectAn object containing several fields relating to performance goals and minimum margin. See Valuation below for more details.  

remaining_days

int

Read-only. The number of days between today and the end_date for the campaign. Note that this will be null if the start_date is in the future or if either the start_date or end_date is not set.

  

total_days

int

Read-only. The number of days between the start_date and end_date for the campaign. Note that this will be null if either the start_date or end_date is not set.

  

first_run

timestamp

Read-only. The date and time when the campaign first served, refreshed on an hourly basis. This value reflects the UTC time zone. To include this information in a GET response, pass flight_info=true in the query string. For details about how to filter line items based on when they first served, see First Run / Last Run below.

  

last_run

timestamp

Read-only. The date and time when the campaign last served, refreshed on an hourly basis. This value reflects the UTC time zone. To include this information in a GET response, pass flight_info=true in the query string. For details about how to filter line items based on when they last served, see First Run / Last Run below.

  

alerts

object

Read-only. The conditions that are preventing the campaign from serving. There are two types of alerts: pauses and warnings. Pauses are considered intentional and user-driven, whereas warnings are considered unintentional. For example, "State is set to inactive" is considered a pause, whereas "No creatives are associated with this campaign" is considered a warning. To retrieve campaigns based on pauses and/or warnings, you must pass certain query string parameters in the GET request. For more details, including a complete list of possible pauses and warnings, see Alerts below.

  
creative_distribution_typeenum

When multiple creatives of the same size are trafficked via a line item, this field's setting is used to determine the creative rotation strategy that will be used. Note that creatives must be managed on the campaign in order to use this field. Allowed values:

  • even: The default. Use the standard AppNexus creative optimization algorithm, where each creative's valuation is computed independently, and the best-valued creative is chosen to serve.
  • weighted: Creative rotation is based on a user-supplied weight.
  • ctr-optimized: The creative with the highest CTR delivers the most.
"even" 
weightintA user-supplied weight that determines the creative rotation strategy for same-sized creatives managed at the campaign level. To use this field, the value of creative_distribution_type must be "weighted". Allowed value: an integer greater than 0 and less than or equal to 1000.10 

Pricing/Budgeting

Field

Type

Description

Default

Required On

lifetime_budget

double

The lifetime budget in dollars (media cost). Null corresponds to "unlimited".

If lifetime_budget is set to null (unlimited), and the line item and insertion order lifetime budgets are also set to null, severe overspend can occur.

null

 

lifetime_budget_imps

int

The lifetime budget in impressions. Null corresponds to "unlimited".

null

 

daily_budget

double

The daily budget in dollars (media cost). Null corresponds to "unlimited".

null

 

daily_budget_imps

int

The daily budget in impressions. Null corresponds to "unlimited".

null

 

learn_budget

double

The lifetime dollar (media cost) budget allocated to learning. Null corresponds to "unlimited".

null

 

learn_budget_imps

int

The lifetime impression budget allocated to learning. Null corresponds to "unlimited".

null

 

learn_budget_daily_cap

double

The maximum number of dollars (media cost) that can be allocated to learning per day. Null corresponds to "unlimited".

null

 

learn_budget_daily_imps

int

The maximum number of impressions that can be allocated to learning per day. Null corresponds to "unlimited".

null

 

enable_pacing

boolean

If true, the campaign's daily budgeted spend is spread out evenly throughout each day. This is only applicable if daily_budget is set. For more details about even daily pacing, see Daily Pacing (customer login required).

false

 

lifetime_pacing

boolean

If true, the campaign will attempt to spend its overall lifetime budget evenly over the campaign flight dates. If true, you cannot set a daily_budget, you cannot set enable_pacing to false, and you must first establish a lifetime_budget, a start_date, and an end_date for the campaign.

false

 

lifetime_pacing_span

int

In the event of an underspend event, this indicates the number of days across which the underspent amount will be distributed. The default value of null indicates a value of three (3) days.

null

 
priority

int

For a campaign targeting direct inventory (inventory_type is "direct"), since you have already paid for inventory, there is no need to input a buying strategy. However, you can set the campaign's priority to weight the campaign against other direct campaigns within your account. The campaign with the highest priority will always win, even if a lower priority campaign bids more. For more information about managing priority, see Bidding Priority (customer login required).

5

 

cadence_modifier_enabled

boolean

If true, bids will be adjusted upward and downward based on the frequency and recency of the user. Typically, bids are increased for low frequency-recency impressions and decreased for high frequency-recency users. This feature is based on the idea that the effectiveness of an ad differs when a user hasn't seen the ad before, hasn't seen it many times, or hasn't seen it recently. For more details, see Cadence Modifier (customer login required).

false

 

expected_pacing

double

Deprecated.

The stats object and Quickstats have been deprecated (as of October 17, 2016).

  

total_pacing

double

Deprecated.

The stats object and Quickstats have been deprecated (as of October 17, 2016).

  

has_pacing_dollars

enum

Deprecated.

The stats object and Quickstats have been deprecated (as of October 17, 2016).

  

has_pacing_imps

enum

Deprecated

The stats object and Quickstats have been deprecated (as of October 17, 2016).

  

imps_pacing_percent

int

Deprecated

The stats object and Quickstats have been deprecated (as of October 17, 2016).

  

media_cost_pacing_percent

int

Deprecated

The stats object and Quickstats have been deprecated (as of October 17, 2016).

  

Bidding Strategies

Field

Type

Description

Default

Required On

cpm_bid_type

enum

Possible values:

  • "base" - Bid a fixed amount.
  • "average" - Bid Estimated Average Price (EAP), an estimate of the price that is likely to win about 50% of the impressions from AppNexus platform sellers based on historical bids and their success or failure. Since off-platform sellers (e.g., Google AdX, Rubicon, etc.) conduct a secondary auction, bidding EAP does not necessarily ensure winning half of off-platform impressions.
  • "clearing" - Bid Estimated Clear Price (ECP), an estimate of the price that is likely to win most impressions from AppNexus platform sellers based on historical bids and their success or failure. Since off-platform sellers (e.g., Google AdX, Rubicon, etc.) conduct a secondary auction, bidding ECP does not necessarily ensure winning off-platform impressions.
  • "predicted" - Vary bids based on the likelihood of a click or conversion for each piece of inventory. For predicting CPC, use cpc_goal. For predicting CPA, see Pixels below.
  • "margin" - Bid a % margin of the revenue that the advertiser pays you. See bid_margin.
  • "custom_model" - Calculate your bid price based on a custom predictive model. You set which model to use in the bid_model object. See AppNexus Programmable Bidder for more details (customer login required).

    You can set cpm_bid_type to "custom_model" only when inventory_type is "rtb".

  • "none" - None is available only if you pay on a per-click or per-conversion basis, and it will result in not being able to bid CPM.
 

POST, unless inventory_type is set to "direct".

base_bid

double

A CPM bid. May be modified by the cadence_modifer.

 

POST, if cpm_bid_type is "base"

min_bid

double

Set a minimum bid that will apply to variable pricing models (See cpm_bid_type).

  

max_bid

double

Set a maximum bid that will apply to variable pricing models (See cpm_bid_type).

  

bid_margin

double

The percent margin of the revenue that the advertiser pays you. For example, if your booked revenue is $1 CPM, and you set a bidding strategy margin of 25%, your campaign will bid $0.75. If your booked revenue type is a CPA or CPC goal, it will apply your desired margin and optimize to that predicted goal.

 

POST, if cpm_bid_type is "margin"

cpc_goal

double

You may wish to vary bids based on the likelihood of some conversion event, either a click or an acquisition, for that particular inventory, in order to attain a specific cost per click or cost per acquisition. In this case the AppNexus Console determines a bid based on past conversion rates and based on how much you value a conversion, whether you define it as a click or an acquisition (registration, purchase, etc.).

 

POST, if cpm_bid_type is "predicted" and the roi_click_goal and roi_view_goal are not set in the pixels array.

max_learn_bid

double

When using the cpm_bid_type "predicted", the optimization engine submits "learn" bids to learn about new inventory. If necessary, enter the max CPM dollar amount for these bids. Note: When you set both max_learn_bid for learn bids and max_bid for non-learn bids, the lower of the two will be used for learn.

null

 

pixels

array

If using a CPA Bidding Strategy, the pixel array is used to associate conversion pixels with the campaign and set CPA goals and payout values for the pixels. See Pixels below for more details.

  
bid_modelobjectIf using a custom predictive model to determine bid prices, this object is used to associate your custom model with the campaign. See Bid Model below for more details.nullPOST, if cpm_bid_type is "custom_model"

Optimization Levers

These optional fields give advanced users extra control over optimizing their campaigns. For detailed information on these fields, see Optimization Levers (customer login required).

 Click here to see how these fields map to features in the Console

If you would like access to optimization levers, an AppNexus admin must set the expose_optimization_levers field to true for your member. Contact your account representative for more details.

Field

Type

Description

Default

Required On

ecp_learn_divisor

string

Deprecated. This feature is not supported in version 7 of the Optimization engine. For newer ways to adjust learn bids, see learn_override_type.

null (3)

 

projected_learn_events

int

Deprecated. This feature has been incorporated into the learn algorithm for version 7 of the Optimization engine.

null (3)

 

learn_threshold

int

The number of successful events (clicks or conversions) required before moving from the learn stage to the optimized stage. Possible values: 1 - 100.

null (3)

 

max_learn_bid

double

When using the cpm_bid_type "predicted", the optimization engine submits "learn" bids to learn about new inventory. If necessary, enter the max CPM dollar amount for these bids. Note: When you set both max_learn_bid for learn bids and max_bid for non-learn bids, the lower of the two will be used for learn.

null

 

cadence_type

enum

The level at which the cadence modifier is applied. Possible values: "advertiser" or "creative".

"advertiser"

 

defer_to_li_prediction

boolean

If true, this campaign will temporarily change the level at which it learns while maintaining a specified profit margin percentage. See Defer to Line Item Revenue with a % Margin for more details.

false

 

optimization_lookback

array of objects

Optimization is based on the last 30 days of data, evenly weighted. You can use this field to give more weight to certain days within that window. Possible values for "day": 0 - 29. Possible values for "bias_percent": 0 - 100. Example:

  

optimization_version

string

Read-only. Indicates the version of optimization currently in use.

v7

 

learn_override_type

enum

If you want to override AppNexus' learn bid, this is the type of bid to submit instead. Possible values:

  • "base_cpm_bid" - A flat CPM bid. You specify the CPM value in the base_cpm_bid_value field.
  • "venue_avg_cpm_bid" - The average bid for each venue.

null

 

base_cpm_bid_value

double

The CPM value to use for learn bids, when learn_override_type is "cpm_learn_bid". This value cannot be greater than 10.0.

null

POST/PUT, if learn_override_type is "base_cpm_bid".

bid_multiplier

double

The value by which to multiply the learn bid. This can be used for AppNexus' default learn bid or an override learn bid when learn_override_type is "venue_average_cpm_bid". This value cannot be greater than 10.0.

1.0

 

impression_limit

int

For a specific venue, the number of impressions after which to stop overriding AppNexus' learn bid. This value must be greater than 0.

40000

 

campaign_modifiers

array of objects

An array of objects containing the segment modifier-related settings associated with this campaign (format shown below). For more information, see Segment Modifier (customer login required).

You cannot set both campaign_modifier and bid_modifier_model in a single campaign.

  
bid_modifier_modelobject

The custom predictive model to apply multipliers to the campaign's optimization-derived CPM bid. This type of model is used in conjunction with an AppNexus optimization-based buying strategy ( when cpm_bid_type is "predicted" or "margin" ).

See Bid Modifier Model below for more details.

You can set bid_modifier_model only when inventory_type is "rtb". Also, you cannot set both bid_modifier_model and campaign_modifier in a single campaign.

null 

Broker Fees

When a network uses a broker to serve an impression, it pays a fee to the broker for that service. This value varies between different networks, different brokers, and different campaigns. Therefore, the network must specify how much it will pay each broker it uses. This can also be done at the Line Item level (Line Item Service) or at the Insertion Order level (Insertion Order Service).

To create or edit brokers, refer to the Broker Service.

Field

Type (Length)

Description

broker_id

int

The ID of the broker.

broker_name

string

Read-Only. The name of the broker.

payment_type

enum

Type of payment to the broker. Possible values: "cpm" or "revshare".

value

double

The value of the payment, based on the payment type.

description

string (255)

The free-form description of the broker fee entry.

Add a broker fee
Modify a broker fee

Creatives

Each object in the creatives array includes the following fields. To obtain information for "id" or "code" fields, you can use the Creative Service.

Field

Type (Length)

Description

Required On
idintThe ID of the creative. Either "id" or "code" is required when updating creative association.PUT
codestringThe custom code for the creative. Either "id" or "code" is required when updating creative association.PUT
namestringRead-only. The name of the creative. 
widthintRead-only. The width of the creative. 

height

int

Read-only. The height of the creative.

 
stateenumRead-only. The state of the creative. Possible values: "active" or "inactive". 

audit_status

enum

Read-only. The audit status of the creative. Possible values: "no_audit", "pending", "rejected", "audited", or "unauditable".

 

is_expired

boolean

Read-only. Whether the creative is expired. If "false," the creative is active.

 
is_prohibitedboolean Read-only. Whether the creative falls into a prohibited category on the AppNexus platform. 
is_self_auditedbooleanRead-only. Whether the creative is self-audited. If true, then yes. 
formatenum Read-only. The format of the creative file. Possible values: "url-html", "url-js", "flash", "image", "raw-js", "raw-html", "iframe-html", or "text". 

pop_window_maximize

boolean

Read-only. If true, the publisher's tag will maximize the window. Only relevant for creatives with format "url-html" and "url-js". If pop_window_maximize is set to true, then neither "height" nor "width" should be set on the creative.

 

Valuation

The valuation object contains the following fields related to minimum margin (customer login required).

Field

Type (Length)

Description

Default

min_margin_rtb_pct
decimalThe minimum margin PCT on RTB inventory. Overrides what is set in the line item.
NULL
eap_multiplier 
decimalThe EAP multiplier value. Can only be used on inventory types "real_time" or "both".
1.000000

Stats

The stats object has been deprecated (as of October 17, 2016). Use the Report Service to obtain statistical information instead.

Labels

Each object in the labels array includes the following fields.

You can use the read-only Label Service to view all possible labels for campaigns, advertisers, insertion orders, line items, and publishers. This service also allows you to view the labels that have already been applied to your objects.

Field

Type (Length)

Description

id

int

The ID of the label. Possible value: 9 (Test/Control).

name

enum

The name of the label. This field is read-only. Possible value: "Test/Control".

value

string (100)

The value assigned to the label. This could be the name of the user_group_target in the associated profile.

Pixels

Before you can associate a pixel to a campaign, the pixel must already be attached to the parent line item. Also, if cpc_bid_type is "predicted" and cpc_goal is not set, you must provide a value for either roi_click_goal or roi_view_goal.

Field

Type

Description

id

int

The ID of the conversion pixel.

state

enum

The state of the conversion pixel. Possible values: "active" or "inactive".

name

string

Read-only. The name of the conversion pixel.

roi_click_goal

double

If paying on a per-impression (CPM) basis and optimizing to a predicted CPA goal, set this field to the click goal.

roi_view_goal

double

If paying on a per-impression (CPM) basis and optimizing to a predicted CPA goal, set this field to the view goal.

click_payout

double

If paying on per-conversion (CPA) basis, set this field to the amount to pay the publisher per click.

view_payout

double

If paying on a per-conversion (CPA) basis, set this field to the amount to pay the publisher per view.

Bid Model

The bid_model object contains the following fields.

FieldTypeDescription
idintThe ID of the custom model. Only custom models with model_output set to "Bid" are allowed. Use the Custom Model Service to retrieve these IDs.
namestringRead-only. The name of the custom model.
activeBoolean

Read-only. The status of the model. Possible values: 1 (true) or 0 (false).

Bid Modifier Model

The bid_modifier_model object contains the following fields.

FieldTypeDescription
idintThe ID of the custom model. Only customs models with model_output set to "bid_modifier" are allowed. Use the Custom Model Service to retrieve these IDs.
namestringRead-only. The name of the custom model.
activeBoolean

Read-only. The status of the model. Possible values: 1 (true) or 0 (false).

First Run / Last Run

To include the first_run and last_run fields in a GET response, pass flight_info=true in the query string. You can also filter for campaigns based on when they first and last served, as follows:

Retrieve only campaigns that have never served
Retrieve only campaigns that first served on or after a specific date
Retrieve only campaigns that first served on or before a specific date
Retrieve only campaigns that first served within a specific date range
Retrieve only campaigns that last served on or after a specific date
Retrieve only campaigns that last served on or before a specific date
Retrieve only campaigns that last served within a specific date range

Alerts

This field notifies you of conditions that are preventing the campaign from serving. There are two types of alerts: pauses and warnings. Pauses are considered intentional and user-driven, whereas warnings are considered unintentional. For example, "State is set to inactive" is considered a pause, whereas "No creatives are associated with this campaign" is considered a warning.

To retrieve campaigns based on pauses and/or warnings, you must pass certain query string parameters in the GET request. See below for use cases with query string parameters and examples. Note that you can use these query string parameters both when retrieving all campaigns or specific campaigns, but the examples below only cover retrieving all campaigns, as that is where this feature offers the most value.

Retrieve all campaigns and show alerts
Retrieve only campaigns that have at least one pause
Retrieve only campaigns that have no pauses
Retrieve only campaigns that have a specific pause
Retrieve only campaigns that have two or more specific pauses
Retrieve only campaigns that have at least one warning
Retrieve only campaigns that have no warnings
Retrieve only campaigns that have a specific warning
Retrieve only campaigns that have at least one pause AND at least one warning
Retrieve only campaigns that have a specific pause AND a specific warning
Retrieve only campaigns that have pauses OR warnings
Pauses

ID

Description

1

State is set to inactive.

2

Parent line item is inactive.

4

Flight start is in the future.

8

Flight end is in the past.

Warnings

ID

Description

1

No creatives are associated with this campaign.

2

All creatives associated to this campaign are either ineligible to serve (inactive, expired, prohibited) or can serve only on direct inventory and on supply partners who trust your network's self-classification (unaudited). Note: Facebook creatives are audited by Facebook. Facebook creatives rejected by Facebook are considered ineligible.

Examples

Viewing campaign 17607 for advertiser 9
Creating a direct campaign


Related Topics