--- title: "Create targeting templates" method: POST path: "/ad_accounts/{ad_account_id}/targeting_templates" tags: ["targeting_template"] --- # Create targeting templates `POST /ad_accounts/{ad_account_id}/targeting_templates` Targeting templates allow advertisers to save a set of targeting details including audience lists, keywords & interest, demographics, and placements to use more than once during the campaign creation process. Templates can be used to build out basic targeting criteria that you plan to use across campaigns and to reuse performance targeting from prior campaigns for new campaigns. ## Path parameters - `ad_account_id` string, required ## Request body - TargetingTemplateCreate — Resource create operation model. - `auto_targeting_enabled` boolean — Enable auto-targeting for ad group. Also known as ["expanded targeting"](https://help.pinterest.com/en/business/article/expanded-targeting). - `keywords` TargetingTemplateKeyword[] - `match_type` 'BROAD' | 'PHRASE' | 'EXACT' | 'EXACT_NEGATIVE' | 'PHRASE_NEGATIVE' — Keyword match type - `value` string — The keyword targeting (120 chars max). - `name` string, required — targeting template name - `placement_group` 'ALL' | 'SEARCH' | 'BROWSE' | 'OTHER' — Campaign placement group type - `targeting_attributes` TargetingSpecOptimal, required - `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 - `tracking_urls` TrackingUrls, 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. - TargetingTemplate - `ad_account_id` string — The ID of the advertiser that this targeting template belongs to. - `auto_targeting_enabled` boolean — Enable auto-targeting for ad group. Also known as ["expanded targeting"](https://help.pinterest.com/en/business/article/expanded-targeting). - `created_time` integer — Targeting template created time. Unix timestamp in seconds. - `id` string — Targeting template ID. - `keywords` TargetingTemplateKeyword[] - `match_type` 'BROAD' | 'PHRASE' | 'EXACT' | 'EXACT_NEGATIVE' | 'PHRASE_NEGATIVE' — Keyword match type - `value` string — The keyword targeting (120 chars max). - `name` string, required — targeting template name - `placement_group` 'ALL' | 'SEARCH' | 'BROWSE' | 'OTHER' — Campaign placement group type - `sizing` TargetingTemplateAudienceSizing, nullable — Gets an audience size estimate for a set of given targeting spec data. **Returns:** An object containing an audience size estimate that has a reach estimate (number of unique users) against the given targeting template. This by default provides a monthly estimate. - `reach_estimate` TargetingTemplateAudienceSizingReachEstimate - `estimate` integer - `lower_bound` integer - `upper_bound` integer - `status` 'ACTIVE' | 'DELETED' — Indicate targeting template is active or Deleted - `targeting_attributes` TargetingSpecOptimal, required - `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 - `tracking_urls` TrackingUrls, 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[] - `updated_time` integer — Targeting template updated time.Unix timestamp in seconds. - `valid` boolean, nullable — Inform if the targeting template is valid (ex. would be false if has revoked audience) ## Other responses - `201` — Resource create operation completed successfully. - `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)