ad_accounts14

ad_groups13

ads10

advanced_auction2

audience_insights2

audience_sharing7

audiences4

billing11

boards11

bulk3

business_access_assets12

business_access_invite6

business_access_relationships9

campaigns8

catalog_feeds8

catalog_items3

catalog_product_groups10

catalog_reports3

catalog_supplemental7

catalogs3

conversion_deletion_requests4

conversion_eqs1

conversion_events1

conversion_tags5

conversions4

customer_list_uploads3

customer_lists4

customer_segment3

integrations7

keywords5

labels5

lead_ads4

lead_forms5

leads_export2

media3

msot_events1

notification1

oauth3

order_lines2

pins8

product_group_promotions5

product_tags3

promotions5

resources6

schedules3

search3

targeting_template3

terms2

terms_of_service1

trends4

user_account14

audiences

Create audience

Changed on Jun 4, 2026

Create a new audience for the ad account.

post/ad_accounts/{ad_account_id}/audiences

Request

Base URL
https://api.pinterest.com/v5
Auth
OAuth 2
Authorization codehttps://www.pinterest.com/oauth/
Token URLhttps://api.pinterest.com/v5/oauth/token
Scopesads:write
TypeScript
https://skmtc.dev/pinterest/apis/pinterest-rest-api/docs/ad_accounts/:ad_account_id/audiences/post.ts
A function with typed inputs. Its response is checked against the schema.

Path parameters

ad_account_idstring required

Unique identifier of an ad account.

Request body

ad_account_idstring

Ad account ID.

audience_type'CUSTOMER_LIST' | 'VISITOR' | 'ENGAGEMENT' | 'ACTALIKE' | 'PERSONA'

Audience type

descriptionstring nullable

Audience description.

namestring

Audience name.

Example request

{
  "audience_type": "ACTALIKE",
  "rule": {
    "event_data": {
      "lead_type": "Newsletter",
      "line_items": {
        "product_brand": "Parker",
        "product_category": "Shoes",
        "product_id": 1414,
        "product_name": "Parker Boots",
        "product_price": "99.99",
        "product_quantity": 2,
        "product_variant": "Red",
        "product_variant_id": "1414-34832"
      },
      "order_id": "X-151481",
      "order_quantity": 1,
      "page_name": "Our Favorite Pins on Pinterest",
      "promo_code": "WINTER10",
      "property": "Athleta",
      "search_query": "boots",
      "value": "199.98",
      "video_title": "How to style your Parker Boots"
    }
  }
}

Response

The request has succeeded.

ad_account_idstring

Ad account ID.

audience_type'CUSTOMER_LIST' | 'VISITOR' | 'ENGAGEMENT' | 'ACTALIKE' | 'PERSONA'

Audience type

created_by_company_namestring nullable

The company that created this audience.

created_timestampinteger nullable

Creation time. Unix timestamp in seconds.

descriptionstring nullable

Audience description.

idstring required

Audience ID.

is_ncaboolean

Whether the audience derives from a new customer acquisition (expanded matching) customer list. Read-only.

namestring

Audience name.

sizeinteger nullable

Audience size.

Audience processing status

typestring

Always "audience".

updated_timestampinteger nullable

Last update time. Unix timestamp in seconds.

Example response

{
  "audience_type": "ACTALIKE",
  "rule": {
    "event_data": {
      "lead_type": "Newsletter",
      "line_items": {
        "product_brand": "Parker",
        "product_category": "Shoes",
        "product_id": 1414,
        "product_name": "Parker Boots",
        "product_price": "99.99",
        "product_quantity": 2,
        "product_variant": "Red",
        "product_variant_id": "1414-34832"
      },
      "order_id": "X-151481",
      "order_quantity": 1,
      "page_name": "Our Favorite Pins on Pinterest",
      "promo_code": "WINTER10",
      "property": "Athleta",
      "search_query": "boots",
      "value": "199.98",
      "video_title": "How to style your Parker Boots"
    }
  }
}

Changes

Jun 4, 2026v5b698c180678a Revision changes
- breaking
  response property rule/percentage list-of-types was widened by adding types string to media type application/json of response 200
- breaking
  response property rule/visitor_source_id list-of-types was widened by adding types array to media type application/json of response 200
- breaking
  the response's property type changed from string to no type for status
- breaking
  the / response's property type changed from array to no type for status
- breaking
  the response's property type changed from string to no type for status
- warning
  removed subschema #2: AudienceCreateRequest from the request body allOf list
- warning
  added the new SALES enum value to the // response property for the response status
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the optional property to the response with the status
- info
  the response optional property became read-only for the status
- info
  the response optional property became read-only for the status
- info
  the response optional property became read-only for the status
- info
  the response optional property became read-only for the status
- info
  the response optional property became read-only for the status
- info
  the response optional property became read-only for the status
- info
  added to the response property allOf list for the response status
- info
  added to the response property allOf list for the response status
- info
  added subschema #1 subschema #2 to the / response property anyOf list for the response status
- info
  the response property became required for the status
- info
  the // response's property pattern ^\d+$ was removed for the status
- info
  the // response's property pattern ^\d+$ was removed for the status
- info
  the // response's property pattern ^\d+$ was removed for the status
- info
  the / response's property pattern ^\d+$ was removed for the status
- info
  added the success response with the status
Dec 11, 2025v579f62f71f05b Revision changes
- breaking
  added to the /// request property allOf list
- breaking
  added to the /// request property allOf list
- breaking
  removed the enum value ARS of the request property ///
- breaking
  removed the enum value AUD of the request property ///
- breaking
  removed the enum value BRL of the request property ///
- breaking
  removed the enum value CAD of the request property ///
- breaking
  removed the enum value CHF of the request property ///
- breaking
  removed the enum value CLP of the request property ///
- breaking
  removed the enum value COP of the request property ///
- breaking
  removed the enum value CZK of the request property ///
- breaking
  removed the enum value DKK of the request property ///
- breaking
  removed the enum value EUR of the request property ///
- breaking
  removed the enum value GBP of the request property ///
- breaking
  removed the enum value HKD of the request property ///
- breaking
  removed the enum value HUF of the request property ///
- breaking
  removed the enum value ILS of the request property ///
- breaking
  removed the enum value INR of the request property ///
- breaking
  removed the enum value JPY of the request property ///
- breaking
  removed the enum value KRW of the request property ///
- breaking
  removed the enum value MXN of the request property ///
- breaking
  removed the enum value NOK of the request property ///
- breaking
  removed the enum value NZD of the request property ///
- breaking
  removed the enum value PLN of the request property ///
- breaking
  removed the enum value RON of the request property ///
- breaking
  removed the enum value SEK of the request property ///
- breaking
  removed the enum value SGD of the request property ///
- breaking
  removed the enum value TRY of the request property ///
- breaking
  removed the enum value UNK of the request property ///
- breaking
  removed the enum value USD of the request property ///
- breaking
  the /// request property type changed from string to no type
- breaking
  the /// request property type changed from object to no type
- breaking
  the // response's property type changed from string to no type for status
- breaking
  the // response's property type changed from object to no type for status
- warning
  removed the request property ////
- warning
  removed the request property ////
- warning
  removed the request property ////
- warning
  removed the request property ////
- warning
  removed the request property ////
- warning
  removed the request property ////
- warning
  removed the request property ////
- warning
  removed the request property ////
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- info
  added to the // response property allOf list for the response status
- info
  added to the // response property allOf list for the response status
- info
  removed the ARS enum value from the // response property for the response status
- info
  removed the AUD enum value from the // response property for the response status
- info
  removed the BRL enum value from the // response property for the response status
- info
  removed the CAD enum value from the // response property for the response status
- info
  removed the CHF enum value from the // response property for the response status
- info
  removed the CLP enum value from the // response property for the response status
- info
  removed the COP enum value from the // response property for the response status
- info
  removed the CZK enum value from the // response property for the response status
- info
  removed the DKK enum value from the // response property for the response status
- info
  removed the EUR enum value from the // response property for the response status
- info
  removed the GBP enum value from the // response property for the response status
- info
  removed the HKD enum value from the // response property for the response status
- info
  removed the HUF enum value from the // response property for the response status
- info
  removed the ILS enum value from the // response property for the response status
- info
  removed the INR enum value from the // response property for the response status
- info
  removed the JPY enum value from the // response property for the response status
- info
  removed the KRW enum value from the // response property for the response status
- info
  removed the MXN enum value from the // response property for the response status
- info
  removed the NOK enum value from the // response property for the response status
- info
  removed the NZD enum value from the // response property for the response status
- info
  removed the PLN enum value from the // response property for the response status
- info
  removed the RON enum value from the // response property for the response status
- info
  removed the SEK enum value from the // response property for the response status
- info
  removed the SGD enum value from the // response property for the response status
- info
  removed the TRY enum value from the // response property for the response status
- info
  removed the UNK enum value from the // response property for the response status
- info
  removed the USD enum value from the // response property for the response status

Operation history (8 revisions)