Create audiences

The people who you want to see your ads make up your audience. Targeting means getting your ads in front of those people.

How audience targeting works in the API

Audience targeting involves two major actions in the API:

Create an audience.
Reference the audience in the targeting spec of an ad group.

You also create and target audiences in Ads Manager.

Before you begin

Before creating an audience, make sure you have generated an OAuth access token that includes the following scopes:

ads:write
ads:read

You can create an audience with a minimum of 100 members. The API does not accept a lower number.

Select your audience type

Link to any of the listed audience types for detailed creation steps.

Audience types
Audience type	Audience description	How to create it in the API
Actalike	People who fit one of your existing audience profiles and are likely to engage with your Pins, or visit your website.	Base the audience on a seed audience derived either from a customer list or Pinterest Tag events.
Customer list	Customers on your database or CRM, whom you want to retarget.	Upload a .csv file of the list.
Engagement	Qualified audiences who have interacted with your Pinterest content with clicks, saves, closeups, or comments.	Define the engagement type in the audience creation endpoint.
Open	The broadest collection of Pinners, with no "type" specified.	Omit the `AUDIENCE_INCLUDE` parameter from your ad group targeting spec. You can still insert different targeting criteria in the ad group, such as location, age, or gender, or leave it open for maximum reach.
Persona	Specifically tailored audiences created by the Pinterest sales team. They include people who are not easily targeted by interest or with keywords.	Ask your account account manager about creating persona audiences for you. You cannot create a persona audience in the API.
Site visitor	Past visitors to your website, whom you want to retarget.	Using Pinterest Tag on your website, pull visitor data based on one or more event tags.

Set up an audience

Customer list audience

Customers on your database or CRM, whom you want to retarget, make up a customer list audience. Creating this type of audience involves posting a .csv-formatted list of your customers.

Step 1. Prepare your customer list

Include one or more of these identifiers in the list:

DataLogix ID (
DLX_ID
)
Email address (
EMAIL
)
Identifier for Advertisers (
IDFA
)
LiveRamp ID (
LR_ID
)
Mobile Advertising ID (
MAID
)
Pinterest user ID hashed with SHA-256 encryption (
HASHED_PINNER_ID
)

Format the .csv file as a sequence of records separated by commas with no header.

SHA-256 hashing of the records is not required but recommended as a best practice.

Step 2. Post the Customer List

POST

Create customer lists

Any parameters and code examples that appear in this section support this use case, but may not represent the full endpoint specification. See the endpoint reference page for the comprehensive spec.

Request parameters

Post the list as a single string using the following parameters:

Post list
Parameter	Description
`records` string required	One string of customer identifiers of any of the accepted types, separated by commas.
`list_type` string required	One of the posted audience types. You can only specify one type, even if you are posting multiple types.


curl --request POST \
  --url https://api.pinterest.com/v5/ad_accounts/120123456789/customer_lists \
  --header 'authorization: Bearer pina_ABCD1234...' \
  --header 'content-type: application/json' \
  --data '{
  "name": "Test customer list",
  "records": "b4e512f8ea8c8935d6bcdc2073e92f24f404a2dff396bc8a92f4ad89b27e1c37,24c989bb281c651d81d77f83144df486dd310438efe80fc4593ab6676075616a,2521cd1b18382856aa92dc6eb8cafced6f0abf12e230d25b1c4f8744931f7578,8ce72a6168ab067edf008b5f8395cbbce98ab7601af174cb8f556d3ff1a0067d,28c36759d8a5c0344d6f2feee8f3741fd9b19ca0d24af0a3fb894a32545d1471",
  "list_type": "EMAIL"
}'

Example response

If the request is successful, the endpoint returns an

id

, which is the new customer list ID to reference when you create the audience in the next step.


{
  "ad_account_id": "120123456789",
  "created_time": 1756331610,
  "id": "3972849",
  "name": "Test customer list",
  "num_batches": 1,
  "num_removed_user_records": 0,
  "num_uploaded_user_records": 5,
  "status": "PROCESSING",
  "type": "customerlist",
  "updated_time": 1756331611,
  "exceptions": {}
}

Step 3. Create the audience

POST

Create audience

Any parameters and code examples that appear in this section support this use case, but may not represent the full endpoint specification. See the endpoint reference page for the comprehensive spec.

Request parameters to keep in mind

Create customer list audience parameters
Parameter	Description
`rule` object (required)	Core part of the request that defines the logic and source data for building the audience.
`rule.customer_list_id`	`id` value that was returned when you posted the customer list in the preceding step.
`records` string required	One string of customer identifiers of any of the accepted types, separated by commas.

Example request for customer list audience


curl --request POST \
  --url https://api.pinterest.com/v5/ad_accounts/120123456789/audiences \
  --header 'authorization: Bearer pina_ABCD1234...' \
  --header 'content-type: application/json' \
  --data '{
  "ad_account_id": "120123456789",
  "name": "Test customer list",
  "rule": {
    "customer_list_id": "3969491"
  },
  "audience_type": "CUSTOMER_LIST"
}

Response fields to keep in mind

Status fields are common for all audience types.

Create customer list audience response fields
Field	Description
`id`	ID of the audience you created, which you will reference with the `AUDIENCE_INCLUDE` parameter when setting up the targeting spec.
`status`	Whether the audience can be targeted, and the reason if it cannot. `INITIALIZING` : Not ready. Audience is being created and processed. `PROCESSING` : Not ready. Posted audience data is being matched against Pinterest user accounts; or the audience segment is still being built. `TOO_SMALL` : Not usable; audience does not meet the 100-member minimum required for targeting. Note: There is no maximum number. `UPDATING` : Not ready. New audience data is being posted or other changes are in progress. `ARCHIVED` : Unavailable for targeting in new ad groups; audience is deactivated or retired, but visible in owner's account for record-keeping. `ERROR` : Audience cannot be processed due to an error. `READY` : Audience can be used for targeting. Audiences are typically ready in 48 hours, but may occasionally take up to 72 hours. Check the status of an audience anytime by calling GET Get audience .

Example response for customer list audience


{
  "ad_account_id": "120123456789",
  "id": "2542623177808",
  "name": "Test customer list",
  "audience_type": "CUSTOMER_LIST",
  "description": null,
  "rule": {
    "customer_list_id": "3969491"
  },
  "size": 0,
  "status": "INITIALIZING",
  "type": "audience",
  "created_timestamp": 1755727294,
  "updated_timestamp": 1755727295,
  "created_by_company_name": null
}

Actalike audience

People who fit one of your existing audience profiles and are likely to engage with your Pins, or visit your website, make up an actalike audience.

You base an actalike audience on a seed audience derived either from a customer list or Pinterest Tag events.

Before you begin

If you are creating a seed audience based on events on your site, set up the Pinterest Tag.

If you are creating a seed audience from a customer list, prepare and post your customer list.

Step 1. Create a seed audience

POST

Create audience

Any parameters and code examples that appear in this section support this use case, but may not represent the full endpoint specification. See the endpoint reference page for the comprehensive spec.

Request parameters to keep in mind

Create customer list audience parameters
Parameter	Description
`rule` object (required)	Core part of the request that defines the logic and source data for building the audience.
`rule.customer_list_id` string	Only for seed audience based on customer list. `id` value that was returned when you posted the customer list.
`rule.visitor_source_id` string	Only for seed audiences based on site events. Pinterest tag ID, that you use on your website for capturing events. You can pull the tag ID from the Conversions > Pinterest Tag > Tag manager section of your Ads Manager. If you do not have a Pinterest Tag, you can create one there.
`rule.ingestion_source` string	Only for seed audiences based on site events. Where the event data comes from. You may want to target audiences differently based on sources: `tag` `mmp` `file_upload` `conversions_api` To specify multiple sources, use the `in` operator as in this example: `"in": ["tag", "api"]` . To specify only one source, use the `=` filter operator as in the following .
`rule.event` string	Only for seed audiences based on site events. A user action that occurred on your site: `pagevisit` `signup` `checkout` `viewcategory` `search` `addtocart` `watchvideo` `lead`
`rule.value` string	Only for seed audiences based on site events. Filter condition that specifies a threshold or comparison for a numeric attribute of an event, such as the value of a purchase or the number of times an event occurred. In the following , the filter uses a comparison operator ( `>` ) to specify only users who triggered the `viewcategory` event more than `1` time.
`audience.type` string	For seed audience based on customer list, enter `CUSTOMER_LIST` . For seed audience based on site events, enter `VISITOR` .

Example request for seed audience based on events


curl --request POST \
  --url https://api.pinterest.com/v5/ad_accounts/120123456789/audiences \
  --header 'authorization: Bearer pina_ABCD1234...' \
  --header 'content-type: application/json' \
  --data '{
  "name": "My seed audience",
  "audience_type": "VISITOR",
  "rule": {
    "visitor_source_id": "9876543210321",
    "ingestion_source": {
      "=": [
        "conversions_api"
      ]
    },
    "or": [
      {
        "event": "viewcategory",
        "value": {
          ">": 1
        }
      }
    ],
    "advertiser_id": "120123456789"
  },
  "created_by_company_name": "Example, Inc."
}'

Example request for a seed audience based on a customer list

See for a customer list audience, which is structurally identical.

Response fields to keep in mind

Create customer list audience response fields
Field	Description
`id`	Seed audience ID that you will pass when making the request to define the audience based on the seed audience in the next step.

Example response for seed audience based on events


{
  "ad_account_id": "549768257474",
  "id": "2542623192081",
  "name": "string",
  "audience_type": "VISITOR",
  "description": null,
  "rule": {
    "ingestion_source": {
      "=": ["conversions_api"]
    },
    "visitor_source_id": "2613484614072",
    "or": [
      {
        "event": "viewcategory",
        "value": {
          ">": 1
        }
      }
    ],
    "advertiser_id": "120123456789"
  },
  "size": 0,
  "status": "INITIALIZING",
  "type": "audience",
  "created_timestamp": 1757468980,
  "updated_timestamp": 1757468980,
  "created_by_company_name": null
}
}'

Step 2: Create an actalike audience based on the seed audience

POST

Create audience

Any parameters and code examples that appear in this section support this use case, but may not represent the full endpoint specification. See the endpoint reference page for the comprehensive spec.

Request parameters to keep in mind

Create customer list audience parameters
Parameter	Description
`rule` object (required)	Core part of the request that defines the logic and source data for building the audience.
`rule.seed_id` string	`id` value that was returned when you created the seed audience in the preceding step.
`rule.visitor_source_id` string	Only for seed audience based on site events. Pinterest tag ID, that you use on your website for capturing events. You can pull the tag ID from the Conversions > Pinterest Tag > Tag of your Ads Manager.

Example request


curl --request POST \
  --url https://api.pinterest.com/v5/ad_accounts/120123456789/audiences \
  --header 'authorization: Bearer pina_ABCD1234...' \
  --header 'content-type: application/json' \
  --data '{
  "name": "My actalike audience",
  "audience_type": "ACTALIKE",
  "rule": {
    "seed_id": [
      "626755481648"
    ],
    "country": "US",
    "percentage": 10
  }
}'

Response fields to keep in mind

Create customer list audience response fields
Field	Description
`id`	ID of the audience you created, which you will reference with the `AUDIENCE_INCLUDE` parameter when setting up the targeting spec.

Example response


{
  "ad_account_id": "120123456789",
  "id": "626755481649",
  "name": "My actalike audience",
  "audience_type": "ACTALIKE",
  "description": null,
  "rule": {
    "country": "US",
    "percentage": 10,
    "seed_id": ["2542623189817"]
  },
  "size": 0,
  "status": "INITIALIZING",
  "type": "audience",
  "created_timestamp": 1757111104,
  "updated_timestamp": 1757111104,
  "created_by_company_name": null
}

Engagement audience

Pinners who have interacted with your Pinterest content with clicks, saves, closeups, or comments, make up an engagement audience. When creating this type of audience, you define the engagements that you want to qualify them with.

Step 1: Define your engagement criteria

POST

Create audience

Any parameters and code examples that appear in this section support this use case, but may not represent the full endpoint specification. See the endpoint reference page for the comprehensive spec.

Request parameters to keep in mind

Create engagement audience parameters
Parameter	Description
`rule` object (required)	Core part of the request that defines the logic and source data for building the audience.
`rule.engagement_type` string	Select Pinterest user action(s) to qualify them for the audience you are creating: `click` `save` `closeup` `comment` `like`
`rule.lookback_window` string	Number of preceding days to include for engagement actions.
`audience_type` string	Pass `ENGAGEMENT` .

Example request


curl --request POST \
  --url https://api.pinterest.com/v5/ad_accounts/120123456789/audiences \
  --header 'authorization: Bearer pina_ABCD1234...' \
  --header 'content-type: application/json' \
  --data '{
  "name": "Pin Clickers - Last 30 Days",
  "audience_type": "ENGAGEMENT",
  "rule": {
    "engagement_type": "CLICK",
    "lookback_window": 30
  },
  "description": "People who clicked my Pins in the last 30 days"
}'

Response fields to keep in mind

Create customer list audience response fields
Field	Description
`id`	ID of the audience you created, which you will reference with the `AUDIENCE_INCLUDE` parameter when setting up the targeting spec.

Example response


{
  "ad_account_id": "120123456789",
  "id": "2542623190796",
  "name": "Pin Clickers - Last 30 Days",
  "audience_type": "ENGAGEMENT",
  "description": "People who clicked my Pins in the last 30 days",
  "rule": {
    "lookback_window": 30,
    "engagement_type": "CLICK"
  },
  "size": 0,
  "status": "INITIALIZING",
  "type": "audience",
  "created_timestamp": 1757350318,
  "updated_timestamp": 1757350318,
  "created_by_company_name": null
}

Open audience

Unlike an engagement audience, an open one simply includes the broadest collection of Pinners, with no "type".

To target an open audience, omit the

AUDIENCE_INCLUDE

parameter from your ad group targeting spec. When defining the ad group, you can still insert different targeting criteria in the ad group, such as location, age, or gender, or leave it open for maximum reach.

Persona audience

The Pinterest sales team can create a special audience that includes people who are not easily targeted by interest or with keywords.

You cannot create a persona audience in the API.

Site visitor audience

You can re-target past visitors to your site using Pinterest Tag, and pulling visitor data based on one or more events, such as page visits, signups, and checkouts.

Before you begin

Set up the Pinterest Tag on your website.

Step 1: Define events when creating your audience

POST

Create audience

Any parameters and code examples that appear in this section support this use case, but may not represent the full endpoint specification. See the endpoint reference page for the comprehensive spec.

Site visitor audience request parameters
Parameter	Description
`audience_tye` string (required)	Pass `VISITOR` .
`rule` object (required)	Core part of the request that defines the logic and source data for building the audience.
`rule.visitor_source_id` string	Pinterest tag ID, that you use on your website for capturing events. You can pull the tag ID from the Conversions > Pinterest Tag > Tag manager section of your Ads Manager. If you do not have a Pinterest Tag, you can create one there.
`rule.visitor_source` string	The platform or location where the event occurs. You may want to target audiences based on where they engage with your content or products: `web` `mobile` `offline` To specify multiple sources, use the `in` operator as in the following request example. To specify only one source, use the `=` filter operator as in this example: `"=": ["web", "mobile"]`
`rule.ingestion_source` string	Where the event data comes from. You may want to target audiences differently based on sources: `tag` `mmp` `file_upload` `conversions_api` To specify multiple sources, use the `in` operator as in this example: `"in": ["tag", "api"]` . To specify only one source, use the `=` filter operator as in the following request example.

Request example


curl --request POST \
  --url https://api.pinterest.com/v5/ad_accounts/120123456789/audiences \
  --header 'authorization: Bearer pina_ABCD1234...' \
  --header 'content-type: application/json' \
  --data '{
  "name": "Site Visitors - Last 30 Days",
  "audience_type": "VISITOR",
  "rule": {
    "event_type": "PAGE_VISIT",
    "lookback_window": 30,
    "visitor_source_id": "9876543210321",
    "event_source": {
      "=": [
        "web",
        "mobile"
      ]
    },
    "ingestion_source": {
      "=": [
        "tag"
      ]
    }
  },
  "description": "People who visited my website in the last 30 days"
}'

Response fields

Create site visitor response fields
Field	Description
`id`	ID of the audience you created, which you will reference with the `AUDIENCE_INCLUDE` parameter when setting up the targeting spec.

Example response


{
  "ad_account_id": "120123456789",
  "id": "2542623191976",
  "name": "Site Visitors - Last 30 Days",
  "audience_type": "VISITOR",
  "description": "People who visited my website in the last 30 days",
  "rule": {
    "event_source": {
      "=": ["web", "mobile"]
    },
    "ingestion_source": {
      "=": ["tag"]
    },
    "visitor_source_id": "9876543210321",
    "event_type": "PAGE_VISIT",
    "lookback_window": 30
  },
  "size": 0,
  "status": "INITIALIZING",
  "type": "audience",
  "created_timestamp": 1757449673,
  "updated_timestamp": 1757449673,
  "created_by_company_name": null
}

Check your audience status

Audiences are typically ready in 48 hours, but may occasionally take up to 72 hours.

Check the status of an audience anytime to know when you can start targeting it.

You also can call this endpoint to review any properites for the audience.

GET

Get audience

Any parameters and code examples that appear in this section support this use case, but may not represent the full endpoint specification. See the endpoint reference page for the comprehensive spec.

Request parameters to keep in mind

Get audience parameters
Parameter	Description
`audience_id` string (required)	`id` value that was returned when you created the audience.

Example request


curl --request GET \
  --url https://api.pinterest.com/v5/ad_accounts/120123456789/audiences/2542623190988 \
  --header 'authorization: Bearer pina_ABCD1234'

Response fields to keep in mind

Get audience response fields
Field	Description
`status`	See descriptions for different types of status values.

Example response


{
  "type": "audience",
  "id": "2542623190988",
  "name": "Pin Clickers - Last 30 Days",
  "ad_account_id": "12013456789",
  "audience_type": "ENGAGEMENT",
  "description": "People who clicked my Pins in the last 30 days",
  "status": "TOO_SMALL",
  "size": 0,
  "updated_timestamp": 1757366621,
  "created_timestamp": 1757366621,
  "rule": {
    "lookback_window": 30,
    "engagement_type": "CLICK,SAVE"
  },
  "created_by_company_name": "Example, Inc."
}

Was this page helpful?