openapi: 3.0.3
info:
  version: 5.13.0
  title: Pinterest Custom 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: Custom
paths:
  /ad_accounts/{ad_account_id}/audiences/custom:
    post:
      summary: Create custom audience
      description: Create a custom audience and find the audiences you want your ads to reach.
      operationId: audiences/create_custom
      security:
      - pinterest_oauth2:
        - ads:write
      x-ratelimit-category: ads_write
      x-sandbox: disabled
      parameters:
      - $ref: '#/components/parameters/path_ad_account_id'
      requestBody:
        description: Custom audience to create.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AudienceCreateCustomRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Audience'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Custom
components:
  schemas:
    AudienceSharingType:
      description: 'Audience sharing type: ["CUSTOM", "SYNDICATED"]'
      type: string
      enum:
      - CUSTOM
      - SYNDICATED
    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
    AudienceCreateCustomRequest:
      type: object
      allOf:
      - $ref: '#/components/schemas/AudienceCommon'
      - title: AudienceCreateCustomRequest
        required:
        - sharing_type
        - name
        - rule
        - data_party
        properties:
          sharing_type:
            $ref: '#/components/schemas/AudienceSharingType'
          data_party:
            $ref: '#/components/schemas/AudienceDataParty'
          category:
            type: string
            example: DLX Demographics
    AudienceDataParty:
      description: Whether the data is owned by the partner (1p) or by the data provider (3p)
      type: string
      enum:
      - 1p
      - 3p
    AudienceRule:
      description: 'JSON object defining targeted audience users. Example rule formats per audience type:<br>CUSTOMER_LIST: { "customer_list_id": "&lt;customer list ID&gt;"}<br>ACTALIKE: { "seed_id": ["&lt;audience ID&gt;"], "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": ["&lt;conversion tag ID&gt;"], "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
    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
  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
  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