Edit

Profile service overview

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