Profile service overview

Article
02/12/2024

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.

REST API

HTTP Method	Endpoint	Description
`POST`	https://api.appnexus.com/profile?advertiser_id=ADVERTISER_ID&member_id=MEMBER_ID (profile JSON)	Add a new profile.
`POST`	https://api.appnexus.com/profile?advertiser_code=ADVERTISER_CODE (profile JSON)	Add a new profile.
`PUT`	https://api.appnexus.com/profile?id=PROFILE_ID&advertiser_id=ADVERTISER_ID&member_id=MEMBER_ID (profile JSON)	Modify an existing profile.
`PUT`	https://api.appnexus.com/profile?code=PROFILE_CODE&advertiser_code=ADVERTISER_CODE (profile JSON)	Modify an existing profile.
`GET`	https://api.appnexus.com/profile?advertiser_id=ADVERTISER_ID&member_id=MEMBER_ID	View all of the profiles for one of your advertisers.
`GET`	https://api.appnexus.com/profile?advertiser_code=ADVERTISER_CODE	View all of the profiles for one of your advertisers.
`GET`	https://api.appnexus.com/profile?id=PROFILE_ID&advertiser_id=ADVERTISER_ID&member_id=MEMBER_ID	View a specific profile for one of your advertisers.
`GET`	https://api.appnexus.com/profile?code=PROFILE_CODE&advertiser_code=ADVERTISER_CODE	View a specific profile for one of your advertisers.

Note

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

JSON fields

General

Field	Type	Description
`id`	int	The ID of the profile. Required: `PUT`, in query string.
`code`	string	Custom code for the profile.
`description`	string	Optional description.
`is_template`	Boolean	If `true`, the profile has been saved as a targeting template in. To get profiles that are targeting templates in, pass `is_template=true` in the query string of a `GET` call. For more details about targeting templates in, see "Managing Targeting Templates" within the app's Help System. Default: `false`
`last_modified`	timestamp	Time of last modification to this profile.
`is_archived`	boolean	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 as `true`, the value can't be changed and the only calls that can be made on the profile object are `GET` and `DELETE`. Note: If a profile's parent 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. Default: `false`
`archived_on`	timestamp	Read-only. The date and time on which the profile was archived (i.e., when the `is_archived` field was set to `true`). Default: `null`

Frequency

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

Field	Type	Description
`max_lifetime_imps`	int	The maximum number of impressions per person. If set, this value must be between `0` and `255`. Default: `null`
`min_session_imps`	int	The minimum number of impressions per person per session. If set, this value must be between `0` and `255`. Default: `null`
`max_session_imps`	int	The maximum number of impressions per person per session. If set, this value must be between `0` and `255`. Default: `null`
`max_day_imps`	int	The maximum number of impressions per person per day. If set, this value must be between `0` and `255`. Default: `null`
`max_hour_imps`	int	The maximum number of impressions per person per hour. If set, this value must be between `0` and `255`. Default: `null`
`max_week_imps`	int	The maximum number of impressions per person per week. If set, this value must be between `0` and `255`. Default: `null`
`max_month_imps`	int	The maximum number of impressions per person per month. If set, this value must be between `0` and `255`. Default: `null`
`min_minutes_per_imp`	int	The minimum number of minutes between impressions per person. This field may not be set to `0`. Default: `null`
`max_page_imps`	int	The maximum number of impressions per page load (seller's ad request). Note: Only relevant for multi-tag auctions (For example: /(ss)vmap). Default: `null`
`require_cookie_for_freq_cap`	Boolean	Indicates whether you'll exclusively serve to users with known identifiers to maintain your frequency cap settings. Setting this field to `true` indicates that you'll only serve ads to users with known identifiers, thereby maintaining your frequency cap settings. Setting this field to `false` indicates that you'll serve to anonymous users as well. If you've set a daily-occurring frequency cap, advanced frequency management will control impressions to anonymous users through modeling. Otherwise, frequency-cap settings won't apply to those users. Because this flag is only enforced when a frequency cap has been set, setting this field to `true` won't require identifiers for an object that has no active frequency-cap settings. Default: `true` Note: Advanced Frequency Management is currently not supported for Monetize users.

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

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

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.
For Programmatic Guaranteed Buying Line Items:
- You can only target one deal target (see Deal Targets below) and the allow_unaudited field must be set to true.
- Do not set any other targeting fields.
For Augmented Line Items, it is mandatory to set at least one country as geography targeting (See Country Targets below).
Effective August 30, 2021:
- TapAd's Graph will provide global coverage excluding Europe.
- Xandr's Graph will provide coverage for Europe and the United States.
  
  Adjust your code accordingly.

Field	Type	Description
`graph_id`	int	- `Null` if the line item is targeting your member seat's default graph selection. - `0` if the line item is targeting no graph. - `3` if the line item is targeting the TapAd Graph. - `4` if the line item is targeting the Xandr Graph. Note: For select EMEA Invest member seats included in the default cross-device pilot, there is a change to the `graph_id` field expectations. Passing `graph_id` as `Null` will now correspond to your member seat's default graph selection. For members in our EMEA pilot, this will be `graph_id = 4`. To disable cross-device targeting, these member seats will need to pass `graph_id = 0`.
`daypart_timezone`	string	The timezone to be used with the `daypart_targets`. For more details, see API Timezones. Note: `null` is equivalent to the user's timezone. Default: `null`
`daypart_targets`	array of objects	The day parts during which to serve the campaign. For more details, see Daypart Targets below. Note: 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	Note: If you use `segment_targets` and edit the associated campaign in our UI, 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. For more details, see Segment Targets and example below.
`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. For more details, see Segment Group Targets and an example below. Note: Null segments cannot be added. You may not add `null` segments to this array using `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`. Default: `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. For more description and examples, see the Age Targets section below.
`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. For more details and format, see Country Targets. Required: `POST`/`PUT`, when `country_action` is include.
`country_action`	enum	Action to be taken on the `country_targets` list. Possible values: `include` or `exclude`. Default: `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. For more details and format, see Region Targets below. Required On: `POST`/`PUT`, when `region_action` is `include`.
`require_transparency_and_consent_framework_string`	boolean	- If `true`, only allow associated objects to purchase inventory where valid TCF string is present. - If `false`, allow associated objects to purchase any inventory that falls within pre-defined targeting declarations. - This is only supported on advertiser level as targeting at other levels may lead to undefined behavior. Note: This parameter is only applicable to the traffic coming from territories where GDPR applies. Default: `false`
`region_action`	enum	Action to be taken on the `region_targets` list. Possible values: `include` or `exclude`. Default: `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. See format example.
`dma_action`	enum	Action to be taken on the `dma_targets` list. Possible values: include or exclude. Default: `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. For more details and format, see City Targets below. Required On: `POST`/`PUT`, when `city_action` is `include`.
`city_action`	enum	Action to be taken on the `city_targets` list. Possible values: `include` or `exclude`. Default: `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. For format, see the example below.
`domain_action`	enum	Action to be taken on the `domain_targets` list. For details on domains, see the Create a Domain or App List in documentation. Possible values: `include` or `exclude`. Default: `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, see Working with Targeting Lists in documentation. Possible values: `include` or `exclude`. Default: `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. See example below. 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_targets`	array of objects	The seller member groups to be excluded or included in a profile. To target Xandr's direct supply, see the format below.
`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. Default: `null`
`video_targets`	object	Video target IDs to be included in a profile. For the specific format, see Video Targets below.
`engagement_rate_targets`	array of objects	Target specific, highly performant inventory based on historic performance. For details, see Engagement Rate Targets below. Default: `null`
`publisher_targets`	array of objects	Managed/direct publisher IDs to be either excluded or included in a profile.
`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. Default: 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. Default: 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. Default: `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. For more details and format, see Content Category Targets below. 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. For more details and format, see Deal Targets below. For more information on how the value of this field and the `deal_action_include` field affect targeting results, see Targeting Results for `deal_action_include` AND `deal_targets` fields below.
`deal_list_targets`	array of objects	The deal list IDs to be targeted by this profile. See example below. Deal list IDs can be fetched using the Deal List Service.
`platform_publisher_targets`	array of objects	Third party publisher IDs to be either excluded or included in a profile. For a list of IDs the Inventory Resold Service.
`platform_content_category_targets`	array of objects	List of network resold content categories to target for this profile. For a list of IDs, see the Inventory Resold Service.
`use_inventory_attribute_targets`	Boolean	If `true`, the profile will allow inventory that has the sensitive attributes included in `inventory_attribute_targets`. Default: `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`. Default: `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`. Note: - This setting overrides the seller trust settings in the `inventory_trust` object of the Member Service. - For Programmatic Guaranteed Buying Line Items, `allow_unaudited` must be set to `true`. Default: `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). Default: `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: You can only choose to include (not exclude) intended audience targets. See example. Note: 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`. Default: `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`. Default: `exclude`
`querystring_boolean_operator`	enum	Boolean logic to be applied to the `querystring_targets`. Possible values: `and` or `or`. Default: `and`
`postal_code_targets`	array of objects	The postal code IDs to target. See example. IDs can be fetched using the Postal Code Service.
`postal_code_list_targets`	array of objects	The postal code list IDs to target. See example. IDs can be fetched using the Postal Code List Service.
`postal_code_action_include`	boolean	Whether to include the postal codes defined in `postal_code_targets`, postal code lists defined in `postal_code_list_targets` in your targeting, and political districts defined in `political_district_targets`. Default: `true`
`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). Default: `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. For formatting, see the View a profile example below. Note: 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 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_targets`	object	The fold positions to target. For more details, see Position Targets below.
`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. For the format, see the example below.
`browser_action`	enum	Action to be taken on the `browser_targets`. Possible values: `include` or `exclude`. Default: `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	For more information, see `location_target_latitude`.
`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 our system, use the read-only Device Model Service. For more details and format, see Device Model Targets below.
`device_model_action`	enum	Action to be taken on `device_model_targets`. Possible values: `include` or `exclude`. Default: `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` - `mediaplayer` For format, see Device Type Targets below.
`device_type_action`	enum	Action to be taken on `device_type_targets`. Possible values: `include` or `exclude`. Default: `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 our system, use the read-only Carrier Service. For more details and format, see Carrier Targets below.
`carrier_action`	enum	Action to be taken on the `carrier_targets`. Possible values: `include` or `exclude`. Default: `exclude`
`inventory_url_list_targets`	array of objects	Contains a list of inventory list IDs (allowlists and/or blocklists). Used to attach a single allowlist and/or one or more blocklists to the profile. - The allowlist contains a list of domains or apps to be targeted by the line item using the profile. If an allowlist is included, domains and apps not in the allowlist will not be targeted. - Each blocklist contains a list of domains or apps that are to be excluded from targeting by line item that uses the profile. For more details, see Inventory Lists below.
`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: 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. For more details and format, see Operating System Family Targets below.
`operating_system_family_action`	enum	Action to be taken on `operating_system_family_targets`. Possible values: `include` or `exclude`. Default: `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. Default: `true`
`operating_system_extended_targets`	array of objects	The list of specific operating systems to either include in or exclude from your targeting. Note: This array is used to target specific operating system versions, whereas `operating_system_family_targets` is used to target all versions of operating systems. For more details and format, see Operating System Extended Targets below. Note: This field will be respected only if `use_operating_system_extended_targeting` is `true`.
`operating_system_action`	enum	Deprecated. Use `operating_system_extended_targets` instead. Default: `exclude`
`operating_system_targets`	array of objects	Deprecated. Use `operating_system_extended_targets` instead.
`mobile_app_instance_targets`	array of objects	A 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_include`	Boolean	Whether to include the mobile app instances defined in `mobile_app_instance_targets` in your campaign targeting. Default: `false`
`mobile_app_instance_list_targets`	array of objects	This 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_include`	Boolean	Whether to include the mobile app instance lists defined in `mobile_app_instance_list_targets` in your campaign targeting. Default: `false`
`deal_action_include`	Boolean	Whether to include or exclude deals defined in `deal_targets` and deal lists defined in `deal_list_targets` in campaign and/or line item targeting. When set to `true`, deals and deal lists will be included. Note: To target or exclude deals and deal lists, in addition to setting this field to `true` or `false`, you must also: - Provide a list of deals and deal lists to include or exclude in the `deal_targets` and `deal_list_targets` array. An empty list would either target no deals/deal lists (if `deal_action_include` is set to `true`) or target all deals/deal lists (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. For more information on how the value of this field and the `deal_targets` field affect targeting results, see Targeting Results for `deal_action_include` AND `deal_targets` fields. Default: `true`
`ip_range_list_targets`	array of objects	A 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`	Boolean	Intent to target specific slots in an ad pod. Note that you can target ad slots or ad bumpers, but not both. Default: `false`
`ad_slot_position_targets`	array of ints	The 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. Default: `empty row`
`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: You can target ad slots or ad bumpers, but not both. Default: `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: You can target ad slots or ad bumpers, but not both. Default: `true`
`screen_size_action`	string	Deprecated. Default: `exclude`
`screen_size_targets`	array of objects	Deprecated.
`optimization_zone_action`	string	Not currently supported. Default: `exclude`
`optimization_zone_targets`	array of objects	Not currently supported.
`created_on`	timestamp	Read-only. The date and time when the profile was created.
`is_expired`	Boolean	Read-only. If `true`, the object associated with the profile is expired. This parameter is only supported for internal purposes. Default: `false`
`inventory_network_resold_targets`	array of objects	Deprecated.
`exelate_targets`	array of objects	Deprecated.
`inventory_url_allowlist_settings`	object	This object contains fields used to determine how allowlists are applied to line item buying. See Inventory URL Allowlist Settings.
`ads_txt_authorized_only`	Boolean	When `true`, the line item will only target web inventory from authorized sellers of domains that have an ads.txt file. Note: The `ads_txt_authorized_only` targeting parameter only applies to Open Exchange inventory. It does not affect targeting of deal inventory. It also does not apply to app inventory (since use of an `ads.txt` file for app inventory has not yet been adopted by the industry). For more information, see Ads.txt FAQ for Buyers. Default: `false`
`political_district_targets`	array of objects	The political district IDs to target. See example. IDs can be fetched using the Political District Service.

`dma_targets` format

{
   "dma_targets":[
      {
         "dma":612
      },
      {
         "dma":622
      }
   ]
}

`domain_targets` format

{
   "domain_targets":[
      {
         "profile_id":128350561,
         "domain":"telenet.be"
      },
      {
         "profile_id":99898705,
         "domain":"cnn.us"
      }
   ]
}

`size_targets` example

{
   "size_targets":[
      {
         "width":190,
         "height":213
      },
      {
         "width":728,
         "height":90
      }
   ]
}

`seller_member_group_targets` format

{
   "seller_member_group_targets":[
      {
         "id":1,
         "action_include":"true/false"
      }
   ]
}

`deal_list_targets` example

{
   "profile":{
      "id":1367515,
      "deal_list_targets":[
         {
            "id":"0101"
         },
         {
            "id":"0102"
         }
      ]
   }
}

`intended_audience_targets` example

{
   "intended_audience_targets":[
      "children",
      "general"
   ]
}

`postal_code_targets` example

{
   "profile":{
      "id":1367515,
      "postal_code_targets":[
         {
            "id":"00135"
         },
         {
            "id":"00136"
         }
      ]
   }
}

`postal_code_list_targets` example

{
   "profile":{
      "id":1367515,
      "postal_code_list_targets":[
         {
            "id":"0099"
         },
         {
            "id":"0100"
         }
      ]
   }
}

`political_district_targets` example

{
   "profile":{
      "id":130465799,
      "political_district_targets":[
         {
            "id":"139897"
         }
      ]
   }
}

Targeting results for `deal_action_include` AND `deal_targets` fields

The following targeting results occur for these values of the deal_action_include AND deal_targets fields:

`deal_action_include`	`deal_targets`	Targeting Result
`true`	`null`	Target no deals
`false`	`null`	Target all deals
`true`	Contains deal targets	Include these deals in targeting
`false`	Contains deal targets	Exclude these deals in targeting

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. For formatting, see the View a profile example below.

Field	Type	Description
`day`	enum	The day of the week. Possible values: `sunday`, `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, or `all`. Note: 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.

Field	Type	Description
`id`	int	The ID of the segment. Required On: `POST`
`code`	string	The custom code for the segment.
`action`	enum	Possible values: `include` or `exclude`. Default: `include`
`start_minutes`	int	The lower bound for the amount of time since a user was added to the segment. Default: `0`
`expire_minutes`	int	The upper bound for the amount of time since a user was added to the segment. Default: `-1`
`other_equals`	int	The exact segment value to target. Note: If you use `other_in_list`, you cannot use this field. Default: `null`
`other_less`	int	The non-inclusive upper bound for segment value targeting. Default: `null`
`other_greater`	int	The non-inclusive lower bound for segment value targeting. Default: `null`
`other_in_list`	array	The list of segment values to target.If you use `other_equals`, you cannot use this field. Default: `null`

Note

For other_equals, other_less, other_greater, and other_in_list, the segment value can be an "other" value passed by the segment pixel 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.

In segment targeting, you need to keep the settings for the Boolean logic consistent, otherwise you would not be able to edit the segments in Microsoft Invest UI. For consistent Boolean logic settings, you need to ensure that:

segment_boolean_operator field is set as either “and” or “or”.
The boolean_operator field in each object of the segment_group_targets array (See Segment Group Targets) is set as either “and” or “or”. However this value should be the opposite of what is set in segment_boolean_operator above. For example, if the value set in segment_boolean_operator is "or", the value of boolean_operator for the objects should be "and".
The value of boolean_operator field for all objects in the segment_group_targets array needs to be same. In short, you cannot have boolean_operator of one object as "and" and other as "or" in the same profile. For an example of consistent and inconsistent JSONs, see below.

Consistent JSONs

{
   "segment_boolean_operator":"and",
   "segment_group_targets":[
      {
         "boolean_operator":"or",
         "segments":[
            {
               "action":"include",
               "code":"1094797",
               "deleted":false,
               "expire_minutes":null,
               "id":19285936,
               "name":"Travel Intender",
               "other_equals":null,
               "other_greater":null,
               "other_in_list":null,
               "other_less":null,
               "start_minutes":null
            },
            {
               "action":"include",
               "code":"3119772",
               "deleted":false,
               "expire_minutes":null,
               "id":19378950,
               "name":"XAS - US HH Demographic - Online Shopping - Travel",
               "other_equals":null,
               "other_greater":null,
               "other_in_list":null,
               "other_less":null,
               "start_minutes":null
            },
            {
               "action":"include",
               "code":"6502105",
               "deleted":false,
               "expire_minutes":null,
               "id":19378951,
               "name":"XAS - US HH Demographic - Online Shopping - Electronics and Gadgets",
               "other_equals":null,
               "other_greater":null,
               "other_in_list":null,
               "other_less":null,
               "start_minutes":null
            },
            {
               "action":"include",
               "code":"3734388",
               "deleted":false,
               "expire_minutes":null,
               "id":19378952,
               "name":"XAS - US HH Demographic - Online Shopping - Apparel",
               "other_equals":null,
               "other_greater":null,
               "other_in_list":null,
               "other_less":null,
               "start_minutes":null
            }
         ]
      },
      {
         "boolean_operator":"or",
         "segments":[
            {
               "action":"include",
               "code":"2137013",
               "deleted":false,
               "expire_minutes":null,
               "id":19378954,
               "name":"XAS - US HH Demographic - Online Shopping - Buy Online",
               "other_equals":null,
               "other_greater":null,
               "other_in_list":null,
               "other_less":null,
               "start_minutes":null
            },
            {
               "action":"include",
               "code":"2272811",
               "deleted":false,
               "expire_minutes":null,
               "id":19378955,
               "name":"XAS - US HH Demographic - Online Shopping - Personal Health",
               "other_equals":null,
               "other_greater":null,
               "other_in_list":null,
               "other_less":null,
               "start_minutes":null
            },
            {
               "action":"include",
               "code":"8578372",
               "deleted":false,
               "expire_minutes":null,
               "id":19378957,
               "name":"XAS - US HH Demographic - Online Shopping - Shoes",
               "other_equals":null,
               "other_greater":null,
               "other_in_list":null,
               "other_less":null,
               "start_minutes":null
            }
         ]
      },
      {
         "boolean_operator":"or",
         "segments":[
            {
               "action":"include",
               "code":"8578372",
               "deleted":false,
               "expire_minutes":null,
               "id":19378957,
               "name":"XAS - US HH Demographic - Online Shopping - Shoes",
               "other_equals":null,
               "other_greater":null,
               "other_in_list":null,
               "other_less":null,
               "start_minutes":null
            },
            {
               "action":"include",
               "code":"4608982",
               "deleted":false,
               "expire_minutes":null,
               "id":21015599,
               "name":"Xandr Audiences - Demographic - Occupation - Detail - Attorneys",
               "other_equals":null,
               "other_greater":null,
               "other_in_list":null,
               "other_less":null,
               "start_minutes":null
            },
            {
               "action":"include",
               "code":"2420395",
               "deleted":false,
               "expire_minutes":null,
               "id":21015602,
               "name":"Xandr Audiences - Demographic - Occupation - Detail - Accountants/CPA",
               "other_equals":null,
               "other_greater":null,
               "other_in_list":null,
               "other_less":null,
               "start_minutes":null
            }
         ]
      }
   ]
}

Inconsistent JSONs

{
   "segment_boolean_operator":"and",
   "segment_group_targets":[
      {
         "boolean_operator":[
            "and",
            "- - same as segment_boolean_operator + also all other boolean_operators in the rest of the object is set to",
            "or",
            "therefore this is inconsistent behavior"
         ],
         "segments":[
            {
               "action":"include",
               "code":"1094797",
               "deleted":false,
               "expire_minutes":null,
               "id":19285936,
               "name":"Travel Intender",
               "other_equals":null,
               "other_greater":null,
               "other_in_list":null,
               "other_less":null,
               "start_minutes":null
            },
            {
               "action":"include",
               "code":"3119772",
               "deleted":false,
               "expire_minutes":null,
               "id":19378950,
               "name":"XAS - US HH Demographic - Online Shopping - Travel",
               "other_equals":null,
               "other_greater":null,
               "other_in_list":null,
               "other_less":null,
               "start_minutes":null
            },
            {
               "action":"include",
               "code":"6502105",
               "deleted":false,
               "expire_minutes":null,
               "id":19378951,
               "name":"XAS - US HH Demographic - Online Shopping - Electronics and Gadgets",
               "other_equals":null,
               "other_greater":null,
               "other_in_list":null,
               "other_less":null,
               "start_minutes":null
            },
            {
               "action":"include",
               "code":"3734388",
               "deleted":false,
               "expire_minutes":null,
               "id":19378952,
               "name":"XAS - US HH Demographic - Online Shopping - Apparel",
               "other_equals":null,
               "other_greater":null,
               "other_in_list":null,
               "other_less":null,
               "start_minutes":null
            }
         ]
      },
      {
         "boolean_operator":"or",
         "segments":[
            {
               "action":"include",
               "code":"2137013",
               "deleted":false,
               "expire_minutes":null,
               "id":19378954,
               "name":"XAS - US HH Demographic - Online Shopping - Buy Online",
               "other_equals":null,
               "other_greater":null,
               "other_in_list":null,
               "other_less":null,
               "start_minutes":null
            },
            {
               "action":"include",
               "code":"2272811",
               "deleted":false,
               "expire_minutes":null,
               "id":19378955,
               "name":"XAS - US HH Demographic - Online Shopping - Personal Health",
               "other_equals":null,
               "other_greater":null,
               "other_in_list":null,
               "other_less":null,
               "start_minutes":null
            },
            {
               "action":"include",
               "code":"8578372",
               "deleted":false,
               "expire_minutes":null,
               "id":19378957,
               "name":"XAS - US HH Demographic - Online Shopping - Shoes",
               "other_equals":null,
               "other_greater":null,
               "other_in_list":null,
               "other_less":null,
               "start_minutes":null
            }
         ]
      },
      {
         "boolean_operator":"or",
         "segments":[
            {
               "action":"include",
               "code":"8578372",
               "deleted":false,
               "expire_minutes":null,
               "id":19378957,
               "name":"XAS - US HH Demographic - Online Shopping - Shoes",
               "other_equals":null,
               "other_greater":null,
               "other_in_list":null,
               "other_less":null,
               "start_minutes":null
            },
            {
               "action":"include",
               "code":"4608982",
               "deleted":false,
               "expire_minutes":null,
               "id":21015599,
               "name":"Xandr Audiences - Demographic - Occupation - Detail - Attorneys",
               "other_equals":null,
               "other_greater":null,
               "other_in_list":null,
               "other_less":null,
               "start_minutes":null
            },
            {
               "action":"include",
               "code":"2420395",
               "deleted":false,
               "expire_minutes":null,
               "id":21015602,
               "name":"Xandr Audiences - Demographic - Occupation - Detail - Accountants/CPA",
               "other_equals":null,
               "other_greater":null,
               "other_in_list":null,
               "other_less":null,
               "start_minutes":null
            }
         ]
      }
   ]
}

Segment targets 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.

{
   "profile":{
      "segment_boolean_operator":"and",
      "segment_targets":[
         {
            "id":86,
            "code":null,
            "name":"Network segment 1",
            "action":"include",
            "start_minutes":0,
            "expire_minutes":-1,
            "other_less":null,
            "other_greater":null,
            "other_equals":null
         },
         {
            "id":202,
            "code":null,
            "name":"Credit Score segment",
            "action":"include",
            "start_minutes":0,
            "expire_minutes":-1,
            "other_less":null,
            "other_greater":null,
            "other_equals":null
         }
      ]
   }
}

Segment group targets

Each segment group object contains the following fields.

Note

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.

Null segments cannot be added.

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

Field	Type	Description
`boolean_operator`	enum	The boolean logic between segments in a segment group. Possible values: `and` or `or`. The value of `boolean_operator` field for all objects in the `segment_group_targets` array needs to be same. In short, you cannot have `boolean_operator` of one object as `"and"` and other as `"or"` in the same profile. Default: `or` Required: `POST`
`id`	int	The ID of the segment. Required: `POST`
`code`	string	The custom code for the segment.
`action`	enum	Possible values: `include` or `exclude`. Default: `include`
`start_minutes`	int	The lower bound for the amount of time since a user was added to the segment. Default: `0`
`expire_minutes`	int	The upper bound for the amount of time since a user was added to the segment. Default: `-1`
`other_equals`	string	The exact segment value to target. Note: If you use `other_in_list`, you cannot use this field. Default: `null`
`other_less`	int	The non-inclusive upper bound for segment value targeting. Default: `null`
`other_greater`	int	The non-inclusive lower bound for segment value targeting. Default: `null`
`other_in_list`	array	The list of segment values to target. Note: If you use `other_equals`, you cannot use this field. Default: `null`

Note

For other_equals, other_less, other_greater, and other_in_list, the segment value can be an "other" value passed by the segment pixel 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.

Segment group targets 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.

{
   "profile":{
      "segment_boolean_operator":"or",
      "segment_group_targets":[
         {
            "boolean_operator":"and",
            "segments":[
               {
                  "id":11,
                  "code":null,
                  "action":"include",
                  "start_minutes":0,
                  "expire_minutes":-1,
                  "other_equals":null,
                  "other_less":null,
                  "other_greater":null
               },
               {
                  "id":22,
                  "code":null,
                  "action":"include",
                  "start_minutes":0,
                  "expire_minutes":-1,
                  "other_equals":null,
                  "other_less":null,
                  "other_greater":null
               }
            ]
         },
         {
            "boolean_operator":"and",
            "segments":[
               {
                  "id":33,
                  "code":null,
                  "action":"include",
                  "start_minutes":0,
                  "expire_minutes":-1,
                  "other_equals":null,
                  "other_less":null,
                  "other_greater":null
               },
               {
                  "id":44,
                  "code":null,
                  "action":"include",
                  "start_minutes":0,
                  "expire_minutes":-1,
                  "other_equals":null,
                  "other_less":null,
                  "other_greater":null
               }
            ]
         }
      ]
   }
}

Age targets

Field	Type	Description
`allow_unknown`	Boolean	Determines whether to include targets where age is not know. Default: `false`
`ages`	array of objects	The 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).

Age targets example

{
   "profile":{
      "age_targets":{
         "allow_unknown":false,
         "ages":[
            {
               "low":20,
               "high":35
            }
         ]
      }
   }
}

Gender targets

The gender_targets object contains the following fields.

Field	Type	Description
`gender`	enum	The gender of the user. Possible values: `m` (male), or `f` (female). Default: `null` Required On: `POST`
`allow_unknown`	Boolean	If `true`, target ad calls where the gender of the user is not available. Default: `false`

Country targets

Each object in the country_targets array contains the following fields.

Field	Type	Description
`id`	int	The ID of the country. You can use the Country Service to retrieve a complete list of country IDs.
`name`	string	Read-only. The name of the country.
`code`	string	Read-only. The code for the country.

Country targets example

{
   "profile":{
      "country_action":"include",
      "country_targets":[
         {
            "id":233,
            "name":"United States",
            "code":"US"
         }
      ]
   }
}

Region targets

Each object in the region_targets array contains the following fields.

Field	Type	Description
`id`	int	The ID of the region. You can use the Region Service to retrieve a list of region IDs.
`name`	string	Read-only. The name of the region.
`code`	string	Read-only. The code for the region.
`country_name`	string	Read-only. The name of the country to which the region belongs.
`country_code`	string	Read-only. The code for the country to which the region belongs.

Region targets example

{
   "profile":{
      "region_action":"include",
      "region_targets":[
         {
            "id":3950,
            "name":"New York",
            "code":"NY",
            "country_name":"United States",
            "country_code":"US"
         }
      ]
   }
}

Field	Type	Description
`require_transparency_and_consent_framework_string`	boolean	- If `true`, only allow associated objects to purchase inventory where valid TCF string is present - If `false`, allow associated objects to purchase any inventory that falls within pre-defined targeting declarations.

Note

This parameter is only applicable to the traffic coming from territories where GDPR applies.

Example

{
   "profile":{
      "require_transparency_and_consent_framework_string":"false"
   }
}

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.

City targets example

{
   "profile":{
      "city_action":"include",
      "city_targets":[
         {
            "id":200942,
            "name":"Portland",
            "region_name":"Oregon",
            "region_code":"OR",
            "country_code":"US",
            "country_name":"United States"
         }
      ]
   }
}

Inventory lists

Each object in the inventory_url_list_targets array includes the following fields.

Field	Type	Description
`deleted`	Boolean	Read-only. Indicates whether the inventory list has been deleted.
`id`	int	The ID of the allowlist or blocklist to be applied. - The allowlist contains a list of domains and apps to be targeted by the line item that uses the profile. - Each blocklist contains a list of domains and apps to be excluded from targeting by the line item that uses the profile. Required On: `POST`, `PUT`
`list_type`	string	Read-only. Denotes whether the list is a blocklist or allowlist. Valid values are `allowlist` or `blocklist`. Note: The `list_type` field (used by the Inventory List Service) is not used by the Profile Service for determining whether an inventory list is excluded (`blocklist`) in targeting or included (`allowlist`). For excluding or including an inventory list in targeting, see `exclude` field in this table.
`name`	string	Read-only. Name of the allowlist or blocklist.
`exclude`	Boolean	Read-only. If `true`, the inventory list will be excluded from targeting (i.e., treated as a blocklist). If `false`, the inventory list will be included in targeting (i.e., treated as an allowlist). This field is solely dependent on the inventory `list_type` field described above.

Inventory lists example

{
   "profile":{
      "id":145,
      "inventory_url_list_targets":[
         {
            "deleted":false,
            "id":51,
            "list_type":"blocklist",
            "name":"Blocklist to exclude medical sites",
            "exclude":true
         },
         {
            "deleted":false,
            "id":53,
            "list_type":"blocklist",
            "name":"Blocklist to exclude military sites",
            "exclude":true
         },
         {
            "deleted":false,
            "id":54,
            "list_type":"blocklist",
            "name":"Line Item - Blocklist - 2017-08-23T21:44:42Z",
            "exclude":true
         },
         {
            "deleted":false,
            "id":66,
            "list_type":"allowlist",
            "name":"Test Allowlist for Targeting",
            "exclude":false
         }
      ]
   }
}

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
`id`	int	The ID of the content category to target. Default: `null` Required On: `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. Default: `exclude`

Content category targets example

{
   "profile":{
      "content_category_targets":{
         "allow_unknown":false,
         "content_categories":[
            {
               "id":3,
               "action":"include"
            }
         ]
      }
   }
}

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. For Deals, it also contains the deal_creative_duration field and the video_frameworks arrays.

Field	Type	Description
`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. Default: `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. Default: `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. Default: `false`

Note

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_width`	int	Read-only. The minimum width of the player, in pixels.
`max_width`	int	Read-only. The maximum width of the player, in pixels.

Creative duration

The deal_creative_duration setting is only used by video deal line items. It lets deals target impressions that allow at least a given creative duration, so creatives of the defined length can successfully serve through a deal without errors. It will aggregate only the impressions with the given setting already in place.

Field	Type	Description
`deal_creative_duration`	int	The duration of the video creative in seconds.

Video frameworks

The video_frameworks array is only used by video deal line items. It lets deals target impressions that allow a given video framework (for example, VPAID) so creatives of this type can successfully serve through a deal without errors. This setting won’t override existing placement settings; it will aggregate only the impressions with the given setting already in place.

Field	Type	Description
`id`	int	The id of the video framework. IDs include: - `VPAID 1.0` - `VPAID 2.0` - `MRAID-1` - `ORMMA` - `MRAID-2`
`name`	string	The name of the video framework. Possible values: - `vpaid_1_0` - `vpaid_2_0` - `mraid_1` - `ormma` - `mraid_2`

Video frameworks example

{
   "profile":{
      "video_targets":{
         "allow_unknown_playback_method":true,
         "allow_unknown_context":true,
         "allow_unknown_player_size":true,
         "contexts":[
            {
               "id":1,
               "name":"pre-roll"
            },
            {
               "id":2,
               "name":"mid-roll"
            },
            {
               "id":4,
               "name":"outstream"
            }
         ],
         "playback_methods":[
            {
               "id":2,
               "name":"auto_play_sound_off"
            },
            {
               "id":3,
               "name":"click_to_play"
            }
         ],
         "player_sizes":[
            {
               "id":1,
               "name":"small",
               "min_width":0,
               "max_width":300
            }
         ],
         "deal_creative_duration":60,
         "video_frameworks":[
            {
               "id":1,
               "name":"vpaid_1_0"
            },
            {
               "id":2,
               "name":"vpaid_2_0"
            }
         ]
      }
   }
}

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.

Note

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).
When using ALIs, set the deals field to true within the supply_strategies array of the Line Item Service.
Programmatic Guaranteed Buying Line Items can only have one deal target in the deal_targets array.

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.
`code`	string	Read-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.

Deal targets example

{
   "profile":{
      "deal_targets":[
         {
            "id":44,
            "name":"Deal with external supply partner",
            "code":"APN-1234-2200f"
         },
         {
            "id":45,
            "name":"Deal with UI seller",
            "code":null
         }
      ]
   }
}

Position targets

The position_targets object contains the following fields.

Field	Type	Description
`allow_unknown`	Boolean	If `true`, the profile will target placements for which the fold position is not known. Default: `false`
`positions`	array of objects	The fold positions to target. Possible values: `"above"` or `"below"`.

Position targets example

{
   "profile":{
      "position_targets":{
         "allow_unknown":false,
         "positions":[
            {
               "position":"above"
            }
         ]
      }
   }
}

Device model targets

Each object in the device_model_targets array contains the following fields.

Tip

To retrieve the IDs of device models registered in our 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.

Device model targets example

{
   "profile":{
      "device_model_action":"include",
      "device_model_targets":[
         {
            "id":1,
            "name":"Onetab XST2"
         },
         {
            "id":2,
            "name":"PAD7"
         },
         {
            "id":3,
            "name":"A101"
         }
      ]
   }
}

Device type targets

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

phone
tablet
pc
tv
gameconsole
stb
mediaplayer

Device type targets example

{
   "profile":{
      "device_type_action":"include",
      "device_type_targets":[
         "phone",
         "tablet"
      ]
   }
}

Carrier targets

Each object in the carrier_targets array contains the following fields.

Note

To retrieve the IDs of mobile carriers registered in our 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.

Carrier targets example

{
   "profile":{
      "carrier_action":"include",
      "carrier_targets":[
         {
            "id":14,
            "name":"Verizon - US",
            "country":"US"
         },
         {
            "id":26,
            "name":"Sprint - US",
            "country":"US"
         },
         {
            "id":32,
            "name":"Orange - US",
            "country":"US"
         }
      ]
   }
}

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

operating_system_extended_targets 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 Use OS Family Targets and OS Extended Targets together example 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 our 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`.

Operating system extended targets example

{
   "profile":{
      "use_operating_system_extended_targeting":true,
      "operating_system_extended_targets":[
         {
            "id":2,
            "name":"Android 2.1",
            "action":"exclude"
         },
         {
            "id":3,
            "name":"Android 2.2",
            "action":"include"
         }
      ]
   }
}

Operating system family targets

The operating_system_family_targets array specifies the operating systems as a whole (e.g., Android, Apple iOS, Windows 7, Windows 11 etc.) to either include in or exclude from your targeting, as defined by the operating_system_family_action field.

Note

operating_system_family_action 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 Use OS Family Targets and OS Extended Targets together example 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 our 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.

Operating system family targets example

{
   "profile":{
      "operating_system_family_action":"exclude",
      "operating_system_family_targets":[
         {
            "id":2,
            "name":"Android"
         },
         {
            "id":3,
            "name":"Apple iOS"
         }
      ]
   }
}

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

Field	Type	Description
`kv_expression`	object	This is a wrapper object that contains all the key/value targeting objects, including the `header` and `exp` objects.

Field	Type	Description
`header`	object	Versioning information used to evaluate the expression.
`exp`	object	The regular expression that defines the combination of key/values.

`header` object

Field	Type	Value	Description
`an_version`	string	`1.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`	string	`1.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

Field	Type	Description
`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`	string	The 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 value	The 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`	string	The value as a string.
`vna`	array of numeric values	A set of values as an array of floats.
`vsa`	array of strings	A set of values as an array of strings.

Key value targets example

{
   "profile":{
      "key_value_targets":{
         "kv_expression":{
            "header":{
               "an_version":"1.0",
               "client_version":"1.0"
            },
            "exp":{
               "typ":"and",
               "sbe":[
                  {
                     "exp":{
                        "typ":"eq",
                        "key":"fruit",
                        "vtp":"str",
                        "vst":"apple"
                     }
                  },
                  {
                     "exp":{
                        "typ":"eq",
                        "key":"city",
                        "vtp":"str",
                        "vst":"NY"
                     }
                  }
               ]
            }
         }
      }
   }
}

Inventory URL allowlist settings

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

Field	Type	Description
`apply_to_managed`	boolean	Designates whether the allowlist is to be applied to managed buying. If set to `true`, any allowlists associated with the line item will be applied to managed buying. Note: Set this field to `true` if the line item associated with this profile has its `inventory_type` field set to `direct`. Default: `false`
`apply_to_rtb`	boolean	Read-only. All allowlists associated with the line item will be applied to RTB buying. Default: `false`

Inventory URL allowlist settings example

{
   "inventory_url_allowlist_settings":{
      "apply_to_managed":true,
      "apply_to_rtb":true
   }
}

Examples

View a profile

This is an example of a profile service.

Note

For the sake of demonstration, this profile has an unrealistic targeting strategy.

$ curl -b cookies -c cookies 'https://api.appnexus.com/profile?id=439&advertiser_id=8&member_id=123'

{
   "response":{
      "status":"OK",
      "count":1,
      "start_element":0,
      "num_elements":100,
      "profile":{
         "id":37291837,
         "code":null,
         "description":null,
         "country_action":"include",
         "region_action":"exclude",
         "city_action":"exclude",
         "browser_action":"exclude",
         "ads_txt_authorized_only":false,
         "use_inventory_attribute_targets":true,
         "last_modified":"2015-07-17 20:01:56",
         "daypart_timezone":null,
         "dma_action":"exclude",
         "domain_action":"exclude",
         "domain_list_action":"include",
         "inventory_action":"exclude",
         "language_action":"include",
         "segment_boolean_operator":"or",
         "min_session_imps":null,
         "session_freq_type":"platform",
         "carrier_action":"exclude",
         "supply_type_action":"exclude",
         "device_type_action":"exclude",
         "screen_size_action":"exclude",
         "device_model_action":"exclude",
         "location_target_radius":null,
         "location_target_latitude":null,
         "location_target_longitude":null,
         "querystring_action":"exclude",
         "querystring_boolean_operator":"and",
         "is_expired":false,
         "non_audited_url_action":"include",
         "daypart_bitmap":"000000000000000000000000111111111111111111111000111111111111111111111000111111111111111111111000111111111111111111111000111111111111111111111000000000000000000000000000",
         "optimization_zone_action":"exclude",
         "advertiser_id":16401,
         "publisher_id":null,
         "max_session_imps":null,
         "max_day_imps":null,
         "max_lifetime_imps":100,
         "max_page_imps":null,
         "min_minutes_per_imp":30,
         "venue_action":"exclude",
         "operating_system_action":"exclude",
         "require_cookie_for_freq_cap":true,
         "trust":"seller",
         "allow_unaudited":false,
         "is_template":false,
         "created_on":"2015-07-17 20:01:56",
         "operating_system_family_action":"exclude",
         "use_operating_system_extended_targeting":true,
         "mobile_app_instance_action_include":false,
         "mobile_app_instance_list_action_include":true,
         "user_group_targets":{
            "include_cookieless_users":false,
            "groups":[
               {
                  "low":0,
                  "high":49
               }
            ]
         },
         "country_targets":[
            {
               "id":233,
               "name":"United States",
               "code":"US"
            }
         ],
         "region_targets":[
            {
               "id":3950,
               "name":"New York",
               "code":"NY",
               "country_name":"United States",
               "country_code":"US"
            }
         ],
         "city_targets":null,
         "inv_class_targets":null,
         "inventory_attribute_targets":[
            {
               "id":2,
               "name":"Political",
               "deleted":false
            },
            {
               "id":4,
               "name":"Social media",
               "deleted":false
            },
            {
               "id":6,
               "name":"Photo and video sharing",
               "deleted":false
            },
            {
               "id":8,
               "name":"Forums (moderated)",
               "deleted":false
            },
            {
               "id":10,
               "name":"Forums (unmoderated)",
               "deleted":false
            },
            {
               "id":12,
               "name":"Incentivized clicks",
               "deleted":false
            },
            {
               "id":14,
               "name":"Non-english languages",
               "deleted":false
            },
            {
               "id":16,
               "name":"Streaming media",
               "deleted":false
            },
            {
               "id":17,
               "name":"Toolbars, plugins, or extensions",
               "deleted":false
            },
            {
               "id":29,
               "name":"Contextual Nudity",
               "deleted":false
            }
         ],
         "age_targets":{
            "allow_unknown":false,
            "ages":[
               {
                  "low":18,
                  "high":24
               },
               {
                  "low":25,
                  "high":34
               },
               {
                  "low":35,
                  "high":44
               }
            ]
         },
         "daypart_targets":[
            {
               "day":"monday",
               "start_hour":0,
               "end_hour":20
            },
            {
               "day":"tuesday",
               "start_hour":0,
               "end_hour":20
            },
            {
               "day":"wednesday",
               "start_hour":0,
               "end_hour":20
            },
            {
               "day":"thursday",
               "start_hour":0,
               "end_hour":20
            },
            {
               "day":"friday",
               "start_hour":0,
               "end_hour":20
            }
         ],
         "browser_targets":[
            {
               "id":4,
               "name":"Internet Explorer (other versions)",
               "deleted":false
            },
            {
               "id":11,
               "name":"Opera (all versions)",
               "deleted":false
            }
         ],
         "dma_targets":null,
         "domain_targets":[
            {
               "profile_id":37291837,
               "domain":"test.com"
            }
         ],
         "domain_list_targets":[
            {
               "id":3905,
               "name":"Test Domain List 1",
               "description":"",
               "type":"white",
               "deleted":false
            }
         ],
         "language_targets":[
            {
               "id":1,
               "name":"English",
               "code":"EN",
               "deleted":false
            }
         ],
         "size_targets":null,
         "zip_targets":null,
         "member_targets":[
            {
               "id":1185,
               "action":"include",
               "third_party_auditor_id":null,
               "billing_name":"AppNexus Demo"
            }
         ],
         "video_targets":null,
         "segment_group_targets":[
            {
               "boolean_operator":"and",
               "segments":[
                  {
                     "id":465381,
                     "action":"include",
                     "start_minutes":null,
                     "expire_minutes":null,
                     "other_less":null,
                     "other_greater":null,
                     "other_equals":null,
                     "code":null,
                     "name":null,
                     "deleted":false,
                     "other_in_list":null
                  },
                  {
                     "id":465382,
                     "action":"include",
                     "start_minutes":null,
                     "expire_minutes":null,
                     "other_less":null,
                     "other_greater":null,
                     "other_equals":null,
                     "code":null,
                     "name":null,
                     "deleted":false,
                     "other_in_list":null
                  }
               ]
            },
            {
               "boolean_operator":"and",
               "segments":[
                  {
                     "id":514839,
                     "action":"exclude",
                     "start_minutes":null,
                     "expire_minutes":null,
                     "other_less":null,
                     "other_greater":null,
                     "other_equals":null,
                     "code":null,
                     "name":null,
                     "deleted":false,
                     "other_in_list":null
                  },
                  {
                     "id":523129,
                     "action":"include",
                     "start_minutes":null,
                     "expire_minutes":null,
                     "other_less":null,
                     "other_greater":null,
                     "other_equals":null,
                     "code":null,
                     "name":null,
                     "deleted":false,
                     "other_in_list":null
                  }
               ]
            }
         ],
         "carrier_targets":null,
         "supply_type_targets":null,
         "device_type_targets":null,
         "screen_size_targets":null,
         "device_model_targets":null,
         "querystring_targets":null,
         "gender_targets":null,
         "intended_audience_targets":[
            "general",
            "children",
            "young_adult"
         ],
         "inventory_network_resold_targets":null,
         "operating_system_targets":null,
         "operating_system_family_targets":[
            {
               "id":6,
               "name":"BlackBerry OS"
            },
            {
               "id":8,
               "name":"Linux"
            }
         ],
         "position_targets":{
            "allow_unknown":true,
            "positions":null
         },
         "site_targets":null,
         "venue_targets":null,
         "operating_system_extended_targets":null,
         "mobile_app_instance_targets":null,
         "mobile_app_instance_list_targets":[
            {
               "id":3,
               "name":"Mopub iOS Apps 1-100",
               "description":"",
               "deleted":false
            }
         ],
         "optimization_zone_targets":null,
         "content_category_targets":{
            "allow_unknown":false,
            "content_categories":[
               {
                  "id":7,
                  "action":"exclude",
                  "name":"Beauty and Personal Care",
                  "is_system":true,
                  "deleted":false
               },
               {
                  "id":10,
                  "action":"include",
                  "name":"Arts and Entertainment",
                  "is_system":true,
                  "deleted":false
               },
               {
                  "id":20344,
                  "action":"exclude",
                  "name":"",
                  "is_system":false,
                  "deleted":false
               },
               {
                  "id":22224,
                  "action":"include",
                  "name":"",
                  "is_system":false,
                  "deleted":false
               }
            ]
         },
         "deal_targets":null,
         "placement_targets":null,
         "platform_content_category_targets":null,
         "platform_placement_targets":null,
         "platform_publisher_targets":[
            {
               "id":500070,
               "action":"exclude",
               "name":"Mediaset",
               "deleted":false
            }
         ],
         "publisher_targets":null,
         "segment_targets":null,
         "exelate_targets":null,
         "ip_range_list_targets":null
      }
   }
}

Target a range of query string values

Scenario: Two auto publishers told you to expect "car year" data in the query strings of their placements. The first passes the year with the "car_year" parameter, and the second passes the year with the "car_YYYY" parameter. In order to target this information in your campaign, you added the "car_year" parameter to segment 25 and the "car_YYYY" parameter to segment 26. Now you want to update the campaign's profile to target placements that include either parameter when the parameter passes any year between "car_year=2009" and "car_year=2012", so you create the following JSON and make a PUT call to update the profile.

$ cat profile_update

{
   "profile":{
      "segment_group_targets":[
         {
            "boolean_operator":"or",
            "segments":[
               {
                  "id":25,
                  "code":null,
                  "action":"include",
                  "start_minutes":0,
                  "expire_minutes":-1,
                  "other_less":2012,
                  "other_greater":2009
               },
               {
                  "id":26,
                  "code":null,
                  "action":"include",
                  "start_minutes":0,
                  "expire_minutes":-1,
                  "other_less":2012,
                  "other_greater":2009
               }
            ]
         }
      ]
   }
}

$ curl -b cookies -c cookies -X PUT -d @profile_update 'https://api.appnexus.com/profile?id=9&advertiser_id=210&member_id=123'

{
   "response":{
      "status":"OK",
      "count":1,
      "id":9
   }
}

Target a list of query string values

Scenario: An auto publisher told you to expect any of the following key-values in the query strings of their placements: "car_make=ford", "car_make=honda", or "car_make=toyota". In order to target such information, you added the parameter and values to segment 12. Now you want to update the campaign's profile to target those values, so you create the following JSON and make a PUT call to update the profile.

$ cat profile_update

{
   "profile":{
      "segment_group_targets":[
         {
            "segments":[
               {
                  "id":12,
                  "code":null,
                  "action":"include",
                  "start_minutes":0,
                  "expire_minutes":-1,
                  "other_in_list":[
                     "ford",
                     "honda",
                     "toyota"
                  ]
               }
            ]
         }
      ]
   }
}

$ curl -b cookies -c cookies -X PUT -d @profile_update 'https://api..com/profile?id=10&advertiser_id=210&member_id=123'

{
   "response":{
      "status":"OK",
      "count":1,
      "id":10
   }
}

Target an exact query string value

Scenario: An auto publisher told you to expect the following key-values in the query strings of their placements: car_color=red, car_color=blue, or car_color=black. In order to target such information, you added the parameter and values to segment 15. Now you want to update the campaign's profile to target a specific query string value, black, so you create the following JSON and make a PUT call to update the profile.

$ cat profile_update

{
   "profile":{
      "segment_group_targets":[
         {
            "segments":[
               {
                  "id":15,
                  "code":null,
                  "action":"include",
                  "start_minutes":0,
                  "expire_minutes":-1,
                  "other_equals":"black"
               }
            ]
         }
      ]
   }
}

$ curl -b cookies -c cookies -X PUT -d @profile_update 'https://api..com/profile?id=10&advertiser_id=210&member_id=123'

{
   "response":{
      "status":"OK",
      "count":1,
      "id":10
   }
}

Target specific countries

Scenario: You want to target your profile to the United States and Canada. This requires setting country_action to include and country_targets to US and CA, so you create the following JSON and make a PUT call to update the profile.

$ cat profile_update

{
   "profile":{
      "country_action":"include",
      "country_targets":[
         {
            "id":233
         },
         {
            "id":39
         }
      ]
   }
}

$ curl -b cookies -c cookies -X PUT -d @profile_update 'https://api..com/profile?id=10&advertiser_id=210&member_id=123'

{
   "response":{
      "status":"OK",
      "count":1,
      "id":10
   }
}

Target a specific state but exclude a DMA

Scenario: You want to target your profile to the state of New York, excluding the New York City area. This requires setting region_action to include, region_targets to US:NY, dma_action to exclude, and dma_targets to 501, which is the DMA code for New York City. You therefore create the following JSON and make a PUT call to update the profile.

$ cat profile_update

{
   "profile":{
      "region_action":"include",
      "region_targets":[
         {
            "id":1
         }
      ],
      "dma_action":"exclude",
      "dma_targets":[
         {
            "dma":501
         }
      ]
   }
}

$ curl -b cookies -c cookies -X PUT -d @profile_update 'https://api..com/profile?id=10&advertiser_id=210&member_id=123'

{
   "response":{
      "status":"OK",
      "count":1,
      "id":10
   }
}

Target a deal

Scenario: You have negotiated a deal with a seller that grants you access to inventory that is not available to other buyers (i.e., a private auction). To take advantage of this deal, you need to use the Deal Buyer Access Service to find the deal ID and then update the deal_targets array of your profile to target that ID.

To find the ID for your deal, you make a GET call to the Deal Buyer Access Service and identify the right deal. Alternately, if you know the member ID of the seller, you can pass it in the query string to retrieve only deals you have with that seller, as shown below.

$ curl -b cookies -c cookies 'https://api.appnexus.com/deal-buyer-access?seller_member_id=814'

{
   "response":{
      "status":"OK",
      "count":1,
      "start_element":0,
      "num_elements":100,
      "deals":[
         {
            "id":65,
            "code":null,
            "name":"Private deal for buyer 1085 with floor of 2.5",
            "description":null,
            "active":true,
            "seller_member_id":814,
            "start_date":"2013-12-01 00:00:00",
            "end_date":"2013-12-31 23:59:59",
            "profile_id":null,
            "floor_price":2.5,
            "currency":"USD",
            "use_deal_floor":true,
            "last_modified":"2013-12-04 22:37:49",
            "buyer":{
               "id":1085,
               "bidder_id":2
            },
            "type":{
               "id":2,
               "name":"Private Auction"
            },
            "brands":[
               {
                  "id":1
               }
            ]
         }
      ]
   }
}

You then create the JSON file with deal_targets set to the ID of the deal.

$ cat profile_update

{
   "profile":{
      "deal_targets":[
         {
            "id":65
         }
      ]
   }
}

Finally, you make a PUT call to update the profile.

$ curl -b cookies -c cookies -X PUT -d @profile_update 'https://api.appnexus.com/profile?id=22&advertiser_id=210&member_id=123'

{
   "response":{
      "status":"OK",
      "count":1,
      "id":22
   }
}

Use OS family targets and OS extended targets together

The OS extended and OS family targets work in tandem to allow different targeting scenarios for specific operating system families. This functionality is best represented by usage examples. This section contains the following examples (scroll down or search to view them).

Target iOS 7.0 devices; all other OS families and other iOS versions will not serve.
Target all iOS devices regardless of version; all other OS families will not serve.
Target all OSes that are not Unknown, Linux, or Symbian.
Target all Android devices, along with iOS 7.0.
Target all Android and all iOS and all Windows Mobile.
Target Mac OS 10.8 (Mountain Lion) and MS Windows 8.0.
Target Mac OS X 10.8 (Mountain Lion) and all Windows Desktop except XP and 2000.
Target all iOS operating systems except 2.0 and 2.1.
Invalid configuration: Cannot include an OS family and exclude its members.
Invalid configuration: Cannot include and exclude members of the same OS family.
Invalid configuration: Cannot include members of an excluded OS family.

Target iOS 7.0 devices; all other OS families and other iOS versions will not serve

{
   "profile":{
      "operating_system_family_action":"include",
      "operating_system_family_targets":{
         
      },
      "operating_system_extended_targets":{
         "id":80,
         "name":"iOS 7.0",
         "action":"include"
      }
   }
}

Target all iOS devices regardless of version; all other OS families will not serve

{
   "profile":{
      "operating_system_family_action":"include",
      "operating_system_family_targets":{
         "id":3,
         "name":"Apple iOS"
      }
   },
   "operating_system_extended_targets":{
      
   }
}

Target all OS that are not Unknown, Linux, or Symbian

In other words, serve on any Android, iOS, MacOS, Windows, Blackberry, or Windows Mobile device.

{
   "profile":{
      "operating_system_family_action":"exclude",
      "operating_system_family_targets":[
         {
            "id":0,
            "name":"Unknown"
         },
         {
            "id":8,
            "name":"Linux"
         },
         {
            "id":9,
            "name":"Symbian OS"
         }
      ]
   }
}

Target all Android devices, along with iOS 7.0

All other iOS versions will not serve, and all non-Android devices will not serve.

{
   "profile":{
      "operating_system_family_action":"include",
      "operating_system_family_targets":{
         "id":2,
         "name":"Android"
      }
   },
   "operating_system_extended_targets":[
      {
         "id":80,
         "name":"iOS 7.0",
         "action":"include"
      }
   ]
}

Target all Android and all iOS and all Windows mobile

{
   "profile":{
      "operating_system_family_action":"include",
      "operating_system_family_targets":[
         {
            "id":2,
            "name":"Android"
         },
         {
            "id":3,
            "name":"Apple iOS"
         },
         {
            "id":7,
            "name":"Microsoft Mobile"
         }
      ],
      "operating_system_extended_targets":{
         
      }
   }
}

Target Mac OS 10.8 (Mountain Lion) and MS Windows 8.0

This example combines OS Extended Targets from different OS families.

{
   "profile":{
      "operating_system_family_action":"include",
      "operating_system_family_targets":{
         
      },
      "operating_system_extended_targets":[
         {
            "id":81,
            "name":"10.8 Mountain Lion",
            "action":"include"
         },
         {
            "id":93,
            "name":"Windows 8",
            "action":"include"
         }
      ]
   }
}

Target Mac OS X 10.8 (Mountain Lion) and all Windows Desktop except XP and 2000

{
   "profile":{
      "operating_system_family_action":"include",
      "operating_system_family_targets":{
         
      },
      "operating_system_extended_targets":[
         {
            "id":80,
            "name":"10.8 Mountain Lion",
            "action":"include"
         },
         {
            "id":89,
            "name":"Windows 2000",
            "action":"exclude"
         },
         {
            "id":90,
            "name":"Windows XP",
            "action":"exclude"
         }
      ]
   }
}

Target all iOS operating systems except 2.0 and 2.1

{
   "profile":{
      "operating_system_family_action":"include",
      "operating_system_family_targets":[
         {
            "id":3,
            "name":"Apple iOS"
         }
      ],
      "operating_system_extended_targets":[
         {
            "id":47,
            "action":"include",
            "name":"iOS 2.0"
         },
         {
            "id":48,
            "action":"include",
            "name":"iOS 2.1"
         }
      ]
   }
}

The following profile targeting configurations are invalid and may result in unexpected behavior.

Invalid configuration: Cannot include an OS family and exclude its members

{
   "profile":{
      "operating_system_family_action":"include",
      "operating_system_family_targets":[
         {
            "id":3,
            "name":"Apple iOS"
         }
      ],
      "operating_system_extended_targets":[
         {
            "id":47,
            "action":"include",
            "name":"iOS 2.0"
         },
         {
            "id":48,
            "action":"include",
            "name":"iOS 2.1"
         }
      ]
   }
}

Invalid configuration: Cannot include and exclude members of the same OS family

{
   "profile":{
      "operating_system_family_action":"include",
      "operating_system_family_targets":{
         
      },
      "operating_system_extended_targets":[
         {
            "id":47,
            "name":"iOS 2.0",
            "action":"include"
         },
         {
            "id":48,
            "name":"iOS 2.1",
            "action":"exclude"
         }
      ]
   }
}

Invalid configuration: Cannot include members of an excluded OS family

{
   "profile":{
      "operating_system_family_action":"include",
      "operating_system_family_targets":[
         {
            "id":3,
            "name":"Apple iOS"
         }
      ],
      "operating_system_extended_targets":[
         {
            "id":47,
            "action":"include",
            "name":"iOS 2.0"
         },
         {
            "id":48,
            "action":"include",
            "name":"iOS 2.1"
         }
      ]
   }
}

Target ad pod positions

{
   "profile":{
      "ad_slot_intro_bumper_action_include":false,
      "ad_slot_outro_bumper_action_include":false,
      "ad_slot_position_action_include":true,
      "ad_slot_position_targets":[
         -1,
         0,
         2
      ]
   }
}

Target only bumper positions (intro and outro)

{
   "profile":{
      "ad_slot_position_action_include":true,
      "ad_slot_position_targets":[],
      "ad_slot_intro_bumper_action_include":true,
      "ad_slot_outro_bumper_action_include":true
   }
}

Target any ad pod slot

{
   "profile":{
      "ad_slot_position_action_include":false,
      "ad_slot_position_targets":[],
      "ad_slot_intro_bumper_action_include":false,
      "ad_slot_outro_bumper_action_include":false
   }
}

Exclude all ad pod slots and bumpers

This behavior is not something you will want to replicate; you will not serve on anything.

{
   "profile":{
      "ad_slot_position_action_include":true,
      "ad_slot_position_targets":[],
      "ad_slot_intro_bumper_action_include":false,
      "ad_slot_outro_bumper_action_include":false
   }
}

Target only the intro bumper

{
   "profile":{
      "ad_slot_position_action_include":true,
      "ad_slot_position_targets":[],
      "ad_slot_intro_bumper_action_include":true,
      "ad_slot_outro_bumper_action_include":false
   }
}

The following profile targeting configurations are invalid and may result in unexpected behavior.

Invalid configuration: Cannot target all ad slots and all bumper positions

{
   "profile":{
      "ad_slot_position_action_include":false,
      "ad_slot_position_targets":[],
      "ad_slot_intro_bumper_action_include":true,
      "ad_slot_outro_bumper_action_include":true
   }
}

Target a Programmatic Guaranteed deal

Scenario: You have negotiated a Programmatic Guaranteed deal (PG deal) with a seller and would like to target this deal with a PG buying line item. You'll need to create a PG deal profile using the PG deal ID. You then must associate this profile with a PG buying line item to target the deal (see the Create a PG buying line item example in Line Item ALI Service).

Create a PG deal profile JSON that includes the deal target ID.

Note

For PG buying line items, you can only have one deal target in the deal_targets array.

$ cat pg_deal_profile

{
   "profile":{
      "deal_targets":[
         {
            "id":456
         }
      ],
      "allow_unaudited":true
   }
}

Make a POST request to the https://api.appnexus.com/profile endpoint with this PG deal profile JSON and an appropriate advertiser_id.

$ curl -b cookies -c cookies -X POST -d @pg_deal_profile 'https://api.appnexus.com/profile?advertiser_id=123'

{
   "response":{
      "status":"OK",
      "count":1,
      "id":123456,
      "start_element":0,
      "num_elements":100,
      "profile":{
         "id":123456,
         "code":null,
         "description":null,
         "country_action":"exclude",
         "region_action":"exclude",
         "city_action":"exclude",
         "browser_action":"exclude",
         "use_inventory_attribute_targets":false,
         "last_modified":"2019-08-07 19:43:12",
         "daypart_timezone":null,
         "dma_action":"exclude",
         "domain_action":"exclude",
         "domain_list_action":"exclude",
         "inventory_action":"exclude",
         "language_action":"exclude",
         "segment_boolean_operator":"and",
         "min_session_imps":null,
         "session_freq_type":"platform",
         "carrier_action":"exclude",
         "supply_type_action":"exclude",
         "device_type_action":"exclude",
         "screen_size_action":"exclude",
         "device_model_action":"exclude",
         "location_target_radius":null,
         "location_target_latitude":null,
         "location_target_longitude":null,
         "querystring_action":"exclude",
         "querystring_boolean_operator":"and",
         "is_expired":false,
         "non_audited_url_action":"include",
         "daypart_bitmap":null,
         "is_archived":false,
         "archived_on":null,
         "advertiser_id":123,
         "publisher_id":null,
         "max_session_imps":null,
         "max_day_imps":null,
         "max_lifetime_imps":null,
         "max_page_imps":null,
         "min_minutes_per_imp":null,
         "venue_action":"exclude",
         "operating_system_action":"exclude",
         "require_cookie_for_freq_cap":true,
         "trust":"seller",
         "allow_unaudited":true,
         "is_template":false,
         "created_on":"2019-08-07 19:43:12",
         "operating_system_family_action":"exclude",
         "use_operating_system_extended_targeting":true,
         "mobile_app_instance_action_include":false,
         "mobile_app_instance_list_action_include":false,
         "inventory_prefer_direct":false,
         "deal_action_include":true,
         "exclude_unknown_seller_member_group":false,
         "ad_slot_position_action_include":false,
         "ad_slot_intro_bumper_action_include":true,
         "ad_slot_outro_bumper_action_include":true,
         "graph_id":null,
         "media_subtype_action_include":false,
         "ads_txt_authorized_only":false,
         "inventory_url_allowlist_settings":{
            "apply_to_rtb":true,
            "apply_to_managed":true
         },
         "user_group_targets":null,
         "country_targets":null,
         "region_targets":null,
         "city_targets":null,
         "inventory_attribute_targets":null,
         "placement_type_targets":null,
         "age_targets":null,
         "daypart_targets":null,
         "browser_targets":null,
         "dma_targets":null,
         "domain_targets":null,
         "domain_list_targets":null,
         "language_targets":null,
         "size_targets":null,
         "zip_targets":null,
         "member_targets":null,
         "video_targets":{
            "allow_unknown_playback_method":false,
            "allow_unknown_context":false,
            "allow_unknown_player_size":false
         },
         "engagement_rate_targets":null,
         "segment_group_targets":null,
         "carrier_targets":null,
         "supply_type_targets":null,
         "device_type_targets":null,
         "screen_size_targets":null,
         "device_model_targets":null,
         "querystring_targets":null,
         "gender_targets":null,
         "intended_audience_targets":null,
         "inventory_network_resold_targets":null,
         "operating_system_targets":null,
         "operating_system_family_targets":null,
         "position_targets":null,
         "site_targets":null,
         "venue_targets":null,
         "operating_system_extended_targets":null,
         "postal_code_targets":null,
         "seller_member_group_targets":null,
         "cross_device":null,
         "key_value_targets":null,
         "media_subtype_targets":null,
         "content_category_targets":null,
         "deal_targets":[
            {
               "id":456,
               "name":"PG Deal 123",
               "code":"PGD_123",
               "deleted":false
            }
         ],
         "placement_targets":null,
         "platform_content_category_targets":null,
         "platform_placement_targets":null,
         "platform_publisher_targets":null,
         "publisher_targets":null,
         "ip_range_list_targets":null,
         "mobile_app_instance_targets":null,
         "mobile_app_instance_list_targets":null,
         "ad_slot_position_targets":null,
         "inventory_url_list_targets":null,
         "max_hour_imps":null,
         "max_week_imps":null,
         "max_month_imps":null
      },
      "dbg_info":{
         "warnings":[

         ],
         "version":"1.18.1247",
         "output_term":"profile"
      }
   }
}

Create a PG buying line item and associate it with the ID of the newly created PG deal profile (see the Create a PG buying line item example in Line Item ALI Service).

Target a specific political district
```
{
   "profile":{
      "political_district_targets":[
         {
            "id":"139897"
         }
      ]
   }
}                        
```

Partager via

Profile service overview

REST API

JSON fields

General

Frequency

Targeting

dma_targets format

domain_targets format

size_targets example

seller_member_group_targets format

deal_list_targets example

intended_audience_targets example

postal_code_targets example

postal_code_list_targets example

political_district_targets example

Targeting results for deal_action_include AND deal_targets fields

Mobile app instance targets

Mobile app instance list targets

Daypart targets

Segment targets

Consistent JSONs

Inconsistent JSONs

Segment targets example

Segment group targets

Segment group targets example

Age targets

ages object

Age targets example

Gender targets

Country targets

Country targets example

Region targets

Region targets example

Require transparency and consent framework string

Example

City targets

City targets example

Inventory lists

Inventory lists example

Content category targets

Content category targets example

Video targets

Contexts

Playback methods

Player sizes

Creative duration

Video frameworks

Video frameworks example

Engagement rate targets

Deal targets

Deal targets example

Position targets

Position targets example

Device model targets

Device model targets example

Device type targets

Device type targets example

Carrier targets

Carrier targets example

IP range list targets

Operating system extended targets

Operating system extended targets example

Operating system family targets

Operating system family targets example

Key value targets

key_value_targets object

header object

exp object

Key value targets example

Inventory URL allowlist settings

Inventory URL allowlist settings 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

`dma_targets` format

`domain_targets` format

`size_targets` example

`seller_member_group_targets` format

`deal_list_targets` example

`intended_audience_targets` example

`postal_code_targets` example

`postal_code_list_targets` example

`political_district_targets` example

Targeting results for `deal_action_include` AND `deal_targets` fields

`ages` object

`key_value_targets` object

`header` object

`exp` object