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.
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_inactive | boolean | Read-only. If To return this field, the | 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 | ||
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 | 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_action | enum | Read-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_type | enum | There are several types of roadblocks available. Allowed values are |
| |
stats | object | The | ||
all_stats | array | The | ||
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 | ||
valuation | object | An 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 | ||
total_days | int | Read-only. The number of days between the | ||
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 | ||
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 | ||
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_type | enum | 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" | |
is_archived | boolean | Read-only. Indicates whether the campaign has been automatically archived due to not being used. Once set to If a campaign is automatically archived, its profile will also be archived. If the campaign's parent line item is automatically archived, all campaigns (as well as their profiles) under that line item will also be archived. Once archived, the only calls that may be made on these objects are | false | |
archived_on | timestamp | Read-only. The date and time on which the campaign was archived (i.e., when the is_archived field was set to true ). | null |
Pricing/Budgeting
Field | Type | Description | Default | Required On |
---|---|---|---|---|
lifetime_budget | double | The lifetime budget in dollars (media cost). Null corresponds to "unlimited". If | 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 | 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 | 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 | |
priority | int | For a campaign targeting direct inventory ( | 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 | ||
total_pacing | double | Deprecated. The | ||
has_pacing_dollars | enum | Deprecated. The | ||
has_pacing_imps | enum | Deprecated The | ||
imps_pacing_percent | int | Deprecated The | ||
media_cost_pacing_percent | int | Deprecated The |
Bidding Strategies
Field | Type | Description | Default | Required On |
---|---|---|---|---|
| enum | Possible values:
|
| |
| double | A CPM bid. May be modified by the |
| |
| double | Set a minimum bid that will apply to variable pricing models (See | ||
| double | Set a maximum bid that will apply to variable pricing models (See | ||
| 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. |
| |
| 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.). |
| |
| double | When using the |
| |
| 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_model | object | If 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. | null | POST , 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).
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 | 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 | 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:
| null | |
base_cpm_bid_value | double | The CPM value to use for learn bids, when | null | POST/PUT, if |
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 | 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 | ||
bid_modifier_model | object | 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 See Bid Modifier Model below for more details. You can set | 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 |
---|---|---|---|
id | int | The ID of the creative. Either "id" or "code" is required when updating creative association. | PUT |
code | string | The custom code for the creative. Either "id" or "code" is required when updating creative association. | PUT |
name | string | Read-only. The name of the creative. | |
width | int | Read-only. The width of the creative. | |
height | int | Read-only. The height of the creative. | |
state | enum | Read-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_prohibited | boolean | Read-only. Whether the creative falls into a prohibited category on the AppNexus platform. | |
is_self_audited | boolean | Read-only. Whether the creative is self-audited. If true, then yes. | |
format | enum | Read-only. The format of the creative file. Possible values: "url-html", "url-js", "flash", "image", "raw-js", "raw-html", "iframe-html", or "text". | |
weight | int | A 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 . | |
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 | decimal | The minimum margin PCT on RTB inventory. Overrides what is set in the line item. | NULL |
eap_multiplier | decimal | The 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.
Field | Type | Description |
---|---|---|
id | int | The 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. |
name | string | Read-only. The name of the custom model. |
active | Boolean | Read-only. The status of the model. Possible values: |
Bid Modifier Model
The bid_modifier_model
object contains the following fields.
Field | Type | Description |
---|---|---|
id | int | The 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. |
name | string | Read-only. The name of the custom model. |
active | Boolean | Read-only. The status of the model. Possible values: |
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). |