--- title: "Update ad groups" method: PATCH path: "/ad_accounts/{ad_account_id}/ad_groups" tags: ["ad_groups"] --- # Update ad groups `PATCH /ad_accounts/{ad_account_id}/ad_groups` Update multiple existing ad groups. ## Path parameters - `ad_account_id` string, required ## Request body - AdGroupUpdateBatchUpdate[] - `auto_targeting_enabled` boolean, nullable — Enable auto-targeting for ad group. Default value is True. Also known as ["Performance+ targeting"](https://help.pinterest.com/en/business/article/performance-plus-targeting). - `bid_in_micro_currency` integer, nullable — Bid price in micro currency. This field is **REQUIRED** for the following campaign objective_type/billable_event combinations: AWARENESS/IMPRESSION, CONSIDERATION/CLICKTHROUGH, CATALOG_SALES/CLICKTHROUGH, VIDEO_VIEW/VIDEO_V_50_MRC. - `bid_multiplier` number — [Open beta](https://help.pinterest.com/en/business/article/beta-features) Bid multiplier for ad group. This value is a double between 0.1 and 10.0. Enter 0 to remove the bid multiplier. - Not currently supported for [Performance+ campaigns](https://help.pinterest.com/en/business/article/performance-plus-campaigns). - `bid_strategy_type` 'AUTOMATIC_BID' | 'MAX_BID' | 'TARGET_AVG' | 'null', nullable — Bid strategy type. For Campaigns with Video Completion objectives, the only supported bid strategy type is AUTOMATIC_BID, also known as "Pinterest Performance+ bidding". - `billable_event` 'CLICKTHROUGH' | 'IMPRESSION' | 'VIDEO_V_50_MRC' — Ad group billable event type. For update, only draft ad groups may update billable event. - `budget_in_micro_currency` integer, nullable — Budget in micro currency. This field is **REQUIRED** for non-CBO (campaign budget optimization) campaigns. A CBO campaign automatically generates ad group budgets from its campaign budget to maximize campaign outcome. A CBO campaign is limited to 70 or less ad groups. - `budget_type` 'DAILY' | 'LIFETIME' | 'CBO_ADGROUP' — Budget type. If DAILY, an ad group's daily spend will not exceed the budget parameter value. If LIFETIME, the end_time parameter is **REQUIRED**, and the ad group spend is spread evenly between the ad group `start_time` and `end_time` range. A CBO campaign automatically generates ad group budgets from its campaign budget to maximize campaign outcome. For CBO campaigns, only "CBO_ADGROUP" is allowed. For WEB_SESSIONS campaigns, only "LIFETIME" is allowed. For update, only draft ad groups may update budget type. - `campaign_id` string — Campaign ID of the ad group. - `customer_segment_id` string - `end_time` integer, nullable — Timestamp in Unix format for scheduling when ads in the ad group stop appearing. If not specified, ads run indefinitely unless you update the ad group by changing their status to `paused`. Cannot occur after `end_time` for parent campaign (if specified). Learn about [scheduling ads](https://help.pinterest.com/en/business/article/ads-manager-schedule-ads). For certain organizations ([Closed beta](https://help.pinterest.com/en/business/article/beta-features)): Supported for campaigns with Campaign Budget Optimization (CBO). For all organizations: Supported for campaigns without CBO. - `ext_features` AdgroupTrackingFeatures, nullable - `enabled` AdgroupTrackingFeatureType[] — Tracking features. To clear this field, set to null. - `feed_profile_id` string — Feed Profile ID associated to the adgroup. - `id` string, required — Ad group ID. - `is_creative_optimization` boolean, nullable — Enable creative optimization for the ad group, default value is FALSE. When enabled, you allow Pinterest to automatically turn your product Pins into ads in different formats (collections and shopping) and deliver those ads to users at scale. - `is_local_inventory` boolean — Indicates whether the ad group should use the local inventory. - `lifetime_frequency_cap` integer — Set a limit to the number of times a promoted pin from this campaign can be impressed by a pinner within the past rolling 30 days. Only available for CPM (cost per mille (1000 impressions)) ad groups. A CPM ad group has an IMPRESSION [billable_event](https://help.pinterest.com/en/business/article/billable-events) value. This field **REQUIRES** the `end_time` field. - `local_inventory_radius_in_miles` number — The targeting radius of the local inventory ads in miles. - `name` string — Ad group name. - `optimization_goal_metadata` NullableOptimizationGoalMetadata, nullable - `conversion_tag_v3_goal_metadata` ConversionTagV3GoalMetadata - `attribution_windows` AttributionWindows - `click_window_days` integer - `engagement_window_days` integer - `view_window_days` integer - `conversion_event` 'PAGE_VISIT' | 'SIGNUP' | 'CHECKOUT' | 'CUSTOM' | 'VIEW_CATEGORY' | 'SEARCH' | 'ADD_TO_CART' | 'WATCH_VIDEO' | 'LEAD' | 'APP_INSTALL' - `conversion_tag_id` string - `cpa_goal_value_in_micro_currency` string - `is_roas_optimized` boolean, nullable — Pinterest Performance+ ROAS bidding. When enabled, Pinterest will optimize for conversion value instead of conversion volume. Only supported when `conversion_event` is set to `"CHECKOUT"` and `bid_strategy_type` is set to `"AUTOMATIC_BID"`. This parameter is not enabled for all advertisers. [Learn more](https://developers.pinterest.com/docs/getting-started/using-beta-and-restricted-features/). - `reporting_event` string — Event name for custom or standard events mapped to an oCPM model - `frequency_goal_metadata` FrequencyGoalMetadata — Frequency target can only be between 2 and 20 - `frequency` integer - `timerange` 'THIRTY_DAY' | 'DAY' | 'SEVEN_DAY' | 'TWENTY_MINUTE' | 'TEN_MINUTE' | 'TWENTY_FOUR_HOUR' - `scrollup_goal_metadata` ScrollupGoalMetadata - `scrollup_goal_value_in_micro_currency` string, nullable - `pacing_delivery_type` 'STANDARD' | 'ACCELERATED' — Ad group pacing delivery type. With ACCELERATED, an ad group budget is spent as fast as possible. With STANDARD, an ad group budget is spent smoothly over a day. When using CBO, only the STANDARD pacing delivery type is allowed. - `performance_plus_campaign_settings` PerformancePlusCampaignSettings, nullable — Pinterest Performance+ campaign settings. - `boost_prospecting_ad_group_bid` boolean — Whether to boost prospecting ad group bid. - `pinner_list_exclusions` string[] — List of campaign-level exclusion pinner list IDs. - `placement_group` 'ALL' | 'SEARCH' | 'BROWSE' | 'OTHER' — Campaign placement group type - `placement_traffic_type` 'ALL' | 'TWO_COLUMN_FEED' | 'FULLSCREEN_FEED' | 'null', nullable — A targeting option that enables advertisers to choose whether to run ads in fullscreen feed, two column feed, or both. - `promotion_application_level` 'NONE' | 'ITEM' | 'AD_GROUP' | 'null', nullable — Specify if the promotion is applied at ad group or item level. - `promotion_id` string, nullable — Promotion ID. To clear this field, set to null. - `promotion_ids` string[] — Promotion IDs list. To clear this field, set to an empty array []. - `start_time` integer, nullable — Timestamp in Unix format for scheduling when ads in the ad group start to appear. If not specified, ads appear during parent campaign's `start_time`. Cannot precede `start_time` for parent campaign (if specified). Learn about [scheduling ads](/docs/api-features/managing-ads/#step-2-create-an-ad-group). For certain organizations ([Closed beta](/docs/getting-started/using-beta-and-restricted-features/)): Supported for campaigns with Campaign Budget Optimization (CBO). For all organizations: Supported for campaigns without CBO. - `status` 'ACTIVE' | 'PAUSED' | 'ARCHIVED' | 'DRAFT' | 'DELETED_DRAFT' — Entity status - `targeting_spec` TargetingSpecOptimal - `AGE_BUCKET` TargetingSpecAgeBucket[], nullable — **Legacy field.** Predefined age ranges. We recommend using MINIMUM_AGE and MAXIMUM_AGE instead for more flexible targeting. Cannot be combined with MINIMUM_AGE/MAXIMUM_AGE. If neither AGE_BUCKET nor MINIMUM_AGE/MAXIMUM_AGE are specified, all ages will be targeted. - `APPTYPE` TargetingSpecAppType[], nullable — Allowed devices. If the APPTYPE field is missing, the default behavior in terms of ad delivery is that **All devices/apptypes** will be targeted. - `AUDIENCE_EXCLUDE` PinterestLibIntegerFormatType[], nullable — Excluded customer list IDs. Used to drive new customer acquisition goals. For example: ["2542620905475"]. Audience lists need to have at least 100 people with Pinterest accounts in them. If the AUDIENCE_EXCLUDE field is missing, the default behavior in terms of ad delivery is that **No users will be excluded**. - `AUDIENCE_INCLUDE` PinterestLibIntegerFormatType[], nullable — Targeted customer list IDs. For example: ["2542620905473"]. Audience lists need to have at least 100 people with Pinterest accounts in them Audience lists need to have at least 100 people with Pinterest accounts in them. If the AUDIENCE_INCLUDE field is missing, the default behavior in terms of ad delivery is that **All users will be included**. - `GENDER` TargetingSpecGender[], nullable — Targeted genders. Values: ["unknown","male","female"]. If the GENDER field is missing, the default behavior in terms of ad delivery is that **All genders will be targeted**. - `GEO` string[], nullable — Region codes or postal codes to include for targeting. Region codes represent broader geographical areas. Example: `US-CA` is the region code for California in the United States. Postal codes represent more granular, specific areas. Example: `94103` is a postal code for a specifc area in San Francisco, California, U.S.A. For each ad group, use only one of these methods, depending on which fits your targeting needs. Do not use both. For example, either specify a broader region code like `US-CA` or a more granular postal code within that regon, such as `94103`. You can specify multiple region codes or postal codes in an array, depending on which method you choose. Precede a region code array with the `region_codes` key and a postal code value with the `postal_codes` key. Examples: ``` "geo": { "region_codes": ["US-CA"] } ``` ``` "geo": { "postal_codes": ["94103"] } ``` For each ad group, specify at least one `GEO` or `LOCATION`. If you do not specifiy a `GEO` code, only `LOCATION` values will be targeted (See `LOCATION` parameter in this targeting spec.). Learn how to [get a current, complete list of codes](/docs/analytics-and-reports/ads-reporting/#get-all-available-codes-and-zones). - `GEO_EXCLUDE` string[] — [Closed beta](/docs/getting-started/using-beta-and-restricted-features/) Region codes or postal codes to exclude from the targeting inclusion area. See `GEO` parameter in this targeting spec for rules, syntax, and other information. - `INTEREST` string[] — Array of interest object IDs. If the INTEREST field is missing, the default behavior in terms of ad delivery is that **All interests will be targeted**. - `LOCALE` string[], nullable — 24 ISO 639-1 two-letter language codes. If the LOCALE field is not included in the request, all languages are targeted. - `LOCATION` string[], nullable — Metropolitan codes and/or ISO-Alpha-2, two-letter country codes to include for targeting. Precede country code values with the `country_codes` key and metro code values with `metro_codes` key. Example: ``` "location": { "country_codes": ["US", "CA"], "metro_codes": ["501", "602"] } ``` For each ad group, specify at least one `GEO` or `LOCATION` code. If you do not specify a `LOCATION` code, only `GEO` values will be targeted (See `GEO` parameter in this targeting spec.). Learn how to [get a current, complete list of codes](/docs/analytics-and-reports/ads-reporting/#get-all-available-codes-and-zones). - `LOCATION_EXCLUDE` string[] — [Closed beta](/docs/getting-started/using-beta-and-restricted-features/) Metropolitan codes and/or ISO-Alpha-2, two-letter country codes to exclude from targeting. See `LOCATION` parameter in this targeting spec for rules, syntax, and other information. - `MAXIMUM_AGE` string — Maximum age to target (inclusive). Values: "18", "19", ..., "65", "65+". Must be used together with `MINIMUM_AGE`. Cannot be combined with `AGE_BUCKET`. If neither `MINIMUM_AGE`/`MAXIMUM_AGE` nor `AGE_BUCKET` are specified, all ages will be targeted. - `MINIMUM_AGE` string — Minimum age to target (inclusive). Values: "18", "19", ..., "65". Note: 65+ is not allowed for minimum age. Must be used together with `MAXIMUM_AGE`. Cannot be combined with `AGE_BUCKET`. If neither `MINIMUM_AGE`/`MAXIMUM_AGE` nor `AGE_BUCKET` are specified, all ages will be targeted. - `SHOPPING_RETARGETING` TargetingSpecShoppingRetargeting[], nullable — Array of object: lookback_window [Integer]: Number of days ago to start lookback timeframe for dynamic retargeting tag_types [Array of integer]: Event types to target for dynamic retargeting exclusion_window [Integer]: Number of days ago to stop lookback timeframe for dynamic retargeting - `exclusion_window` integer — Number of days ago to stop lookback timeframe for dynamic retargeting - `lookback_window` integer — Number of days ago to start lookback timeframe for dynamic retargeting - `tag_types` integer[] — Event types to target for dynamic retargeting - `TARGETING_STRATEGY` TargetingStrategy[], nullable - `targeting_spec_operations` TargetingSpecOperations[] - union - object - `field` 'AUDIENCE_EXCLUDE', required - `operation` 'SET' | 'ADD' | 'REMOVE', required - `values` string[], required - object - `field` 'AUDIENCE_INCLUDE', required - `operation` 'SET' | 'ADD' | 'REMOVE', required - `values` string[], required - object - `field` 'GEO', required - `operation` 'SET' | 'ADD' | 'REMOVE', required - `values` string[], required - object - `field` 'GEO_EXCLUDE', required - `operation` 'SET' | 'ADD' | 'REMOVE', required - `values` string[], required - object - `field` 'INTEREST', required - `operation` 'SET' | 'ADD' | 'REMOVE', required - `values` string[], required - object - `field` 'LOCATION', required - `operation` 'SET' | 'ADD' | 'REMOVE', required - `values` string[], required - object - `field` 'LOCATION_EXCLUDE', required - `operation` 'SET' | 'ADD' | 'REMOVE', required - `values` string[], required - object - `field` 'LOCALE', required - `operation` 'SET' | 'ADD' | 'REMOVE', required - `values` string[], required - object - `field` 'APPTYPE', required - `operation` 'SET' | 'ADD' | 'REMOVE', required - `values` TargetingSpecAppType[], required - object - `field` 'GENDER', required - `operation` 'SET' | 'ADD' | 'REMOVE', required - `values` TargetingSpecGender[], required - object - `field` 'AGE_BUCKET', required - `operation` 'SET', required - `values` TargetingSpecAgeBucket[], required - object - `field` 'SHOPPING_RETARGETING', required - `operation` 'SET', required - `values` TargetingSpecShoppingRetargeting[], required - `exclusion_window` integer — Number of days ago to stop lookback timeframe for dynamic retargeting - `lookback_window` integer — Number of days ago to start lookback timeframe for dynamic retargeting - `tag_types` integer[] — Event types to target for dynamic retargeting - object - `field` 'MAXIMUM_AGE', required - `operation` 'SET', required - `value` string, nullable, required - object - `field` 'MINIMUM_AGE', required - `operation` 'SET', required - `value` string, nullable, required - `targeting_template_ids` PinterestLibIntegerFormatType[], nullable — Targeting template IDs applied to the ad group. We currently only support 1 targeting template per ad group. To use targeting templates, do not set any other targeting fields: targeting_spec, tracking_urls, auto_targeting_enabled, placement_group. To clear all targeting template IDs, set this field to ['0']. - `tracking_urls` AdGroupTrackingURLs, nullable — Third-party tracking URLs. Up to three tracking URLs - with a max length of 2,000 - are supported for each event type. Tracking URLs set at the ad group or ad level can override those set at the campaign level. For more information, see [Third-party and dynamic tracking](https://help.pinterest.com/en/business/article/third-party-and-dynamic-tracking). - `audience_verification` string[] - `buyable_button` string[] - `click` string[] - `engagement` string[] - `impression` string[] ## Response `200` The request has succeeded. - object - `items` object[], required - `data` AdGroup - `ad_account_id` string — Advertiser ID. - `bid_in_micro_currency` integer, nullable — Bid price in micro currency. This field is **REQUIRED** for the following campaign objective_type/billable_event combinations: AWARENESS/IMPRESSION, CONSIDERATION/CLICKTHROUGH, CATALOG_SALES/CLICKTHROUGH, VIDEO_VIEW/VIDEO_V_50_MRC. - `bid_strategy_type` 'AUTOMATIC_BID' | 'MAX_BID' | 'TARGET_AVG' | 'null', nullable — Bid strategy type. For Campaigns with Video Completion objectives, the only supported bid strategy type is AUTOMATIC_BID, also known as "Pinterest Performance+ bidding". - `billable_event` 'CLICKTHROUGH' | 'IMPRESSION' | 'VIDEO_V_50_MRC', required — Ad group billable event type. For update, only draft ad groups may update billable event. - `budget_in_micro_currency` integer, nullable — Budget in micro currency. This field is **REQUIRED** for non-CBO (campaign budget optimization) campaigns. A CBO campaign automatically generates ad group budgets from its campaign budget to maximize campaign outcome. A CBO campaign is limited to 70 or less ad groups. - `campaign_id` string, required — Campaign ID of the ad group. - `conversion_learning_mode_type` 'NOT_ACTIVE' | 'ACTIVE' | 'null', nullable, required — oCPM learn mode. - `created_time` integer, required — Ad group creation time. Unix timestamp in seconds. - `customer_segment_id` string - `dca_assets` unknown - `end_time` integer, nullable — Timestamp in Unix format for scheduling when ads in the ad group stop appearing. If not specified, ads run indefinitely unless you update the ad group by changing their status to `paused`. Cannot occur after `end_time` for parent campaign (if specified). Learn about [scheduling ads](https://help.pinterest.com/en/business/article/ads-manager-schedule-ads). For certain organizations ([Closed beta](https://help.pinterest.com/en/business/article/beta-features)): Supported for campaigns with Campaign Budget Optimization (CBO). For all organizations: Supported for campaigns without CBO. - `ext_features` AdgroupTrackingFeatures, nullable - `enabled` AdgroupTrackingFeatureType[] — Tracking features. To clear this field, set to null. - `feed_profile_id` string — Feed Profile ID associated to the adgroup. - `id` string, required — Ad group ID. - `is_creative_optimization` boolean, nullable — Enable creative optimization for the ad group, default value is FALSE. When enabled, you allow Pinterest to automatically turn your product Pins into ads in different formats (collections and shopping) and deliver those ads to users at scale. - `is_local_inventory` boolean — Indicates whether the ad group should use the local inventory. - `lifetime_frequency_cap` integer — Set a limit to the number of times a promoted pin from this campaign can be impressed by a pinner within the past rolling 30 days. Only available for CPM (cost per mille (1000 impressions)) ad groups. A CPM ad group has an IMPRESSION [billable_event](https://help.pinterest.com/en/business/article/billable-events) value. This field **REQUIRES** the `end_time` field. - `local_inventory_radius_in_miles` number — The targeting radius of the local inventory ads in miles. - `name` string, required — Ad group name. - `optimization_goal_metadata` NullableOptimizationGoalMetadata, nullable - `conversion_tag_v3_goal_metadata` ConversionTagV3GoalMetadata - `attribution_windows` AttributionWindows - `click_window_days` integer - `engagement_window_days` integer - `view_window_days` integer - `conversion_event` 'PAGE_VISIT' | 'SIGNUP' | 'CHECKOUT' | 'CUSTOM' | 'VIEW_CATEGORY' | 'SEARCH' | 'ADD_TO_CART' | 'WATCH_VIDEO' | 'LEAD' | 'APP_INSTALL' - `conversion_tag_id` string - `cpa_goal_value_in_micro_currency` string - `is_roas_optimized` boolean, nullable — Pinterest Performance+ ROAS bidding. When enabled, Pinterest will optimize for conversion value instead of conversion volume. Only supported when `conversion_event` is set to `"CHECKOUT"` and `bid_strategy_type` is set to `"AUTOMATIC_BID"`. This parameter is not enabled for all advertisers. [Learn more](https://developers.pinterest.com/docs/getting-started/using-beta-and-restricted-features/). - `reporting_event` string — Event name for custom or standard events mapped to an oCPM model - `frequency_goal_metadata` FrequencyGoalMetadata — Frequency target can only be between 2 and 20 - `frequency` integer - `timerange` 'THIRTY_DAY' | 'DAY' | 'SEVEN_DAY' | 'TWENTY_MINUTE' | 'TEN_MINUTE' | 'TWENTY_FOUR_HOUR' - `scrollup_goal_metadata` ScrollupGoalMetadata - `scrollup_goal_value_in_micro_currency` string, nullable - `performance_plus_campaign_settings` PerformancePlusCampaignSettings, nullable — Pinterest Performance+ campaign settings. - `boost_prospecting_ad_group_bid` boolean — Whether to boost prospecting ad group bid. - `pinner_list_exclusions` string[] — List of campaign-level exclusion pinner list IDs. - `placement_group` 'ALL' | 'SEARCH' | 'BROWSE' | 'OTHER' — Campaign placement group type - `placement_traffic_type` 'ALL' | 'TWO_COLUMN_FEED' | 'FULLSCREEN_FEED' | 'null', nullable — A targeting option that enables advertisers to choose whether to run ads in fullscreen feed, two column feed, or both. - `promotion_application_level` 'NONE' | 'ITEM' | 'AD_GROUP' | 'null', nullable — Specify if the promotion is applied at ad group or item level. - `promotion_id` string, nullable — Promotion ID. To clear this field, set to null. - `promotion_ids` string[] — Promotion IDs list. To clear this field, set to an empty array []. - `start_time` integer, nullable — Timestamp in Unix format for scheduling when ads in the ad group start to appear. If not specified, ads appear during parent campaign's `start_time`. Cannot precede `start_time` for parent campaign (if specified). Learn about [scheduling ads](/docs/api-features/managing-ads/#step-2-create-an-ad-group). For certain organizations ([Closed beta](/docs/getting-started/using-beta-and-restricted-features/)): Supported for campaigns with Campaign Budget Optimization (CBO). For all organizations: Supported for campaigns without CBO. - `status` 'ACTIVE' | 'PAUSED' | 'ARCHIVED' | 'DRAFT' | 'DELETED_DRAFT' — Entity status - `summary_status` 'RUNNING' | 'PAUSED' | 'NOT_STARTED' | 'COMPLETED' | 'ADVERTISER_DISABLED' | 'ARCHIVED' | 'DRAFT' | 'DELETED_DRAFT', required — Summary status for campaign - `targeting_spec` TargetingSpecOptimal - `AGE_BUCKET` TargetingSpecAgeBucket[], nullable — **Legacy field.** Predefined age ranges. We recommend using MINIMUM_AGE and MAXIMUM_AGE instead for more flexible targeting. Cannot be combined with MINIMUM_AGE/MAXIMUM_AGE. If neither AGE_BUCKET nor MINIMUM_AGE/MAXIMUM_AGE are specified, all ages will be targeted. - `APPTYPE` TargetingSpecAppType[], nullable — Allowed devices. If the APPTYPE field is missing, the default behavior in terms of ad delivery is that **All devices/apptypes** will be targeted. - `AUDIENCE_EXCLUDE` PinterestLibIntegerFormatType[], nullable — Excluded customer list IDs. Used to drive new customer acquisition goals. For example: ["2542620905475"]. Audience lists need to have at least 100 people with Pinterest accounts in them. If the AUDIENCE_EXCLUDE field is missing, the default behavior in terms of ad delivery is that **No users will be excluded**. - `AUDIENCE_INCLUDE` PinterestLibIntegerFormatType[], nullable — Targeted customer list IDs. For example: ["2542620905473"]. Audience lists need to have at least 100 people with Pinterest accounts in them Audience lists need to have at least 100 people with Pinterest accounts in them. If the AUDIENCE_INCLUDE field is missing, the default behavior in terms of ad delivery is that **All users will be included**. - `GENDER` TargetingSpecGender[], nullable — Targeted genders. Values: ["unknown","male","female"]. If the GENDER field is missing, the default behavior in terms of ad delivery is that **All genders will be targeted**. - `GEO` string[], nullable — Region codes or postal codes to include for targeting. Region codes represent broader geographical areas. Example: `US-CA` is the region code for California in the United States. Postal codes represent more granular, specific areas. Example: `94103` is a postal code for a specifc area in San Francisco, California, U.S.A. For each ad group, use only one of these methods, depending on which fits your targeting needs. Do not use both. For example, either specify a broader region code like `US-CA` or a more granular postal code within that regon, such as `94103`. You can specify multiple region codes or postal codes in an array, depending on which method you choose. Precede a region code array with the `region_codes` key and a postal code value with the `postal_codes` key. Examples: ``` "geo": { "region_codes": ["US-CA"] } ``` ``` "geo": { "postal_codes": ["94103"] } ``` For each ad group, specify at least one `GEO` or `LOCATION`. If you do not specifiy a `GEO` code, only `LOCATION` values will be targeted (See `LOCATION` parameter in this targeting spec.). Learn how to [get a current, complete list of codes](/docs/analytics-and-reports/ads-reporting/#get-all-available-codes-and-zones). - `GEO_EXCLUDE` string[] — [Closed beta](/docs/getting-started/using-beta-and-restricted-features/) Region codes or postal codes to exclude from the targeting inclusion area. See `GEO` parameter in this targeting spec for rules, syntax, and other information. - `INTEREST` string[] — Array of interest object IDs. If the INTEREST field is missing, the default behavior in terms of ad delivery is that **All interests will be targeted**. - `LOCALE` string[], nullable — 24 ISO 639-1 two-letter language codes. If the LOCALE field is not included in the request, all languages are targeted. - `LOCATION` string[], nullable — Metropolitan codes and/or ISO-Alpha-2, two-letter country codes to include for targeting. Precede country code values with the `country_codes` key and metro code values with `metro_codes` key. Example: ``` "location": { "country_codes": ["US", "CA"], "metro_codes": ["501", "602"] } ``` For each ad group, specify at least one `GEO` or `LOCATION` code. If you do not specify a `LOCATION` code, only `GEO` values will be targeted (See `GEO` parameter in this targeting spec.). Learn how to [get a current, complete list of codes](/docs/analytics-and-reports/ads-reporting/#get-all-available-codes-and-zones). - `LOCATION_EXCLUDE` string[] — [Closed beta](/docs/getting-started/using-beta-and-restricted-features/) Metropolitan codes and/or ISO-Alpha-2, two-letter country codes to exclude from targeting. See `LOCATION` parameter in this targeting spec for rules, syntax, and other information. - `MAXIMUM_AGE` string — Maximum age to target (inclusive). Values: "18", "19", ..., "65", "65+". Must be used together with `MINIMUM_AGE`. Cannot be combined with `AGE_BUCKET`. If neither `MINIMUM_AGE`/`MAXIMUM_AGE` nor `AGE_BUCKET` are specified, all ages will be targeted. - `MINIMUM_AGE` string — Minimum age to target (inclusive). Values: "18", "19", ..., "65". Note: 65+ is not allowed for minimum age. Must be used together with `MAXIMUM_AGE`. Cannot be combined with `AGE_BUCKET`. If neither `MINIMUM_AGE`/`MAXIMUM_AGE` nor `AGE_BUCKET` are specified, all ages will be targeted. - `SHOPPING_RETARGETING` TargetingSpecShoppingRetargeting[], nullable — Array of object: lookback_window [Integer]: Number of days ago to start lookback timeframe for dynamic retargeting tag_types [Array of integer]: Event types to target for dynamic retargeting exclusion_window [Integer]: Number of days ago to stop lookback timeframe for dynamic retargeting - `exclusion_window` integer — Number of days ago to stop lookback timeframe for dynamic retargeting - `lookback_window` integer — Number of days ago to start lookback timeframe for dynamic retargeting - `tag_types` integer[] — Event types to target for dynamic retargeting - `TARGETING_STRATEGY` TargetingStrategy[], nullable - `targeting_template_ids` PinterestLibIntegerFormatType[], nullable — Targeting template IDs applied to the ad group. We currently only support 1 targeting template per ad group. To use targeting templates, do not set any other targeting fields: targeting_spec, tracking_urls, auto_targeting_enabled, placement_group. To clear all targeting template IDs, set this field to ['0']. - `tracking_urls` AdGroupTrackingURLs, nullable — Third-party tracking URLs. Up to three tracking URLs - with a max length of 2,000 - are supported for each event type. Tracking URLs set at the ad group or ad level can override those set at the campaign level. For more information, see [Third-party and dynamic tracking](https://help.pinterest.com/en/business/article/third-party-and-dynamic-tracking). - `audience_verification` string[] - `buyable_button` string[] - `click` string[] - `engagement` string[] - `impression` string[] - `type` string, required — Always "adgroup". - `updated_time` integer, required — Ad group last update time. Unix timestamp in seconds. - `exceptions` PinterestLibBatchItemException[] - `code` integer - `message` string, required ## Other responses - `400` — The request could not be understood by the server due to unexpected data. - `401` — Authentication is required and has either failed or not been provided. - `403` — The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. - `404` — The requested resource could not be found on this server. - `429` — The user has sent too many requests in a given amount of time and is being rate limited. - `default` — An unexpected error response. --- [API](https://skmtc.net/pinterest/apis/pinterest-rest-api.md) · [All operations](https://skmtc.net/pinterest/apis/pinterest-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pinterest/pinterest-rest-api/revisions/b698c180678a/schema)