Pinterest Audience API
The Audience API from Pinterest — 3 operation(s) for audience.
OpenAPI Specification
openapi: 3.0.3
info:
version: 5.13.0
title: Pinterest Audience 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: Audience
paths:
/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:
- Audience
/ad_accounts/{ad_account_id}/audience_insights:
get:
summary: Get audience insights
description: 'Get Audience Insights for an ad account. The response will return insights for 3 types of audiences: the
ad account''s engaged audience on Pinterest, the ad account''s total audience on Pinterest and Pinterest''s
total audience.<p/>
<a href="https://help.pinterest.com/en/business/article/audience-insights" target="_blank">Learn more about Audience Insights</a>.'
operationId: audience_insights/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/query_audience_insight_type'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AudienceInsightsResponse'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
tags:
- Audience
/ad_accounts/{ad_account_id}/audiences/{audience_id}:
get:
summary: Get audience
description: Get a specific audience given the audience ID.
operationId: audiences/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_audience_id'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Audience'
'404':
description: Audience not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
default:
description: Unexpected error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Audience
patch:
summary: Update audience
description: Update (edit or remove) an existing targeting audience.
operationId: audiences/update
security:
- pinterest_oauth2:
- ads:write
x-ratelimit-category: ads_write
x-sandbox: disabled
parameters:
- $ref: '#/components/parameters/path_ad_account_id'
- $ref: '#/components/parameters/path_audience_id'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AudienceUpdateRequest'
description: The audience to be updated.
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Audience'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
tags:
- Audience
components:
parameters:
path_ad_account_id:
name: ad_account_id
description: Unique identifier of an ad account.
in: path
required: true
schema:
type: string
pattern: ^\d+$
maxLength: 18
query_audience_insight_type:
description: Type of audience insights.
explode: false
in: query
name: audience_insight_type
required: true
schema:
$ref: '#/components/schemas/AudienceInsightType'
path_audience_id:
name: audience_id
description: Unique identifier of an audience
in: path
required: true
schema:
type: string
pattern: ^\d+$
maxLength: 18
schemas:
AudienceDemographics:
title: AudienceDemographics
description: Audience demographics
type: object
properties:
ages:
title: ages
description: Ages distribution.
type: array
items:
$ref: '#/components/schemas/AudienceDemographicValue'
genders:
title: genders
description: Gender distribution.
type: array
items:
$ref: '#/components/schemas/AudienceDemographicValue'
devices:
title: devices
description: Device usage distribution.
type: array
items:
$ref: '#/components/schemas/AudienceDemographicValue'
metros:
title: metros
description: Geographic metro area distribution.
type: array
items:
$ref: '#/components/schemas/AudienceDemographicValue'
countries:
title: countries
description: Country area distribution.
type: array
items:
$ref: '#/components/schemas/AudienceDemographicValue'
Error:
title: Error
type: object
properties:
code:
type: integer
message:
type: string
required:
- code
- message
AudienceCommon:
title: AudienceCommon
type: object
properties:
ad_account_id:
title: ad_account_id
description: Ad account ID.
type: string
example: '549755885175'
pattern: ^\d+$
name:
title: name
description: Audience name.
type: string
example: string
rule:
$ref: '#/components/schemas/AudienceRule'
Audience:
properties:
ad_account_id:
description: Ad account ID.
example: '549755885175'
pattern: ^\d+$
title: ad_account_id
type: string
id:
description: Audience ID.
example: '1234'
pattern: ^\d+$
title: id
type: string
name:
description: Audience name.
example: ACME Tools
title: name
type: string
audience_type:
type: string
description: '<a href="/docs/reference/glossary/#Audience Types">Audience types</a>: ACTALIKE, ENGAGEMENT, CUSTOMER_LIST and VISITOR'
title: audience_type
description:
description: Audience description.
example: People who love making quilts.
nullable: true
title: description
type: string
rule:
$ref: '#/components/schemas/AudienceRule'
size:
description: Audience size.
example: 1000
nullable: true
title: size
type: integer
status:
type: string
description: Audience status. READY, INITIALIZING, TOO_SMALL - Each audience list needs to have at least 100 people with Pinterest accounts before you can start using it.
title: status
type:
description: Always "audience".
example: audience
title: type
type: string
created_timestamp:
description: Creation time. Unix timestamp in seconds.
example: 1451431341
nullable: true
title: created_time
type: integer
updated_timestamp:
description: Last update time. Unix timestamp in seconds.
example: 1451431341
nullable: true
title: updated_time
type: integer
title: Audience
type: object
ObjectiveType:
type: string
description: Campaign objective type. If set as one of ["AWARENESS", "CONSIDERATION", "WEB_CONVERSION", "CATALOG_SALES"] the campaign is considered as a Campaign Budget Optimization (CBO) campaign, meaning budget needs to be set at the campaign level rather than at the ad group level. ["WEB_SESSIONS"] is DEPRECATED. For update, only draft campaigns may update objective type.
enum:
- AWARENESS
- CONSIDERATION
- VIDEO_VIEW
- WEB_CONVERSION
- CATALOG_SALES
- WEB_SESSIONS
AudienceInsightsResponse:
title: AudienceInsightsResponse
description: Audience interests and demographics.
type: object
properties:
categories:
title: categories
description: Category interest distribution
type: array
items:
$ref: '#/components/schemas/AudienceCategory'
demographics:
$ref: '#/components/schemas/AudienceDemographics'
type:
$ref: '#/components/schemas/AudienceInsightType'
date:
title: date
description: Generation date
type: string
nullable: true
example: '2022-10-09'
pattern: ^\d{4}-\d{2}-\d{2}$
size:
title: size
description: Population count.
type: integer
example: 10000
size_is_upper_bound:
title: size_is_upper_bound
description: Indicates whether the audience size has been rounded up to the next highest upper boundary.
type: boolean
example: true
TargetingSpec:
description: Ad group targeting specification defining the ad group target audience. For example, `{"APPTYPE":["iphone"], "GENDER":["male"], "LOCALE":["en-US"], "LOCATION":["501"], "AGE_BUCKET":["25-34"]}`
type: object
properties:
AGE_BUCKET:
type: array
nullable: true
description: Age ranges. If the AGE_BUCKET field is missing, the default behavior in terms of ad delivery is that **All age buckets** will be targeted.
example:
- 35-44
- 50-54
items:
type: string
enum:
- 18-24
- 21+
- 25-34
- 35-44
- 45-49
- 50-54
- 55-64
- 65+
APPTYPE:
type: array
nullable: true
description: Allowed devices. If the APPTYPE field is missing, the default behavior in terms of ad delivery is that **All devices/apptypes** will be targeted.
example:
- ipad
- iphone
items:
type: string
enum:
- android_mobile
- android_tablet
- ipad
- iphone
- web
- web_mobile
AUDIENCE_EXCLUDE:
type: array
nullable: true
description: '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**.'
items:
type: string
pattern: ^\d+$
minItems: 100
AUDIENCE_INCLUDE:
type: array
nullable: true
description: '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**.'
items:
type: string
pattern: ^\d+$
minItems: 100
GENDER:
type: array
nullable: true
description: '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**.'
items:
type: string
enum:
- unknown
- male
- female
GEO:
type: array
nullable: true
description: Location region codes, e.g., "BE-VOV" (East Flanders, Belgium) For complete list, <a href="https://help.pinterest.com/sub/helpcenter/partner/pinterest_location_targeting_codes.xlsx" target="_blank">click here</a> or postal codes, e.g., "US-94107". Use either region codes or postal codes but not both. At least one of LOCATION or GEO must be specified. If the GEO field is missing, then only LOCATION values will be targeted (see LOCATION field below).
items:
type: string
INTEREST:
type: array
description: 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**.
items:
type: string
LOCALE:
type: array
nullable: true
description: 24 ISO 639-1 two letter language codes. If the LOCALE field is missing, the default behavior in terms of ad delivery is that **All languages will be targeted, only english non-sublanguage will be targeted**.
items:
type: string
LOCATION:
type: array
nullable: true
description: 22 ISO Alpha 2 two letter country codes or US Nielsen DMA (Designated Market Area) codes (location region codes) (e.g., ["US", "807"]). For complete list, click here. Location-Country and Location-Metro codes apply. At least one of LOCATION or GEO must be specified. If the LOCATION field is missing, then only GEO values will be targeted (see GEO field above).
items:
type: string
SHOPPING_RETARGETING:
type: array
nullable: true
description: "Array of object: lookback_window\t[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"
items:
type: object
example:
lookback_window: 30
exclusion_window: 14
tag_types:
- 0
- 6
properties:
lookback_window:
description: Number of days ago to start lookback timeframe for dynamic retargeting
example: 30
title: lookback_window
type: integer
tag_types:
description: Event types to target for dynamic retargeting
example:
- 0
- 6
items:
type: integer
title: tag_types
type: array
exclusion_window:
description: Number of days ago to stop lookback timeframe for dynamic retargeting
example: 14
title: exclusion_window
type: integer
title: TargetingSpec_SHOPPING_RETARGETING
TARGETING_STRATEGY:
type: array
nullable: true
description: ''
items:
enum:
- CHOOSE_YOUR_OWN
- FIND_NEW_CUSTOMERS
- RECONNECT_WITH_USERS
AdGroupAudienceSizingRequest:
type: object
properties:
auto_targeting_enabled:
type: boolean
description: Enable auto-targeting for ad group. Also known as <a href="https://help.pinterest.com/en/business/article/expanded-targeting" target="_blank">"expanded targeting"</a>.
example: true
default: true
placement_group:
type: string
allOf:
- $ref: '#/components/schemas/PlacementGroupType'
default: ALL
description: <a href="/docs/redoc/#section/Placement-group">Placement group</a>.
creative_types:
description: Pin creative types filter. </p><strong>Note:</strong> SHOP_THE_PIN has been deprecated. Please use COLLECTION instead.
type: array
items:
type: string
example: REGULAR
enum:
- REGULAR
- VIDEO
- SHOPPING
- CAROUSEL
- MAX_VIDEO
- SHOP_THE_PIN
- COLLECTION
- IDEA
nullable: true
targeting_spec:
$ref: '#/components/schemas/TargetingSpec'
product_group_ids:
type: array
items:
type: string
pattern: ^\d+$
example: '23423422123'
description: Targeted product group IDs. </p><strong>Note:</strong> This can only be combined with shopping/catalog sales campaigns. For more information, <a href="https://help.pinterest.com/en/business/article/shopping-ads#section-14571" target="_blank">click here</a>. SHOPPING_RETARGETING must be included in targeting_spec object or this field will be ignored.
nullable: true
keywords:
type: array
description: Array of keyword objects. If the keywords field is missing, all keywords will be targeted.
items:
type: object
properties:
match_type:
$ref: '#/components/schemas/MatchTypeResponse'
value:
type: string
description: Keyword value (120 chars max).
required:
- match_type
- value
nullable: true
MatchTypeResponse:
type: string
description: Keyword match type
nullable: true
example: BROAD
enum:
- BROAD
- PHRASE
- EXACT
- EXACT_NEGATIVE
- PHRASE_NEGATIVE
- null
Currency:
type: string
description: Currency Codes from ISO 4217
example: USD
enum:
- UNK
- USD
- GBP
- CAD
- EUR
- AUD
- NZD
- SEK
- ILS
- CHF
- HKD
- JPY
- SGD
- KRW
- NOK
- DKK
- PLN
- RON
- HUF
- CZK
- BRL
- MXN
- ARS
- CLP
- COP
AudienceDemographicValue:
title: AudienceDemographicValue
description: Demographic detail for a single audience demographic
type: object
properties:
key:
title: key
description: Unique key for demographic item
type: string
example: us
name:
title: name
description: Display name for demographic
type: string
example: United States
ratio:
title: ratio
description: Value of demographic item as a percent of total audience
type: number
example: 0.551
example:
name: United States
key: us
ratio: 0.551
AudienceUpdateRequest:
type: object
allOf:
- $ref: '#/components/schemas/AudienceCommon'
- title: AudienceUpdateRequest
type: object
properties:
description:
$ref: '#/components/schemas/AudienceDescription'
operation_type:
$ref: '#/components/schemas/AudienceUpdateOperationType'
AudienceRule:
description: 'JSON object defining targeted audience users. Example rule formats per audience type:<br>CUSTOMER_LIST: { "customer_list_id": "<customer list ID>"}<br>ACTALIKE: { "seed_id": ["<audience ID>"], "country": "US", "percentage": "10" }<br>(Valid countries include: "US", "CA", and "GB". Percentage should be 1-10.<br>The targeted audience should be this % size across Pinterest.)<br>VISITOR: { "visitor_source_id": ["<conversion tag ID>"], "retention_days": "180", "event_source": {"=": ["web", "mobile"]}, "ingestion_source": {"=": ["tag"]}}<br>(Retention days should be 1-540. Retention applies to specific customers.)<br>ENGAGEMENT: {"engagement_domain": ["www.entomi.com"], "engager_type": 1}<br>For more details on engagement audiences, see <a href="https://developers.pinterest.com/docs/redoc/adtech_ads_v4/#section/November-2021" target="_blank">November 2021 changelog</a>.'
properties:
country:
description: 'Valid countries include: "US", "CA", and "GB".'
example: US
title: country
type: string
customer_list_id:
description: Customer list ID. For CUSTOMER_LIST `audience_type`.
example: '5497558859876'
pattern: ^\d+$
title: customer_list_id
type: string
engagement_domain:
description: The audience account's verified domain. **Required** for ENGAGEMENT `audience_type`.
example:
- www.somedomain.com
items:
type: string
title: engagement_domain
type: array
engagement_type:
description: 'Engagement type enum. Optional for ENGAGEMENT `audience_type`. Supported values are `click`, `save`, `closeup`, `comment` and `like`. All engagements are included if this field is not set. '
example: click
title: engagement_type
type: string
event:
description: A Pinterest tag event. Optional for VISITOR `audience_type`. Possible values are `pagevisit`, `signup`, `checkout`, `viewcategory`, `search`, `addtocart`, `watchvideo`, `lead`, and `custom`. This field also accepts a partner-defined Pinterest tag event.
example: checkout
title: event
type: string
event_data:
description: 'Optional for VISITOR `audience_type`. With the Pinterest tag, you can use event data to capture event details from your website. This object lists all the available predefined event data fields in the Pinterest tag. You can include these event data fields as part of a VISITOR audience s `rule`; however, you **must** specify an `event` for the `event_data` fields to be evaluated. Besides whats listed, you can also create your own set of `event_data` fields and define their usages or purposes according to your website needs. However, the benefit of using the predefined event data fields is that we can provide various metrics based on those fields'' data.<br>Examples per `event` type:<br>`pagevisit`<br>"event_data": { "page_name": "My online store 123 | view items | shoe" }<br>`signup`<br>"event_data": { "lead_type": "New release promotion" }<br>`checkout`<br>"event_data": { "value": 116, "order_quantity": 2, "currency": "USD", "line_items": [ { "product_name": "Pillows (Set of 2)", "product_id": "11", "product_price": 48, "product_quantity": 1 }, { "product_name": "Pillows, Large (Set of 2)", "product_id": "15", "product_price": 68, "product_quantity": 1 } ] }<br>`addtocart`<br>"event_data": { "value": 499, "order_quantity": 1, "currency": "USD", "line_items": [ { "product_name": "Red leather boots", "product_id": "3486", "product_category": "shoe", "product_variant_id": "JB11103000", "product_price": 499, "product_quantity": "1" , "product_brand": "My brand" }]}<br>`watchvideo`<br>"event_data": { "video_title": "My Product Video 01" }<br>`lead`<br>"event_data": { "lead_type": "Newsletter" }'
properties:
currency:
$ref: '#/components/schemas/Currency'
lead_type:
description: Promotion code. For example, "Newsletter".
example: Newsletter
title: lead_type
type: string
line_items:
properties:
product_brand:
description: Product brand. For example, "Parker".
example: Parker
title: product_brand
type: string
product_category:
description: Product category. For example, "Shoes".
example: Shoes
title: product_category
type: string
product_id:
description: Product ID. For example, 1414.
example: 1414
title: product_id
type: integer
product_name:
description: Product name. For example, "Parker Boots".
example: Parker Boots
title: product_name
type: string
product_price:
description: Product price. For example, "99.99".
example: '99.99'
title: product_price
type: string
product_quantity:
description: Product quantity. For example, 2.
example: 2
title: product_quantity
type: integer
product_variant:
description: Product variant. For example, "Red".
example: Red
title: product_variant
type: string
product_variant_id:
description: Product variant ID. For example, "1414-34832".
example: 1414-34832
title: product_variant_id
type: string
title: LineItem
type: object
order_id:
description: Order ID. For example, "X-151481".
example: X-151481
title: order_id
type: string
order_quantity:
description: Order quantity. For example, 1.
example: 1
title: order_quantity
type: integer
page_name:
description: Page name. For example, "Our Favorite Pins on Pinterest".
example: Our Favorite Pins on Pinterest.
title: page_name
type: string
promo_code:
description: Promotion code. For example, "WINTER10".
example: WINTER10
title: promo_code
type: string
property:
description: Property. For example, "Athleta".
example: Athleta
title: property
type: string
search_query:
description: Search query string. For example, "boots".
example: boots
title: search_query
type: string
value:
description: Product value. For example, "199.98"
example: '199.98'
title: value
type: string
video_title:
description: Video title. For example, "How to style your Parker Boots".
example: How to style your Parker Boots
title: video_title
type: string
title: PinterestTagEventData
type: object
percentage:
description: Percentage should be 1-10. The targeted audience should be this % size across Pinterest.
example: 3
title: percentage
type: integer
pin_id:
description: 'IDs of engaged organic pins. Optional for ENGAGEMENT `audience_type`. For example, "pin_id:": ["34567"]'
example:
- '34567'
items:
pattern: ^\d+$
type: string
title: pin_id
type: array
prefill:
description: Optional for VISITOR `audience_type`. If `true`, the specified rule on existing engagement data is applied to pre-populate the audience. If `false`, the audience is empty at creation time. The default is `true`.
example: true
title: prefill
type: boolean
retention_days:
description: Number of days a Pinterest user remains in the audience. Optional for ENGAGEMENT and VISITOR `audience_type`. Accepted range is 1-540. Defaults to 180 if not specified.
example: 30
title: retention_days
type: integer
seed_id:
description: 'Audience ID(s). For ACTALIKE `audience_type`. '
example:
- '2542620639259'
- '2542620639261'
items:
pattern: ^\d+$
type: string
title: seed_id
type: array
url:
description: 'Optional for ENGAGEMENT or VISITOR `audience_type`. For ENGAGEMENT, it is the engaged pin''s URL. For VISITOR, you can use it as a string or a {operator: value} object for filtering visitors based on conversion tag event URLs. Supported operators are [ =, !=, contains, not_contains].<br>Example 1: "url": "http://www.myonlinestore123.com/view_item/shoe"<br>Example 2: "url": {"contains": "/view_item/shoe"}'
items:
type: string
title: url
type: array
visitor_source_id:
description: The conversion tag ID, or the Pinterest tag ID, that you use on your website. For VISITOR `audience_type`.
example: '549755885175'
pattern: ^\d+$
title: visitor_source_id
type: string
event_source:
description: 'Optional for VISITOR. You can use it as a {''='': [value]}. Supported values are: web, mobile, offline'
example:
'=':
- web
- mobile
title: event_source
type: object
ingestion_source:
description: 'Optional for VISITOR. You can use it as a {''='': [value]}. Supported values are: tag, mmp, file_upload, conversions_api'
example:
'=':
- tag
title: ingestion_source
type: object
engager_type:
description: Optional for ENGAGEMENT. Engager type value should be 1-2.
example: 1
title: engager_type
type: integer
campaign_id:
description: Campaign ID for engagement audience filter.
example:
- '626744528398'
items:
pattern: ^\d+$
type: string
title: campaign_id
type: array
ad_id:
description: Ad ID for engagement audience filter.
example:
- '687201361754'
items:
pattern: ^\d+$
type: string
title: ad_id
type: array
objective_type:
description: Objective for engagement audience filter.
example:
- AW
# --- truncated at 32 KB (38 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/pinterest/refs/heads/main/openapi/pinterest-audience-api-openapi.yml