Pinterest Groups API
The Groups API from Pinterest — 15 operation(s) for groups.
OpenAPI Specification
openapi: 3.0.3
info:
version: 5.13.0
title: Pinterest Groups API
description: This is the description of your API.
contact:
name: Pinterest, Inc.
url: https://developers.pinterest.com/
license:
name: MIT
url: https://spdx.org/licenses/MIT
termsOfService: https://developers.pinterest.com/terms/
servers:
- url: https://api.pinterest.com/v5
tags:
- name: Groups
paths:
/ad_accounts/{ad_account_id}/ad_groups:
get:
summary: List ad groups
description: 'List ad groups based on provided campaign IDs or ad group IDs.(campaign_ids or ad_group_ids). <p/>
<strong>Note:</strong><p/>
Provide only campaign_id or ad_group_id. Do not provide both.'
operationId: ad_groups/list
security:
- pinterest_oauth2:
- ads:read
x-ratelimit-category: ads_read
x-sandbox: enabled
parameters:
- $ref: '#/components/parameters/path_ad_account_id'
- $ref: '#/components/parameters/query_campaign_ids'
- $ref: '#/components/parameters/query_ad_group_ids'
- $ref: '#/components/parameters/query_entity_statuses'
- $ref: '#/components/parameters/query_page_size'
- $ref: '#/components/parameters/query_order'
- $ref: '#/components/parameters/query_bookmark'
- $ref: '#/components/parameters/query_translate_interests_to_names'
responses:
'200':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Paginated'
- type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/AdGroupResponse'
description: Success
'400':
description: Invalid ad account group parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 400
message: Invalid ad account group parameters.
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Groups
post:
summary: Create ad groups
description: "Create multiple new ad groups. All ads in a given ad group will have the same budget, bid, run dates, targeting, and placement (search, browse, other). For more information, <a href=\"https://help.pinterest.com/en/business/article/campaign-structure\" target=\"_blank\"> click here</a>.</p>\n<strong>Note:</strong>\n- 'bid_in_micro_currency' and 'budget_in_micro_currency' should be expressed in microcurrency amounts based on the currency field set in the advertiser's profile.<p/>\n<p>Microcurrency is used to track very small transactions, based on the currency set in the advertisers profile.</p>\n<p>A microcurrency unit is 10^(-6) of the standard unit of currency selected in the advertisers profile.</p>\n <p><strong>Equivalency equations</strong>, using dollars as an example currency:</p>\n<ul>\n <li>$1 = 1,000,000 microdollars</li>\n <li>1 microdollar = $0.000001 </li>\n</ul>\n<p><strong>To convert between currency and microcurrency</strong>, using dollars as an example currency:</p>\n<ul>\n <li>To convert dollars to microdollars, mutiply dollars by 1,000,000</li>\n <li>To convert microdollars to dollars, divide microdollars by 1,000,000</li>\n</ul>\n- Ad groups belong to ad campaigns. Some types of campaigns (e.g. budget optimization) have limits on the number of ad groups they can hold. If you exceed those limits, you will get an error message.\n- Start and end time cannot be set for ad groups that belong to CBO campaigns. Currently, campaigns with the following objective types: TRAFFIC, AWARENESS, WEB_CONVERSIONS, and CATALOG_SALES will default to CBO."
operationId: ad_groups/create
security:
- pinterest_oauth2:
- ads:write
x-ratelimit-category: ads_write
x-sandbox: enabled
parameters:
- $ref: '#/components/parameters/path_ad_account_id'
requestBody:
content:
application/json:
schema:
items:
$ref: '#/components/schemas/AdGroupCreateRequest'
maxItems: 30
minItems: 1
type: array
description: List of ad groups to create, size limit [1, 30].
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AdGroupArrayResponse'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
tags:
- Groups
patch:
summary: Update ad groups
description: Update multiple existing ad groups.
operationId: ad_groups/update
security:
- pinterest_oauth2:
- ads:write
x-ratelimit-category: ads_write
x-sandbox: enabled
parameters:
- $ref: '#/components/parameters/path_ad_account_id'
requestBody:
content:
application/json:
schema:
items:
$ref: '#/components/schemas/AdGroupUpdateRequest'
maxItems: 30
minItems: 1
type: array
description: List of ad groups to update, size limit [1, 30].
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AdGroupArrayResponse'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
tags:
- Groups
/ad_accounts/{ad_account_id}/ad_groups/analytics:
get:
summary: Get ad group analytics
description: 'Get analytics for the specified ad groups in the specified <code>ad_account_id</code>, filtered by the specified options.
- The token''s user_account must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via <a href="https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts">Business Access</a>: Admin, Analyst, Campaign Manager.
- If granularity is not HOUR, the furthest back you can are allowed to pull data is 90 days before the current date in UTC time and the max time range supported is 90 days.
- If granularity is HOUR, the furthest back you can are allowed to pull data is 8 days before the current date in UTC time and the max time range supported is 3 days.'
operationId: ad_groups/analytics
security:
- pinterest_oauth2:
- ads:read
x-ratelimit-category: ads_analytics
x-sandbox: enabled
parameters:
- $ref: '#/components/parameters/path_ad_account_id'
- $ref: '#/components/parameters/query_start_date'
- $ref: '#/components/parameters/query_end_date'
- $ref: '#/components/parameters/query_ad_group_ids_required'
- $ref: '#/components/parameters/query_columns'
- $ref: '#/components/parameters/query_granularity'
- $ref: '#/components/parameters/query_conversion_attribution_click_window_days'
- $ref: '#/components/parameters/query_conversion_attribution_engagement_window_days'
- $ref: '#/components/parameters/query_conversion_attribution_view_window_days'
- $ref: '#/components/parameters/query_conversion_attribution_conversion_report_time'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AdGroupsAnalyticsResponse'
description: Success
'400':
description: Invalid ad account group analytics parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 400
message: Invalid ad account group analytics parameters.
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Groups
/ad_accounts/{ad_account_id}/ad_groups/targeting_analytics:
get:
summary: Get targeting analytics for ad groups
description: 'Get targeting analytics for one or more ad groups.
For the requested ad group(s) and metrics, the response will include the requested metric information
(e.g. SPEND_IN_DOLLAR) for the requested target type (e.g. "age_bucket") for applicable values (e.g. "45-49"). <p/>
- The token''s user_account must either be the Owner of the specified ad account, or have one
of the necessary roles granted to them via
<a href="https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts">Business Access</a>: Admin, Analyst, Campaign Manager.
- If granularity is not HOUR, the furthest back you can are allowed to pull data is 90 days before the current date in UTC time and the max time range supported is 90 days.
- If granularity is HOUR, the furthest back you can are allowed to pull data is 8 days before the current date in UTC time and the max time range supported is 3 days.'
operationId: ad_groups_targeting_analytics/get
security:
- pinterest_oauth2:
- ads:read
x-ratelimit-category: ads_analytics
x-sandbox: enabled
parameters:
- $ref: '#/components/parameters/path_ad_account_id'
- $ref: '#/components/parameters/query_ad_group_ids_required'
- $ref: '#/components/parameters/query_start_date'
- $ref: '#/components/parameters/query_end_date'
- $ref: '#/components/parameters/query_targeting_types'
- $ref: '#/components/parameters/query_columns'
- $ref: '#/components/parameters/query_granularity'
- $ref: '#/components/parameters/query_conversion_attribution_click_window_days'
- $ref: '#/components/parameters/query_conversion_attribution_engagement_window_days'
- $ref: '#/components/parameters/query_conversion_attribution_view_window_days'
- $ref: '#/components/parameters/query_conversion_attribution_conversion_report_time'
- $ref: '#/components/parameters/query_attribution_types'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/MetricsResponse'
description: Success
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Groups
/ad_accounts/{ad_account_id}/ad_groups/audience_sizing:
post:
summary: Get audience sizing
description: "Get potential audience size for an ad group with given targeting criteria. \nPotential audience size estimates the number of people you may be able to reach per month with your campaign. \nIt is based on historical advertising data and the targeting criteria you select.\nIt does not guarantee results or take into account factors such as bid, budget, schedule, seasonality or product experiments."
operationId: ad_groups/audience_sizing
security:
- pinterest_oauth2:
- ads:read
x-ratelimit-category: ads_read
x-sandbox: enabled
parameters:
- $ref: '#/components/parameters/path_ad_account_id'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdGroupAudienceSizingRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AdGroupAudienceSizingResponse'
description: Success
'400':
description: Invalid ad group audience sizing parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 400
message: Invalid ad group audience sizing parameters.
'403':
description: No access to requested audience list or product group.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 403
message: You don't have access to the requested audience list or product group.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
tags:
- Groups
/ad_accounts/{ad_account_id}/ad_groups/{ad_group_id}:
get:
summary: Get ad group
description: 'Get a specific ad given the ad ID. If your pin is rejected, rejected_reasons will
contain additional information from the Ad Review process.
For more information about our policies and rejection reasons see the <a href="https://www.pinterest.com/_/_/policy/advertising-guidelines/"
target="_blank">Pinterest advertising standards</a>.'
operationId: ad_groups/get
security:
- pinterest_oauth2:
- ads:read
x-ratelimit-category: ads_read
x-sandbox: enabled
parameters:
- $ref: '#/components/parameters/path_ad_account_id'
- $ref: '#/components/parameters/path_ad_group_id'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AdGroupResponse'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
tags:
- Groups
/ad_accounts/{ad_account_id}/product_group_promotions:
post:
description: Add one or more product groups from your catalog to an existing ad group. (Product groups added to an ad group are a 'product group promotion.')
operationId: product_group_promotions/create
security:
- pinterest_oauth2:
- ads:write
x-ratelimit-category: ads_write
x-sandbox: disabled
parameters:
- $ref: '#/components/parameters/path_ad_account_id'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ProductGroupPromotionCreateRequest'
description: List of Product Group Promotions to create, size limit [1, 30].
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ProductGroupPromotionResponse'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
summary: Create product group promotions
tags:
- Groups
patch:
description: Update multiple existing Product Group Promotions (by product_group_id)
operationId: product_group_promotions/update
security:
- pinterest_oauth2:
- ads:write
x-ratelimit-category: ads_write
x-sandbox: disabled
parameters:
- $ref: '#/components/parameters/path_ad_account_id'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ProductGroupPromotionUpdateRequest'
description: Parameters to update Product group promotions
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ProductGroupPromotionResponse'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
summary: Update product group promotions
tags:
- Groups
get:
description: 'List existing product group promotions associated with an ad account.
Include either ad_group_id or product_group_promotion_ids in your request.
<b>Note:</b> ad_group_ids and product_group_promotion_ids are mutually exclusive parameters.
Only provide one. If multiple options are provided, product_group_promotion_ids takes precedence over ad_group_ids. If none are provided, the endpoint returns an error.'
operationId: product_group_promotions/list
security:
- pinterest_oauth2:
- ads:read
x-ratelimit-category: ads_read
x-sandbox: disabled
parameters:
- $ref: '#/components/parameters/path_ad_account_id'
- $ref: '#/components/parameters/query_product_group_promotion_ids'
- $ref: '#/components/parameters/query_entity_statuses'
- $ref: '#/components/parameters/query_ad_group_id'
- $ref: '#/components/parameters/query_page_size'
- $ref: '#/components/parameters/query_order'
- $ref: '#/components/parameters/query_bookmark'
responses:
'200':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Paginated'
- type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/ProductGroupPromotionResponseItem'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
summary: Get product group promotions
tags:
- Groups
/ad_accounts/{ad_account_id}/product_group_promotions/{product_group_promotion_id}:
get:
description: Get a product group promotion by id
operationId: product_group_promotions/get
security:
- pinterest_oauth2:
- ads:read
x-ratelimit-category: ads_read
x-sandbox: disabled
parameters:
- $ref: '#/components/parameters/path_ad_account_id'
- $ref: '#/components/parameters/path_product_group_promotion_id'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ProductGroupPromotionResponse'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
summary: Get a product group promotion by id
tags:
- Groups
/ad_accounts/{ad_account_id}/product_groups/analytics:
get:
summary: Get product group analytics
description: 'Get analytics for the specified product groups in the specified <code>ad_account_id</code>, filtered by the specified options.
- The token''s user_account must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via <a href="https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts">Business Access</a>: Admin, Analyst, Campaign Manager.
- If granularity is not HOUR, the furthest back you can are allowed to pull data is 90 days before the current date in UTC time and the max time range supported is 90 days.
- If granularity is HOUR, the furthest back you can are allowed to pull data is 8 days before the current date in UTC time and the max time range supported is 3 days.'
operationId: product_groups/analytics
security:
- pinterest_oauth2:
- ads:read
x-ratelimit-category: ads_analytics
x-sandbox: disabled
parameters:
- $ref: '#/components/parameters/path_ad_account_id'
- $ref: '#/components/parameters/query_start_date'
- $ref: '#/components/parameters/query_end_date'
- $ref: '#/components/parameters/query_product_group_ids_required'
- $ref: '#/components/parameters/query_columns'
- $ref: '#/components/parameters/query_granularity'
- $ref: '#/components/parameters/query_conversion_attribution_click_window_days'
- $ref: '#/components/parameters/query_conversion_attribution_engagement_window_days'
- $ref: '#/components/parameters/query_conversion_attribution_view_window_days'
- $ref: '#/components/parameters/query_conversion_attribution_conversion_report_time'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ProductGroupAnalyticsResponse'
description: Success
'400':
description: Invalid ad account ads analytics parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 400
message: Invalid ad account ads analytics parameters.
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Groups
/ad_accounts/{ad_account_id}/product_groups/catalogs:
get:
deprecated: true
description: This endpoint is completely deprecated. Please use <a href='/docs/api/v5/#operation/catalogs_product_groups/list'>List product groups</a> from Catalogs API instead.
operationId: ad_accounts_catalogs_product_groups/list
security:
- pinterest_oauth2:
- ads:write
x-ratelimit-category: ads_write
x-sandbox: disabled
parameters:
- $ref: '#/components/parameters/path_ad_account_id'
- $ref: '#/components/parameters/query_feed_profile_id'
responses:
'200':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Paginated'
- type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/CatalogProductGroup'
description: Success
'400':
description: Invalid ad account ads parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 400
message: Invalid ad account ads parameters.
'401':
description: Access Denied. This can happen if account is not yet approved to operate as Merchant on Pinterest.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Merchant data not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
summary: Get catalog product groups
tags:
- Groups
/catalogs/product_groups/multiple:
delete:
x-ratelimit-category: catalogs_write
summary: Delete multiple product groups
description: 'Delete product groups owned by the "operation user_account".
- By default, the "operation user_account" is the token user_account.
Optional: Business Access: Specify an <code>ad_account_id</code> (obtained via <a href=''/docs/api/v5/#operation/ad_accounts/list''>List ad accounts</a>) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following <a href="https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts">Business Access</a> roles on the ad_account: Owner, Admin, Catalogs Manager.
<a href=''/docs/shopping/catalog/''>Learn more</a>'
operationId: catalogs_product_groups/delete_many
x-sandbox: enabled
parameters:
- $ref: '#/components/parameters/query_catalogs_product_group_ids_required'
- $ref: '#/components/parameters/query_ad_account_id'
security:
- pinterest_oauth2:
- catalogs:write
responses:
'204':
description: Catalogs Product Groups deleted successfully.
'401':
description: Unauthorized access.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
UnauthorizedAccess:
value:
code: 29
message: You are not permitted to access that resource.
'403':
description: Forbidden. Account not approved for catalog product group mutations yet.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
MerchantDisapproved:
value:
code: 2625
message: Sorry, you cannot perform this action. Account is disapproved.
MerchantUnderReview:
value:
code: 2626
message: Sorry, you cannot perform this action. Account is under review.
'404':
description: Catalogs product group not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
CatalogsProductGroupNotFound:
value:
code: 4180
message: Sorry! We could not find your catalogs product group.
'409':
description: Conflict. Can't delete this catalogs product group.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
CatalogsProductGroupHasActivePromotions:
value:
code: 4176
message: We can't delete a Catalogs Product Group with active promotions.
CannotAlterAutoGeneratedCatalogsProductGroup:
value:
code: 4177
message: You cannot alter an auto generated catalogs product group.
CatalogsMerchantNotCreated:
value:
code: 4182
message: Can't access this feature without an existing catalog.
default:
description: Unexpected error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Groups
post:
x-ratelimit-category: catalogs_write
summary: Create multiple product group
description: 'Create product group to use in Catalogs owned by the "operation user_account".
- By default, the "operation user_account" is the token user_account.
Optional: Business Access: Specify an <code>ad_account_id</code> (obtained via <a href=''/docs/api/v5/#operation/ad_accounts/list''>List ad accounts</a>) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following <a href="https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts">Business Access</a> roles on the ad_account: Owner, Admin, Catalogs Manager.
<a href=''/docs/shopping/catalog/''>Learn more</a>
Note: The catalog type of Creative Assets is only allowed in the <a href=''https://api-sandbox.pinterest.com/v5''>Pinterest API Sandbox</a>.
If access is required, please contact your partner manager.'
operationId: catalogs_product_groups/create_many
security:
- pinterest_oauth2:
- catalogs:write
x-sandbox: enabled
parameters:
- $ref: '#/components/parameters/query_ad_account_id'
requestBody:
description: Request object used to create one or more catalogs product groups.
required: true
content:
application/json:
schema:
type: array
title: multiple product groups
items:
oneOf:
- $ref: '#/components/schemas/CatalogsProductGroupCreateRequest'
- $ref: '#/components/schemas/CatalogsVerticalProductGroupCreateRequest'
examples:
RetailFewFiltersUsingAllOf:
summary: A simple retail example that applies "all of the following filters".
description: 'The use of "all_of" creates a Product Group where all of the individual filters
must be satisfied by a product to be included in the Product Group.
'
value:
- name: Few Filters using "all_of"
feed_id: '2680059592705'
featured: false
filters:
all_of:
- MIN_PRICE:
values: 999.99
inclusion: true
- CURRENCY:
values: USD
- CUSTOM_LABEL_0:
values:
- Luxury Items
RetailManyFiltersUsingAnyOf:
summary: A more complete retail example that applies "any of the following filters".
description: 'The use of "any_of" creates a Product Group where any of the individual filters
can add products to the Product Group independently.
'
value:
- name: Many Filters using "any_of"
featured: false
feed_id: '2680059592705'
filters:
all_of:
- MIN_PRICE:
values: 111.55
inclusion: false
negated: false
- CURRENCY:
values: USD
negated: false
- AVAILABILITY:
values:
- IN_STOCK
- OUT_OF_STOCK
- PREORDER
negated: false
- BRAND:
values:
- avanti
- beautyrest
negated: true
- GOOGLE_PRODUCT_CATEGORY_0:
values:
- - furniture
- tables
- accent tables
- end tables
- - furniture
- chairs
- slipper chairs
- - home & garden
negated: false
- CONDITION:
values:
- NEW
- REFURBISHED
- USED
negated: false
- CUSTOM_LABEL_0:
values:
- 004 - home furn leisure
negated: false
- CUSTOM_LABEL_1:
values:
- clearance
- original price
negated: false
- CUSTOM_LABEL_2:
values:
- 789 - table linens
- 794 - living room accents
negated: false
- GENDER:
values:
- FEMALE
- MALE
- UNISEX
nega
# --- truncated at 32 KB (182 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/pinterest/refs/heads/main/openapi/pinterest-groups-api-openapi.yml