int

The ID of the campaign

PUT, in query string

state

enum

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

"active"

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).

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.

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.

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, and mobile_app.

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.

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.

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

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.

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.

Read-only. Indicates whether the campaign has been automatically archived due to not being used. Once set to true, the value can't be changed and the only calls that can be made on the campaign object are GET and DELETE.

lifetime_budget

double

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

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

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.

total_pacing

double

Deprecated.

has_pacing_dollars

enum

Deprecated.

has_pacing_imps

enum

Deprecated

imps_pacing_percent

int

Deprecated

media_cost_pacing_percent

int

Deprecated

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 Custom Models 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.

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).

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.

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.

height

int

Read-only. The height of the creative.

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.

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.

min_margin_rtb_pct

NULL

eap_multiplier 

1.000000

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.

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.

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

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

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.

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).