Pinterest Audiences API
The Audiences API from Pinterest — 1 operation(s) for audiences.
OpenAPI Specification
openapi: 3.0.3
info:
version: 5.13.0
title: Pinterest Audiences 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: Audiences
paths:
/ad_accounts/{ad_account_id}/audiences:
get:
summary: List audiences
description: Get list of audiences for the ad account.
operationId: audiences/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_bookmark'
- description: 'The order in which to sort the items returned: ASCENDING or DESCENDING by ID.
For received audiences, it is sorted by sharing event time.
Note that higher-value IDs are associated with more-recently added items.'
in: query
name: order
required: false
schema:
type: string
example: ASCENDING
enum:
- ASCENDING
- DESCENDING
- $ref: '#/components/parameters/query_page_size'
- description: '<strong>This feature is currently in beta and not available to all apps.</strong>
Filter audiences by ownership type.'
in: query
name: ownership_type
required: false
example: OWNED
schema:
type: string
default: OWNED
enum:
- OWNED
- RECEIVED
responses:
'200':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Paginated'
- type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/Audience'
description: Success
'400':
description: Invalid ad account audience parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 400
message: Invalid ad account audience parameters.
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Audiences
post:
description: 'Create an audience you can use in targeting for specific ad groups. Targeting combines customer information with
the ways users interact with Pinterest to help you reach specific groups of users; you can include or exclude
specific audience_ids when you create an ad group. <p/>
For more, see <a class="reference external" href="https://help.pinterest.com/en/business/article/audience-targeting" target="_blank">Audience targeting</a>.'
operationId: audiences/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/AudienceCreateRequest'
description: List of ads to create, size limit [1, 30]
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Audience'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
summary: Create audience
tags:
- Audiences
components:
parameters:
query_page_size:
name: page_size
description: Maximum number of items to include in a single page of the response. See documentation on <a href='/docs/getting-started/pagination/'>Pagination</a> for more information.
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 250
default: 25
query_bookmark:
name: bookmark
description: Cursor used to fetch the next page of items
in: query
required: false
schema:
type: string
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
schemas:
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
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:
- AWARENESS
items:
$ref: '#/components/schemas/ObjectiveType'
title: objective_type
type: array
ad_account_id:
description: Ad account ID.
example: '549755885175'
pattern: ^\d+$
title: ad_account_id
type: string
title: Rule
type: object
AudienceDescription:
title: description
description: Audience description.
type: string
example: string
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'
AudienceCreateRequest:
type: object
allOf:
- $ref: '#/components/schemas/AudienceCommon'
- title: AudienceCreateRequest
required:
- audience_type
- name
- rule
properties:
description:
$ref: '#/components/schemas/AudienceDescription'
audience_type:
type: string
allOf:
- $ref: '#/components/schemas/AudienceType'
- title: audience_type
description: '<a href="/docs/reference/glossary/#Audience Types">Audience types</a>: ACTALIKE, ENGAGEMENT, CUSTOMER_LIST and VISITOR. Values are case-sensitive.'
AudienceType:
description: Audience type
enum:
- CUSTOMER_LIST
- VISITOR
- ENGAGEMENT
- ACTALIKE
- PERSONA
example: ACTALIKE
title: AudienceType
type: string
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
Paginated:
type: object
properties:
items:
type: array
items:
type: object
bookmark:
type: string
nullable: true
required:
- items
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
securitySchemes:
pinterest_oauth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://www.pinterest.com/oauth/
tokenUrl: https://api.pinterest.com/v5/oauth/token
scopes:
ads:read: See all of your advertising data, including ads, ad groups, campaigns etc.
ads:write: Create, update, or delete ads, ad groups, campaigns etc.
billing:read: See all of your billing data, billing profile, etc.
billing:write: Create, update, or delete billing data, billing profiles, etc.
biz_access:read: See business access data
biz_access:write: Create, update, or delete business access data
boards:read: See your public boards, including group boards you join
boards:read_secret: See your secret boards
boards:write: Create, update, or delete your public boards
boards:write_secret: Create, update, or delete your secret boards
catalogs:read: See all of your catalogs data
catalogs:write: Create, update, or delete your catalogs data
pins:read: See your public Pins
pins:read_secret: See your secret Pins
pins:write: Create, update, or delete your public Pins
pins:write_secret: Create, update, or delete your secret Pins
user_accounts:read: See your user accounts and followers
user_accounts:write: Update your user accounts and followers
conversion_token:
type: http
scheme: bearer
description: This security scheme only applies to the conversion events endpoint (POST /ad_accounts/{ad_account_id}/events). This endpoint requires a bearer token generated via Ads Manager (ads.pinterest.com).
basic:
type: http
scheme: basic
x-tagGroups:
- name: Pin and Boards
tags:
- pins
- boards
- media
- aggregated_comments
- aggregated_pin_data
- user_account
- name: Campaign Management
tags:
- ad_accounts
- campaigns
- ad_groups
- ads
- product_group_promotions
- bulk
- name: Targeting
tags:
- audiences
- customer_lists
- keywords
- targeting_template
- audience_insights
- audience_sharing
- name: Ad Formats
tags:
- lead_forms
- lead_ads
- leads_export
- name: Billing
tags:
- billing
- order_lines
- terms_of_service
- name: Business Access
tags:
- business_access_assets
- business_access_invite
- business_access_relationships
- name: Conversions
tags:
- conversion_events
- conversion_tags
- name: Others
tags:
- integrations
- oauth
- resources
- search
- terms
- name: Shopping
tags:
- catalogs
- name: Deprecated
tags:
- product_groups