Skip to end of metadata
Go to start of metadata

Profile Service

A profile is a set of targeting parameters, such as gender, age, geography, and frequency. It can be applied to several objects in the system, most of which are listed below. The most common use of the profile service is to run a campaign; you create a profile and then associate it with the Campaign Service. The campaign object includes fields such as flight dates and associated creatives.

  • Except for segment targeting, parameters are absolute. For example, if the geographical target is set only to the United States, ONLY U.S.-based impressions will receive bids.
  • Segment targeting uses and/or Boolean logic.
  • Profiles must be associated with either an advertiser or a publisher, in order to be used with several other objects in the system, listed below.

Profiles can be used with several other objects in the system (listed below). Any fields in the profile that do not apply to the associated object will be ignored.

  • Advertiser
  • Line Item
  • Creative
  • Campaign
  • Payment Rule
  • Ad Quality Rule

It is also possible to refer to a profile within a deal object, while it is not necessary for the profile to be associated to an advertiser or publisher.

On This Page

REST API

Add a new profile:

Modify an existing profile:

View all of the profiles for one of your advertisers:

View a specific profile for one of your advertisers:

To use this service for publisher profiles, replace advertiser_id with publisher_id.

JSON Fields

General

Field

Type

Description

Default

Required On

id

int

The ID of the profile.

 

PUT, in query string

code

string

A custom code for the profile.

  

description

string

Optional description.

  

is_template

Boolean

If true, the profile has been saved as a targeting template in the UI. To get profiles that are targeting templates in the UI, pass is_template=true in the query string of a GET call. For more details about targeting templates in the UI, see Managing Targeting Templates (Customer login required).

false

 

last_modified

timestamp

Time of last modification to this profile.

  
is_archivedboolean

Read-only. Indicates whether the profile has been automatically archived due to it's parent line item not being used (and therefore, having been archived). Once set to true, the value can't be changed and the only calls that can be made on the profile object are GET and DELETE.

If a profile's parent line item or campaign is automatically archived, the profile will also be archived. In addition, once archived, the profile may not be associated with any line items or campaigns.

false 
archived_ontimestampRead-only. The date and time on which the profile was archived (i.e., when the is_archived field was set to true).null 

Frequency

For details on Frequency and Recency Targeting and the below fields, please click here.

Field

Type

Description

Default

Required On

max_lifetime_imps

int

The maximum number of impressions per person. If set, this value must be between 0 and 255.

null

 

min_session_imps

int

The minimum number of impressions per person per session. If set, this value must be between 0 and 255.

null

 

max_session_imps

int

The maximum number of impressions per person per session. If set, this value must be between 0 and 255.

null

 

max_day_imps

int

The maximum number of impressions per person per day. If set, this value must be between 0 and 255.

null

 
max_hour_imps
intThe maximum number of impressions per person per hour. If set, this value must be between 0 and 255. null 
max_week_imps
intThe maximum number of impressions per person per week. If set, this value must be between 0 and 255. null 
max_month_imps
intThe maximum number of impressions per person per month. If set, this value must be between 0 and 255. null 

min_minutes_per_imp

int

The minimum number of minutes between impressions per person. This field may not be set to 0.

null

 

max_page_imps

int

The maximum number of impressions per page load from a single advertiser.

Only applies to mtj ad calls (Customer login required).

null

 
require_cookie_for_freq_capBooleanIndicates whether you want to serve only to users that use cookies in order to maintain your frequency cap settings (because we cannot track the number of impressions without cookies). A value of true indicates you will not serve to non-cookie users and maintain the frequency settings. A value of false indicates you will serve to non-cookie users and ignore the frequency cap settings for those users.true 

Targeting

When multiple targets are set, only inventory that satisfies all targeting criteria is eligible. For example, if you target intended audience general and inventory sources x, y, and z, then the profile will only target general audience inventory from inventory sources x, y, and z. Note that you may not specify both the segment_targets and segment_group_targets fields in any POST or PUT calls (only one of the two may be specified).

Please be aware that some targets accept an array of objects rather than integers or strings. The format can be found in the examples at the bottom of this page.

Field

Type

Description

Default

Required On

daypart_timezone

string

The timezone to be used with the daypart_targets. For more details, see API Timezones. Note that null is equivalent to the user's timezone.

null

 

daypart_targets

array of objects

The day parts during which to serve the campaign. See Daypart Targets below for more details. Note that if you do not set any daypart targets, the campaign will serve on all days of the week at all times.

  

segment_targets

 

array of objects

If you use segment_targets and edit the associated campaign in the AppNexus Console, the segments will be converted to a group in the segment_group_targets array. Therefore, it's recommended to use segment_group_targets when working via the API.

The segment IDs to target, each of which has an associated action (include or exclude). You define the Boolean logic between segments with the segment_boolean_operator field outside of the array. See Segment Targets below for more details and an example.

  

segment_group_targets

array of objects

The segment groups to target. Whereas the segment_targets array allows you to define Boolean logic between individual segments, this array allows you to establish groups of segments, defining Boolean logic between the groups as well as between the segments within each group. You define the Boolean logic between groups with the segment_boolean_operator field outside of the array; you define the Boolean logic between segments in a group with the boolean_operator field within the group object. See Segment Group Targets below for more details and an example.

Null segments cannot be added

You may not add null segments to this array via POST or PUT.

  

segment_boolean_operator

enum

If using segment_targets, this defines the Boolean logic between the segments specified. If using segment_group_targets, this defines the Boolean logic between the segment groups (the Boolean logic between segments in a group is defined directly in the segment_group_targets array). Possible values: and or or.

and

 

age_targets

array of objects

The list of age ranges to target for this profile. The allow_unknown field is available as a Boolean in order to account for ad calls where the age of the user is not available. See the Age Targets section below for more description and examples.

  

gender_targets

object

The gender targeting used for the profile. Possible values for gender are m or f. The allow_unknown field is available as a Boolean in order to account for ad calls where the gender of the user is not available. See the Gender Targets section below.

  

country_targets

array of objects

The country IDs to be either excluded or included in a profile, as defined by the country_action field. You can use the Country Service to retrieve a list of country IDs. See Country Targets for more details and format.

 

POST/PUT, when country_action is include

country_action

enum

Action to be taken on the country_targets list. Possible values: include or exclude.

exclude

 

region_targets

array of objects

The region/state IDs to be either excluded or included in a profile, as defined by the region_action field. You can use the Region Service to retrieve a list of region IDs. See Region Targets for more details and format.

 

POST/PUT, when region_action is include

region_action

enum

Action to be taken on the region_targets list. Possible values: include or exclude.

exclude

 

dma_targets

array of objects

The IDs of designated market areas to be either excluded or included in a profile, as defined by the dma_action field. You can use the Designated Market Area Service to retrieve a list of DMA IDs. Format example:

  

dma_action

enum

Action to be taken on the dma_targets list. Possible values: include or exclude.

exclude

 

city_targets

array of objects

The IDs of cities to be either included or excluded in a profile, as defined by the city_action field. You can use the City Service to retrieve a list of city IDs. See City Targets for more details and format.

 

POST/PUT, when city_action is include

city_action

enum

Action to be taken on the city_targets list. Possible values: include or exclude.

exclude

 

domain_targets

array of objects

List of domains to be either included or excluded in a profile, as defined by the domain_action field. See the example below for format.

  

domain_action

enum

Action to be taken on the domain_targets list. For details on domains, please see Working with Targeting Lists (Customer login required). Possible values: include or exclude.

exclude

 

domain_list_targets

array of objects

The IDs of domains lists to either include or exclude in a profile, as defined by the domain_list_action field. You can use the Domain List Service to retrieve domain list IDs. See the example below for format. Note: You can use no more than 100 domain lists in a single profile.

  

domain_list_action

enum

Action to be taken on the domain_list_targets list. For details on domains, please see Working with Targeting Lists (Customer login required). Possible values: include or exclude.

exclude

 

platform_placement_targets

array of objects

RTB or other Networks' inventory you can target. You can use Inventory Resold or Reporting services to find platform placements.

  

size_targets

array of objects

List of eligible sizes to be included in the profile.

The sizes are in an array size objects, each object containing the width and height of each target size:

Note: When you enable roadblocking on a guaranteed line item, this value is combined with creative sizes on the line item and campaign to produce forecasting. The size with the lowest forecasted number of impressions will be returned as the forecasted capacity.

  
seller_member_group_targetsarray of objects

The seller member groups to be excluded or included in a profile. To target AppNexus Direct, the format is:

  

member_targets

array of objects

Seller member IDs to be either excluded or included in a profile. The specific format can be found in the example at the bottom of the page.

  

member_default_action

enum

Deprecated

null

 
video_targets object

Video target IDs to be included in a profile. See Video Targets below for the specific format.

  
engagement_rate_targetsarray of objects

Target specific, highly performant inventory based on historic performance. See Engagement Rate Targets below for details.

null 

publisher_targets

array of objects

Managed/direct publisher IDs to be either excluded or included in a profile. The specific format can be found in the example at the bottom of the page.

  

site_targets

array of objects

The sites IDs to be either excluded or included in a profile. Exclude or include is inherited from the publisher_targets field. The specific format can be found in the example at the bottom of the page.

If you do not provide action with site_targets, action will default to NULL and profile.inventory_action will be used.

 

placement_targets

array of objects

The placement IDs to be either excluded or included in a profile. Exclude or include is inherited from the publisher_targets field. The specific format can be found in the example at the bottom of the page.

If you do not provide action with placement_targets, action will default to NULL and profile.inventory_action will be used.

 

inventory_action

enum

Action to be taken on the inventory_targets, publisher_targets, site_targets, and placement_targets list. Possible values: include or exclude. If action is include, then any targeted publisher, site, or placement will be included.

exclude

 

content_category_targets

object with string and array

The content categories to target for this profile as well as whether to allow unknown categories. See Content Category Targets below for more details and format. To retrieve content category IDs, use the Content Category Service.

  

deal_targets

array of objects

The deal IDs to be targeted by this profile. A deal is an agreement between a seller and buyer that may provide the buyer preferential pricing, access to exclusive inventory, reduced competition on inventory, or other opportunities. See Deal Targets below for more details and format.

  

platform_publisher_targets

array of objects

Third party publisher IDs to be either excluded or included in a profile. See the Inventory Resold Service for a list of IDs.

  

platform_content_category_targets

array of objects

List of network resold content categories to target for this profile. See the Inventory Resold Service for a list of IDs.

  

use_inventory_attribute_targets

Boolean

If true, the profile will allow inventory that has the sensitive attributes included in inventory_attribute_targets.

false

 

trust

enum

Indicates the level of audit which inventory must meet in order to be eligible. Possible values: appnexus or "seller". If this field is set to "appnexus", the allow_unaudited field must be set to false.

seller

 

allow_unaudited

Boolean

If true, this profile will allow unaudited inventory to pass targeting. If the trust field is set to appnexus, this must be set to false.

This setting overrides the seller trust settings in the inventory_trust object of the Member Service.

false

 

session_freq_type

enum

Indicates how the number of impressions seen by the user are counted during the current browsing session. Possible values: platform (across all publishers in the current session) or publisher (for the specific publisher).

platform

 

inventory_attribute_targets

array of objects

The IDs of inventory attributes to target for this profile. You can use the Inventory Attribute Service to retrieve a list of IDs.

  

intended_audience_targets

array of strings

The intended audience targets. Possible values: general, children, young_adult, or mature. Note that you can only choose to include (not exclude) intended audience targets.

Example:

To use the intended audience targeting, default_trust under inventory_trust (an attribute under the member) must be set to seller. Without this setting, the intended audience targeting will not be applied.

  

language_targets

array of objects

The IDs of the browser languages to either include or exclude in the profile, as defined by the language_action field. You can use the Language Service to retrieve language IDs.

  

language_action

enum

Action to be taken on language_targets. Possible values: include or exclude.

exclude

 

querystring_targets

array of objects

The query string targets to either include or exclude in the profile, as defined by the querystring_action field.

  

querystring_action

enum

Action to be taken on the querystring_targets. Possible values: include or exclude.

exclude

 

querystring_boolean_operator

enum

Boolean logic to be applied to the querystring_targets. Possible values: and or or.

and

 
postal_code_targets array of objects

The postal code IDs to target. For example:

IDs can be fetched using the Postal Code Service.

  

zip_targets

array of objects

Deprecated. Use postal_code_targets instead.

 

  

supply_type_targets

array of strings

The type(s) of supply to either include in or exclude from targeting, as defined by the supply_type_action field. Possible values: web, mobile_web and mobile_app.

Note: The facebook_sidebar option has been deprecated.

  

supply_type_action

enum

Supply types are web, mobile_web, and mobile_app. Possible values: include or exclude. If this field is set to include, only inventory of types included in supply_type_targets will be targeted. If exclude, only inventory not in supply_type_targets will be targeted (except facebook_sidebar, which has been deprecated).

exclude

 

user_group_targets

object

Every user is randomly assigned to 1 of 100 user groups, no group holding any advantage over another. You can use this field to target a specific range of these user groups. Also, you can use the include_cookieless_users field to include or exclude users without cookies. See the View a profile example below for formatting. Note that the User Group Pattern Service can help you calculate your user group targets.

The most common use for user group targets is defining user groups for A/B testing (customer login required) of campaign targeting strategies. Here's how it works: You set test user group targets in one profile and control user group targets in another. Then you apply the user group label to each affected campaign, using the label to identify the user group as test or control (see the labels field in the Campaign Service). Then you run the Network Analytics, Network Advertiser Analytics, or Advertiser Analytics report grouped by user_group_for_campaign to rank how campaigns performed by user group.

  
position_targetsobjectThe fold positions to target. See Position Targets below for more details.  

browser_targets

array of objects

The IDs of browsers to either include in or exclude from your targeting, as defined by the browser_action field. You can use the Browser Service to retrieve a list of browser IDs. See the example below for the format.

  

browser_action

enum

Action to be taken on the browser_targets. Possible values: include or exclude.

exclude

 

location_target_latitude

double

The latitude of the user's location. This must be between -90 and 90, with up to 6 decimal places, where south is negative and north is positive. A profile can be targeted to a specific location when GPS data is available from a mobile device. When lat/long targeting is set, users will only be targeted within the area defined by the center (location_target_latitude, location_target_longitude) and radius location_target_radius. Users will not be targeted when GPS data is not available for the impression.

  

location_target_longitude

double

The longitude of the user's location. This must be between -180 and 180, with up to 6 decimal places, where west is negative and east is positive. A profile can be targeted to a specific location when GPS data is available from a mobile device. When lat/long targeting is set, users will only be targeted within the area defined by the center (location_target_latitude, location_target_longitude) and radius location_target_radius. Users will not be targeted when GPS data is not available for the impression.

  

location_target_radius

integer length in meters

See location_target_latitude for more information.

  

device_model_targets

array of objects

The models of mobile devices (i.e., iPhone) to either include in or exclude from your targeting, as defined by the device_model_action field. To retrieve a complete list of device models registered in the AppNexus system, use the read-only Device Model Service. See Device Model Targets below for more details and format.

  

device_model_action

enum

Action to be taken on device_model_targets. Possible values: include or exclude.

exclude

 

device_type_targets

array of strings

The types of devices to either include in or exclude from your targeting, as defined by the device_type_action field.

Possible values:

  • phone
  • tablet
  • pc
  • tv
  • gameconsole
  • stb

See Device Type Targets below for format.

  

device_type_action

enum

Action to be taken on device_type_targets. Possible values: include or exclude.

exclude

 

carrier_targets

array of objects

The mobile carriers to either include in or exclude from your targeting, as defined by the carrier_action field. To retrieve a complete list of mobile carriers registered in the AppNexus system, use the read-only Carrier Service. See Carrier Targets below for more details and format.

  

carrier_action

enum

Action to be taken on the carrier_targets. Possible values: include or exclude.

exclude

 
inventory_url_list_targets array of objects

Contains a list of inventory list IDs (whitelists and/or blacklists). Used to attach a single whitelist and/or one or more blacklists to the profile.

  • The whitelist contains a list of domains or apps to be targeted by the line item using the profile. If a whitelist is included, domains and apps not in the whitelist will not be targeted.
  • Each blacklist contains a list of domains or apps that are to be excluded from targeting by line item that uses the profile.

See Inventory Lists for more details.

  

operating_system_family_targets

array of objects

The operating systems as a whole (e.g., Android, Apple iOS, Windows 7, etc.) to either include in or exclude from your targeting, as defined by the operating_system_family_action field. Note that this field is used to target all versions of operating systems, whereas operating_system_extended_targets is used to target specific versions of operating systems. See Operating System Family Targets below for more details and format.

  

operating_system_family_action

enum

Action to be taken on operating_system_family_targets. Possible values: include or exclude.

exclude

 

use_operating_system_extended_targeting

Boolean

Read-only. If true, the operating_system_extended_targets field will be respected.

By default, newer profiles will have this field set to true. However, older profiles (and any "newer" profiles created by duplicating them) will have this field set to false by default.

There is no way to update an older profile (or its duplicates) to set this field to true. If you want add OS extended targeting to these old profiles (or their duplicates), you must create a new profile and add your targeting settings to the new profile.

true

 

operating_system_extended_targets

array of objects

The list of specific operating systems to either include in or exclude from your targeting. Note that this array is used to target specific operating system versions, whereas operating_system_family_targets is used to target all versions of operating systems. See Operating System Extended Targets below for more details and format.

This field will be respected only if use_operating_system_extended_targeting is true.

  

operating_system_action

enum

Deprecated. Please use operating_system_extended_targets instead.

"exclude" 

operating_system_targets

array of objects

Deprecated. Please use operating_system_extended_targets instead.

  
mobile_app_instance_targetsarray of objectsA list of mobile app instances that you'd like to include or exclude from targeting. For field definitions, see Mobile App Instance Targets below. For more details about what mobile app instances are and how they work, see the Mobile App Instance Service.  
mobile_app_instance_action_includeBooleanWhether to include the mobile app instances defined in mobile_app_instance_targets in your campaign targeting.false 
mobile_app_instance_list_targetsarray of objectsThis list contains mobile app instance lists (in other words, it's a list of lists). For field definitions, see Mobile App Instance List Targets below. For more information about mobile app instance lists are and how they work, see the Mobile App Instance List Service.  
mobile_app_instance_list_action_includeBooleanWhether to include the mobile app instance lists defined in mobile_app_instance_list_targets in your campaign targeting.false 
deal_action_include Boolean

Whether to include or exclude deals in campaign and/or line item targeting.

To target or exclude deals, in addition to setting this field to true or false, you must also:

  • provide a list of deals to include or exclude in the deal_targets array. An empty list would either target no deals (if deal_action_include is set to true) or target all deals (if deal_action_include is set to false).
  • (only when using ALIs) set the deals field to true within the supply_strategies array of the Line Item Service
true 
ip_range_list_targetsarray of objectsA list of IP address ranges to be included or excluded from campaign targeting. For more information, see IP Range List Targets below, as well as the documentation for the IP Range List Service.  
key_value_targets
array of objects

A list of custom key/value targets. For details and examples, see Key Value Targets below.

 

  
ad_slot_position_action_include
BooleanIntent to target specific slots in an ad pod. Note that you can target ad slots or ad bumpers, but not both.
false
 
ad_slot_position_targets
array of intsThe ad slot positions a buyer wants to serve on. -1 represents the last position, 0 represents the first. By default when ad_slot_position_action_include is set to false, an empty array means spending can happen on any position. Set ad_slot_position_action_include to true first if you want to use ad_slot_position_targets to specify positions to target.
empty array
 
ad_slot_intro_bumper_action_include
Boolean

This controls if the creative will target video intro positions for VAST video auctions. The default is true. To ensure that your creative does not target the intro adpod position, set this field to false. Note that you can target ad slots or ad bumpers, but not both.

true
 
ad_slot_outro_bumper_action_include
Boolean

This controls if the creative will target video outro positions for VAST video auctions. The default is true. To ensure that your creative does not target the outro adpod position, set this field to false . Note that you can target ad slots or ad bumpers, but not both.

true
 
screen_size_action stringDeprecated."exclude" 
screen_size_targets array of objectsDeprecated.  
optimization_zone_action stringNot currently supported."exclude" 
optimization_zone_targets array of objectsNot currently supported.  
created_on timestampRead-only. The date and time when the profile was created.  
is_expired BooleanRead-only. If true, the object associated with the profile is expired. This field is only for internal purposes.false 
inventory_network_resold_targets array of objectsDeprecated.  
exelate_targets array of objectsDeprecated.  
inventory_url_whitelist_settingsobjectThis object contains fields used to determine how whitelists are applied to line item buying. See Inventory URL Whitelist Settings.  

Mobile App Instance Targets

For more information about mobile app instances, including instructions on adding them to your profile, see the Mobile App Instance Service.

Field

Type

Description

id

int

The unique ID of the mobile app instance.

bundle_id

string

The bundle ID of this mobile app instance.

os_family_id

int

The OS family ID associated with this mobile app instance.

Mobile App Instance List Targets

For more information about mobile app instance lists, including instructions on adding them to your profile, see the Mobile App Instance List Service.

Field

Type

Description

id

int

The unique ID of the mobile app instance list.

name

string

The name of this mobile app instance list.

description

string

An optional description of the list's purpose or contents.

Daypart Targets

Each object in the daypart_targets array includes the following fields. See the View a profile example below for formatting.

Field

Type

Description

day

enum

The day of the week. Possible values: sunday, monday, tuesday, wednesday, thursday, friday, saturday, or all. Note that these strings must be in lower case.

start_hour

int

The start hour for the daypart. This must be an integer between 0 and 23. The campaign will start serving at the beginning of the hour (6 is equivalent to "6:00" am).

end_hour

int

The end hour for the daypart. This must be an integer between 0 and 23. The campaign will stop serving at the end of the hour (23 is equivalent to "23:59").

Segment Targets

You define the Boolean logic between segments with segment_boolean_operator field outside of the array. If segment_boolean_operator is AND, then the profile will only target users that satisfy all segment targets. If the segment_boolean_operator is OR, then the profile will target users that satisfy any of the specified segments. For detailed guidance on Boolean logic for segment targeting, see Segment Targeting (Customer login required).

Field

Type

Description

Default

Required On

id

int

The ID of the segment.

 

POST

code

string

The custom code for the segment.

  

action

enum

Possible values: include or exclude.

include

 

start_minutes

int

The lower bound for the amount of time since a user was added to the segment.

0

 

expire_minutes

int

The upper bound for the amount of time since a user was added to the segment.

-1

 

other_equals

int

The exact segment value to target. Note: If you use other_in_list, you cannot use this field.

null

 

other_less

int

The non-inclusive upper bound for segment value targeting.

null

 

other_greater

int

The non-inclusive lower bound for segment value targeting

null

 

other_in_list

array

The list of segment values to target. Note: If you use other_equals, you cannot use this field.

null

 

For other_equals, other_less, other_greater, and other_in_list, the segment value can be an "other" value passed by the segment pixel (customer login required) or can be related to segment query string values (see the "querystring_mapped" field in the Segment Service). For examples of how to target query string values in a segment, see other examples below.

Example

In this example, since the segment_boolean_operator is AND, the profile will target only users that fit in both segment 86 and segment 202.

Segment Group Targets

Each segment group object contains the following fields. Note that you define the Boolean logic between groups with the segment_boolean_operator field outside of the array, and you define the Boolean logic between segments in a group with the boolean_operator field within the group object. See the example below for formatting and for an example of the logic of combining segment_boolean_operator and boolean_operator. For detailed guidance on Boolean logic for segment targeting, see Segment Targeting (Customer login required).

Null segments cannot be added

You may not add null segments to this array via POST or PUT.

Field

Type

Description

Default

Required On

boolean_operator

enum

The Boolean logic between segments in a segment group. Possible values: and or or.

or

POST

id

int

The ID of the segment.

 

POST

code

string

The custom code for the segment.

  

action

enum

Possible values: include or exclude.

include

 

start_minutes

int

The lower bound for the amount of time since a user was added to the segment.

0

 

expire_minutes

int

The upper bound for the amount of time since a user was added to the segment.

-1

 

other_equals

string

The exact segment value to target. Note: If you use other_in_list, you cannot use this field.

null

 

other_less

int

The non-inclusive upper bound for segment value targeting.

null

 

other_greater

int

The non-inclusive lower bound for segment value targeting

null

 

other_in_list

array

The list of segment values to target. Note: If you use other_equals, you cannot use this field.

null

 

For other_equals, other_less, other_greater, and other_in_list, the segment value can be an "other" value passed by the segment pixel (customer login required) or can be related to segment query string values (see the "querystring_mapped" field in the Segment Service). For examples of how to target query string values in a segment, see other examples below.

Example

In this example, since the segment_boolean_operator is OR and the boolean_operator for each group is AND, the profile will target only users that fit in both segment 11 and segment 22 or both segment 33 and segment 44.

Age Targets

FieldTypeDescriptionDefaultRequired On
allow_unknownBooleanDetermines whether to include targets where age is not know.False 
agesarray of objectsThe age ranges targeted in this profile.  

ages object:

Field

Type

Description

low

int

The lower bound of the age range (min 13).

high

int

The upper bound of the age range (max 100).

Example:


Gender Targets

The gender_targets object contains the following fields.

Field

Type

Description

Default

Required On

gender

enum

The gender of the user. Possible values: m (male), or f (female).

null

POST

allow_unknownBooleanIf true, target ad calls where the gender of the user is not available.false 

Country Targets

Each object in the country_targets array contains the following fields.

Field

Type

Description

idintThe ID of the country. You can use the Country Service to retrieve a complete list of country IDs.
namestringRead-only. The name of the country.
codestringRead-only. The code for the country.


Example

Region Targets

Each object in the region_targets array contains the following fields.

Field

Type

Description

idintThe ID of the region. You can use the Region Service to retrieve a list of region IDs.
namestringRead-only. The name of the region.
codestringRead-only. The code for the region.
country_namestringRead-only. The name of the country to which the region belongs.
country_codestringRead-only. The code for the country to which the region belongs.


Example

City Targets

Each object in the city_targets array contains the following fields.

Field

Type

Description

id

int

The ID of the city to target. You can use the City Service to retrieve a list of city IDs.

name

int

Read-only. The name of the city to target.

region_name

string

Read-only. The name of the region to which the city belongs.

region_code

string

Read-only. The code of the region to which the city belongs.

country_name

enum

Read-only. The name of the country to which the region belongs.

country_code

enum

Read-only. The code of the country to which the region belongs.


Example

Inventory Lists

Each object in the inventory_url_list_targets array includes the following fields.

Field

Type

Description

Required on
deletedbooleanRead-only. Indicates whether the inventory list has been deleted. 

id

int

The ID of the whitelist or blacklist to be applied.

  • The whitelist contains a list of domains and apps to be targeted by the line item that uses the profile.
  • Each blacklist contains a list of domains and apps to be excluded from targeting by the line item that uses the profile.
POST, PUT
list_typestring Read-only. Denotes whether the list is a blacklist or whitelist. Valid values are whitelist or blacklist. 
namestring Read-only. Name of the whitelist or blacklist. 

Example

 

Content Category Targets

The content_category_targets object includes the allow_unknown field, which is a Boolean, and the content_category array. Each object in the content_category array contains the following fields.

Field

Type

Description

Default

Required On

id

int

The ID of the content category to target.

null

POST

action

num

The action to take for this content category. Possible values: include or exclude. If "include, then category will be targeted; if exclude, the category will explicitly not be targeted.

exclude

 

Example

Video Targets

The video_targets object contains the allow_unknown_playback_method, allow_unknown_context, allow_unknown_player_size fields and the playback_methods , contexts , player_sizes arrays.

Field

Type

Description

Default

allow_unknown_playback_method

Boolean

Use this field to target inventory where the playback method is unknown. Set this field to true when using the fields of the playback_method array to target specific playback methods AND when you want to include inventory for which no playback method information has been provided.

If you are not targeting specific playback methods, this field will have no effect on targeting.

false

allow_unknown_context

Boolean

Use this field to target inventory where the context is unknown. Set this field to true when using the fields of the contexts array to target specific contexts AND when you want to include inventory for which no context information has been provided.

If you are not targeting specific contexts, this field will have no effect on targeting.

false
allow_unknown_player_size Boolean

Use this field to target inventory where the player size is unknown. Set this field to true when using the fields of the player_sizes array to target specific player sizes AND when you want to include inventory for which no player size information has been provided.

If you are not targeting specific player sizes, this field will have no effect on targeting.

false

When you do NOT set any specific video targeting options, you will target all inventory, including undefined inventory.

Ensure that you have elected to include or exclude intro and outro creatives by setting them in the ad_slot_intro_bumper_action_include and ad_slot_outro_bumper_action_include fields.


Contexts

The default value is an empty array, and will target any roll position. The contexts array contains objects with the following fields:

Field

Type

Description

id

int

The ID of the context. Possible values:

  • 1: position-pre-roll

  • 2: position-mid-roll

  • 3: position-post-roll

  • 4: outstream

name

string

Read-only. Possible values: pre-roll, mid-roll, post-roll, or outstream.


Playback Methods

The default value is an empty array, and will target any playback method. The playback_methods array contains the following fields:

Field

Type

Description

id

int

The ID of the playback method. Possible values:

  • 1: playback-method-auto-play-sound-on

  • 2: playback-method-auto-play-sound-off

  • 3: playback-method-click-to-play
  • 4: playback-method-mouse-over
  • 5: playback-method-auto-play-sound-unknown

name

string

Read-only. Possible values: auto_play_sound_on, auto_play_sound_off, click_to_play, mouse_over, or auto_play_sound_unknown.

 

Player Sizes

The default value is an empty array, and will target any player size. The player_sizes array contains objects with the following fields:

Field

Type

Description

id

int

The ID of the player size. Possible values:

  • 1: player-size-sm

  • 2: player-size-med

  • 3: player-size-lg

name

string

Read-only. Possible values: small, medium, or large.

min_widthintRead-only. The minimum width of the player, in pixels.
max_widthintRead-only. The maximum width of the player, in pixels.

Example

Engagement Rate Targets

The engagement_rate_targets array of objects is used to target specific, highly performant inventory based on historic performance. You can use targeting criteria to purchase either video inventory with a high completion rate, or highly viewable inventory, by specifying the desired video completion rate or viewability rate.

Field

Type

Description

engagement_rate_type

enum

The targeting criteria. Possible values:

  • 1: video_completion - Video Completion Rate. A prediction of how likely a video impression is to be fully played (video completes/total impressions).
  • 2: view - Predicted IAB Viewability Rate (previously known as  "Estimated IAB Viewthrough Rate"). A prediction of how likely a web display impression is to be viewable (viewed/measured impressions), judged by the IAB standard.
  • 3: view_over_total - Predicted IAB Viewability Rate Over Total. A prediction of how likely a web display impression is to be viewable (viewed/total impressions), judged by the IAB standard.
  • 4: predicted_iab_video_view_rate - Predicted IAB Video Viewability Rate. A prediction of how likely a web video impression is to be viewable (viewed/measured impressions), judged by the IAB standard.

  • 5: predicted_iab_video_view_rate_over_total - Predicted IAB Video Viewability Rate Over Total A prediction of how likely a web video impression is to be viewable (viewed/total impressions), judged by the IAB standard.

  • 6: predicted_100pv50pd_video_view_rate - Predicted Video Viewability Rate (100% View, 50% Duration, Sound On). A prediction of how likely a web video impression is to be viewable (viewed/measured impressions), judged by this custom standard (100% viewable, 50% duration, sound on).

  • 7: predicted_100pv50pd_video_view_rate_over_total - Predicted Video Viewability Rate Over Total (100% View, 50% Duration, Sound On). A prediction of how likely a web video impression is to be viewable (viewed/total impressions), judged by this custom standard (100% viewable, 50% duration, sound on).

  • 8: predicted_100pv1s_display_view_rate - Predicted Viewability Rate (100% View). A prediction of how likely a web display impression is to be viewable (viewed/measured impressions), judged by this custom standard (100% viewable, 1 second).

  • 9: predicted_100pv1s_display_view_rate_over_total - Predicted Viewability Rate Over Total (100% View). A prediction of how likely a web display impression is to be viewable (viewed/total impressions), judged by this custom standard (100% viewable, 1 second).

engagement_rate_pct

int

Possible values: 1 - 100.

Deal Targets

Each object in the deal_targets array contains the following fields.

To target or exclude deals, in addition to setting the fields within this array as needed, you must also:

  • set the deal_action_include field to true or false (depending on inclusion or exclusion)
  • (only when using ALIs) set the deals field to true within the supply_strategies array of the Line Item Service

Field

Type

Description

id

int

The ID of the deal. To retrieve the IDs of your deals, use the Deal Buyer Access Service.

name

string

Read-only. The name of the deal.

codestringRead-only. The custom code for the deal. For deals with external supply partners, this is generally the string that you will use to identify the deal.

Example

Position Targets

The position_targets object contains the following fields.

Field

Type

Description

Default

allow_unknown

Boolean

If true, the profile will target placements for which the fold position is not known.

false

positions

array of objects

The fold positions to target. Possible values: "above" or "below".

 


Example

Device Model Targets

Each object in the device_model_targets array contains the following fields.

To retrieve the IDs of device models registered in the AppNexus system, use the Device Model Service.

Field

Type

Description

id

int

The ID of the device model.

name

string

Read-only. The name of the device model, i.e., Onetab XST2, PAD7, A101, etc.


Example

Device Type Targets

The device_type_targets array can contain one or more of the following strings:

  • phone
  • tablet
  • pc
  • tv
  • gameconsole
  • stb

Example

Carrier Targets

Each object in the carrier_targets array contains the following fields.

To retrieve the IDs of mobile carriers registered in the AppNexus system, use the Carrier Service.

The ability to target by carrier refers to the fact that you can target devices currently using that carrier's network. You are not able to target subscribers of the network.

For example, a Verizon iPhone using a 4G network can be targeted as Verizon when on 4G, but not when the user is connected to their home wifi.

Field

Type

Description

id

int

The ID of the mobile carrier.

name

string

Read-only. The name of the mobile carrier.

country

enum

Read-only. The ISO code for the country in which the carrier operates.


Example

IP Range List Targets

For more information about IP range lists, see the IP Range List Service .

Per profile, you can target up to 10 "include" IP range lists (include set to true in the IP range list) and no more than 1 "exclude" IP range list (include set to false in the IP range list). The excluded IP ranges must be a subset of the included IP ranges.

Field

Type

Description

id

int

The unique ID of this IP range list.

name

string

Read-only. The name of this IP range list.

include

Boolean

Read-only. Whether to include or exclude the IP ranges in the IP range list. This is defined in the IP range list itself, not in the profile

description

string

Read-only. An optional description of the list's purpose or contents.

 

Operating System Extended Targets

The operating_system_extended_targets array specifies operating system versions (e.g., Android 3.x, Apple iOS 6, etc.) to either include in or exclude from your targeting. Note that this array is used to target specific operating system versions, whereas operating_system_family_targets is used to target all versions of operating systems.

OS Family Targets and OS Extended Targets Work Together

The OS Family and OS Extended Targets are most effective when used together. For examples of how to use their combined targeting capabilities, see the example Use OS Family Targets and OS Extended Targets together below.

To use operating_system_extended_targets, you must set use_operating_system_extended_targeting to true. Once a profile is created using the operating_system_extended_targets, you will not be allowed to set use_operating_system_extended_targeting to false or populate the operating_system_targets fields on PUT.

Each object in the operating_system_extended_targets array contains the following fields.

Field

Type

Description

id

int

The ID of the operating system version. To retrieve the IDs of operating system versions registered in the AppNexus system, use the Operating System Extended Service .

name

string

Read-only. The name of the operating system version, e.g., Android 3.x, Apple iOS 5, etc.

action

enum

Action to be taken on id. Possible values: include or exclude.


Example

Operating System Family Targets

The operating_system_family_targets array specifies the operating systems as a whole (e.g., Android, Apple iOS, Windows 7, etc.) to either include in or exclude from your targeting, as defined by the operating_system_family_action field. Note that this field is used to target all versions of operating systems, whereas operating_system_targets is used to target specific versions of operating systems.

OS Family Targets and OS Extended Targets Work Together

The OS Family and OS Extended Targets are most effective when used together. For examples of how to use their combined targeting capabilities, see the example Use OS Family Targets and OS Extended Targets together below.

Each object in the operating_system_family_targets array contains the following fields.

Field

Type

Description

id

int

The ID of the operating system family. To retrieve the IDs of operating system families registered in the AppNexus system, use the Operating System Family Service .

name

string

Read-only. The name of the operating system family, i.e., Microsoft Windows, Android, Apple iOS, etc.

Example

Key Value Targets

The key_value_targets field defines the combination of custom keys and values that are targeted in this profile. The field is a parsed version of a logical expression.

You can find more information on how key value targeting works and details on how to parse out expressions for the profile service at  Custom Key Value Targeting .

key_value_targets object


FieldTypeDescription
kv_expression
objectThis is a wrapper object that contains all the key/value targeting objects, including the header and exp objects.

Field

Type

Description

header
objectVersioning information used to evaluate the expression.
exp

object

The regular expression that defines the combination of key/values.

header object

FieldTypeValueDescription
an_version
string1.0

The version of the back-end engine evaluating the expression. Current version is 1.0. This field is required on PUT and POST.

client_version
string1.0

The version of the client-facing implementation of the expression (the format shown in the example below). Current version is 1.0. This field is required on PUT and POST.

exp object

FieldTypeDescription
typ
string

The operators used in the expression. Possible values include:

  • and
  • or
  • not
  • in
  • eq (equal to)
  • gt (greater than)
  • lt (less than)
  • gte (greater than or equal to)
  • lte (less than or equal to)
  • neq (not equal to)

The operators and, or, and not can be used only with sub-expressions.

The operators gt, lt, gte and lte can be used only with numeric values.

All operators must be lowercase.

sbe
exp object

An object containing the sub-expression (the elements of the expression).

key
stringThe name of the targeting key
vtp
type

This field identifies the data type of the expression value. The value you enter in this field must match the field and type of the corresponding value field. The following values are valid:

  • num - numeric; a value must be provided in the vnm field
  • str - string; a value must be provided in the vst field
  • nma - numeric array; a value must be provided in the vna field
  • sta - string array; a value must be provided in the vsa field
vnm
numeric valueThe value as a 32-bit signed float (for example, 25.3). Numbers can be up to 13 digits (with a maximum of six digits to the right of the decimal point).
vst
stringThe value as a string.
vna
array of numeric valuesA set of values as an array of floats.
vsa
array of stringsA set of values as an array of strings.

Example

Inventory URL Whitlist Settings

The fields in this object are used to set how whitelists attached to a line item will be applied. All whitelists will be applied to RTB buying by default. You can additionally choose to apply the whitelists to Managed buying as well.

FieldTypeDescriptionDefault
apply_to_managedboolean

Designates whether the whitelist is to be applied to managed buying. If set to true, any whitelists associated with the line item will be applied to managed buying.

Set this field to true if the line item associated with this profile has its inventory_type field set to direct.

false
apply_to_rtbbooleanRead-only. All whitelists associated with the line item will be applied to RTB buying.true

Example


Examples

View a profile
Target a range of query string values
Target a list of query string values
Target an exact query string value

Target specific countries

Target a specific state but exclude a DMA
Target a deal
Use OS Family Targets and OS Extended Targets together
Target Ad Pod Positions

Related Topics