Create campaigns and ad groups

Once you've set up business access and at least one ad account, creating a campaign is the next step to creating an ad. This document will show you how to manage campaigns through the API.

Before getting started

Running ads on Pinterest requires setting up a business account and an ad account within that business account. For first time advertisers we recommend using the UI to set up your first ad account.
Review our Pinterest entities guide to understand the relationship between campaigns, ad groups, and ads.

Create a campaign

POST

Create campaigns

make sure you have your

ad_account_id

. Note that you have the ability to create campaigns in bulk by providing an array of campaign objects.

Set a campaign objective

The objective is the action that you want the user to take after seeing an ad in the campaign. It influences which features of the campaign are optimized and which bid types are available.

As the following table shows, certain objectives designate campaigns as having Campaign Budget Optimization (CBO). This means that you must set budgets at the level of the campaign, not the child ad groups.


Campaign objective	Description	CBO?
Awareness	Help people discover your brand, products or other services.	Yes
Consideration	Help increase the number of Pin clicks or outbound clicks on your ad.	Yes
Web conversion	Drive people to take actions like checkout, sign up, or add to cart on your website.	Yes
Catalog sales	Help people discover your products or services while searching Pinterest for inspiration.	Yes
Video completion	Optimize for users to view your video to completion.
Web sessions	Deprecated.	N/A

Learn more about campaign objectives.

Campaign Budgets

Campaign budgets are designed to optimize spending across ad groups to achieve the best results. The main types of budgets include:

Lifetime: Set a total budget for flexible spending based on optimal daily opportunities.
Daily- Average Daily: Set a flexible daily spend based on optimal spending opportunities
Fixed Daily: Set a consistent amount to spend each day.


Budget Type	Parameter Settings	Description
Lifetime	`lifetime_spend_cap`	Set a total budget for flexible spending based on optimal daily opportunities.
Pinterest Performance+ budget (Also known as "Average Daily")	`daily_spend_cap` and `is_flexible_daily_budgets` is set to `true`	Set a flexible daily spend based on optimal spending opportunities.
Fixed Daily	`daily_spend_cap` and `is_flexible_daily_budgets` is set to `false`	Set a consistent amount to spend each day.

Please note that you cannot set both

lifetime_spend_cap

and

daily_spend_cap

simultaneously.

Set a campaign schedule (optional)

You can schedule when a campaign starts and stops using the

start_time

and

end_time parameters

. Otherwise, the campaign starts immediately and runs indefinitely, unless you call

PATCH

Update campaigns

and set the

status

parameter to

paused

With CBO campaigns, you can only schedule start and end times at the campaign level; however, certain organizations can also schedule start and end times at the ad group level for CBO campaigns

Closed beta

Campaign- and ad-group level scheduling

Ads scheduled at the ad group level cannot occur outside the time windows of parent campaign-level schedules.

If your campaign and any child ad groups have start and end times specified, and if you call

PATCH

Update campaigns

to update that campaign with a start time that is later than that of the ad groups or an end time that is earlier than that of the ad groups, the campaign schedule will supersede that of the ad group, and the request will not return an error.

In that scenario, if you call
GET
List campaigns
or
GET
List ad groups
, the returned campaigns or ad groups are listed with the start and end times that you assigned them, regardless of supersedence.

Campaign Status

Specify the status of the campaign using the

status

field.


Status Type	Description
ACTIVE	Campaign is active and accruing costs.
PAUSED	Campaign is paused, not accruing costs. You are unable to edit certain fields such as `objective_type` for campaigns, the budget_type and billable_event for ad groups and creative_type for ads and product group promotions. To allow these fields to be editable in draft form, use the DRAFT status type.
DRAFT	Campaign is not active and all fields are editable. Can incrementally build and save multiple draft campaigns until they're ready to be published. Different users can also collaborate together on the same draft as long as they have the appropriate Business Access.
DELETED_DRAFT	Draft is permanently deleted.
ARCHIVE	Campaign is deleted. Reach out to customer ops agent and file a ticket to reverse.

For more info on pausing campaigns, please see this help center article.

For more info on draft campaigns, please see this help center article.

Note on is_automated_campaign

is_automated_campaign

indicates that the campaign was created through the automated campaign creation flow on Ads Manager. It is primarily useful as info about a campaign, and not relevant for creating campaigns via the API.

Modifying and Viewing Campaigns

All endpoints for creating and managing campaigns are:

Note that certain fields are not editable when a campaign is PAUSED. See table above for more info.

Label a campaign

Closed beta

Use labels to help you organize your ad campaigns and analyze their performance more efficiently.

After creating a campaign, you can categorize it with a label.

Currently, you can label campaigns by associated brands. In the future we will offer more categorization options.

Step 1: Create a label

POST

Create labels

Parameters to keep in mind

See the endpoint for a full list of parameters.

Campaign labeling request
Parameter	Description
`account_id` string Required	Unique identifier of the account that is labeling the asset. Find your account ID.
`labels.value` string Required	Label name. 100-character limit.
`labels.label_type` string Required	Category for the labeled items: `BRAND` can be used for brand-awareness or brand-building campaigns. You can apply one brand label to a campaign. `CUSTOM` can be used for defining any kind of segmentation. You can apply up to 30 custom labels to a campaign. You also can use brand and custom labels together for a campaign.

Response fields to keep in mind

For successfully created labels, the endpoint returns the

labels

array, which provides metadata about each label. For unsuccessful attempts, the endpoint returns the

errors

array, which provides error messages in addition to metadata about each label you tried to create.

See the endpoint for a complete list of fields.

Campaign labeling reponse
Field	Description
`errors.labels.error_messages`	Reason that a label could not be applied.
`labels.id`	Unique identifier of the label.
`label_status`	Whether the label is in use ( `ACTIVE` ) or not ( `ARCHIVED` ). When you initially create a label, its status is `ACTIVE` by default. You can change the status by updating the label.

Step 2: Apply a label

You can apply a label to a maximum of 250 campaigns.

POST

Apply label to entity

Parameters to keep in mind

Apply label request
Parameter	Description
`ad_account_id` string Required	Your advertiser account ID, which is associated with the label ID.
`label_id` string Required	Indentifier for the label you created (see response fields) and now want to apply to the campaigns. You can view all labels associated with your account and their IDs.
`entity_id` string Required	The ID of the campaign you want to label. You can submit up to 250 campaigns in a request.

Example request



curl --location --request POST 'https://api.pinterest.com/ad_accounts/123456789/labels/987654321/apply?'\
 --header 'Authorization: Bearer pina_ABCD1234...' \
 --header 'Content-Type: application/json' \
 --data {
     "entity_ids": [
      "0987654321", "0987654322", "0987654323"
     ]
    }

Response fields to keep in mind

Apply label response
Field	Description
`entities_labels` array of objects	Container for all the labels you wanted to apply in the request. Each object is organized by an `entity_id` for each campaign that you passed in the request.
`entities_labels` `status` string	The status of the label in that particular campaign. `ACTIVE` : The label has been applied to the campaign. `ARCHIVED` : The label has not been applied because it was previously archived for that campaign, either in the label update request or in Ads Manager. `NULL` : The label has not been applied, or its status is undefined, possibly due to an error.
`errors` array of objects	Container for errors that prevented any labels from being applied in the request.
`errors.` `messages` array of strings	Explanations for why any errors occurred.

Example response


{
  "results": [
    {
      "entity_id": "0987654321",
      "entity_type": "CAMPAIGN",
      "label_id": "label_abc123",
      "status": "ACTIVE"
    },
    {
      "entity_id": "0987654322",
      "entity_type": "CAMPAIGN",
      "label_id": "label_abc123",
      "status": "ARCHIVED"
    },
    {
      "entity_id": "0987654323",
      "entity_type": "CAMPAIGN",
      "label_id": "label_abc123",
      "status": "NULL"
    }
  ],
  "errors": [
    {
      "data": {
        "entity_id": "0987654323",
        "label_id": "label_abc123",
        "status": "NULL"
      },
      "error_messages": ["The provided campaign ID does not exist or is not accessible."]
    }
  ]
}

Use other label endpoints

Remove label from entities

Create an ad group

All ads must be contained within ad groups.

At the ad group level, you can choose where your ads will show on Pinterest and set the budget, bid, run dates, and targeting for all the ads housed within them. Ad groups let you address the different regions, product lines, and target audiences that may be a part of a single campaign. They also allow you to test the performance of various targeting and objective strategies without creating multiple campaigns. Finally, you can create multiple ads in a single ad group to test which variations in creative work best with your targeted audience.

To create an ad group, call the

POST

Create ad groups

with the following:

Give the ad group a
name
Specify the
campaign_id
of your desired campaign
Choose a
billable_event
type
Specify any other desired parameters

Scheduling ads (optional) at the ad group level

To schedule ads, use the the

start_time

and

end_time parameters

when calling

. You can only set start and end times at the campaign level for ads in CBO campaigns. However, certain organizations can also set start and end times at the ad group level for CBO campaigns

Closed beta

Ads scheduled at the ad group level cannot occur outside the time windows of parent campaign-level schedules.

Three possible scheduling scenarios can occur based on the parent/child relationship of campaigns and ad groups:

If you set start and end times for an ad group but not for the parent campaign, ads run on the ad group schedule.
If you do not set start and end times for an ad group, it inherits the schedule set for the parent campaign.
If you do not set a start or end time for an ad group or its parent campaign, ads run immediately and indefinitely, unless you call update ad groups and set the status parameter to paused.

Potential ad group/campaign scheduling discrepancies

If your campaign and any child ad groups have start and end times specified, and if you call

PATCH

Update ad groups

to update one of those ad groups with a start time that is earlier than that of the campaign or an end time that is later than that of the campaign, the campaign schedule will supersede that of the ad group, and the request will return an error.

In that scenario, if you call
GET
List campaigns
or
GET
List ad groups
, the returned campaigns or ad groups are listed with the start and end times that you assigned them, regardless of supersedence.

Managing ads

Was this page helpful?

Campaign objective

Description

CBO?

Awareness

Help people discover your brand, products or other services.

Yes

Consideration

Help increase the number of Pin clicks or outbound clicks on your ad.

Yes

Web conversion

Drive people to take actions like checkout, sign up, or add to cart on your website.

Yes

Catalog sales

Help people discover your products or services while searching Pinterest for inspiration.

Yes

Video completion

Optimize for users to view your video to completion.

Web sessions

Deprecated.

N/A

Budget Type

Parameter Settings

Description

Lifetime

lifetime_spend_cap

Set a total budget for flexible spending based on optimal daily opportunities.

Pinterest Performance+ budget

(Also known as "Average Daily")

daily_spend_cap

and

is_flexible_daily_budgets

is set to

true

Set a flexible daily spend based on optimal spending opportunities.

Fixed Daily

daily_spend_cap

and

is_flexible_daily_budgets

is set to

false

Set a consistent amount to spend each day.

Status Type

Description

ACTIVE

Campaign is active and accruing costs.

PAUSED

Campaign is paused, not accruing costs. You are unable to edit certain fields such as

objective_type

for campaigns, the budget_type and billable_event for ad groups and creative_type for ads and product group promotions. To allow these fields to be editable in draft form, use the DRAFT status type.

DRAFT

Campaign is not active and all fields are editable. Can incrementally build and save multiple draft campaigns until they're ready to be published. Different users can also collaborate together on the same draft as long as they have the appropriate Business Access.

DELETED_DRAFT

Draft is permanently deleted.