Pinterest Ad API
The Ad API from Pinterest — 63 operation(s) for ad.
Pinterest Ad API is one of 117 APIs that Pinterest publishes on the APIs.io network, described by a machine-readable OpenAPI specification and an AsyncAPI event-driven specification.
Tagged areas include Ad. The published artifact set on APIs.io includes an OpenAPI specification, API documentation, and an AsyncAPI specification.
This API exposes 86 operations across 63 paths, and defines 201 schemas. It is described by OpenAPI 3.2.0, at version 5.13.0.
Requests are made against a single base URL, https://api.pinterest.com/v5.
86 operations
63 paths
201 schemas
2 DELETE51 GET9 PATCH24 POST
Metadata
The identity and technical contract details declared by the specification.
Authentication & Security 3
Pinterest Ad API declares
3 security schemes
for authenticating requests.
It supports OAuth 2.0 (pinterest_oauth2) using the authorizationCode flow, exposing 18 scopes.
It accepts HTTP bearer tokens (conversion_token).
It accepts HTTP basic authentication (basic).
conversion_token— This security scheme only applies to the conversion events endpoint (POST /adaccounts/{adaccountid}/events). This endpoint requires a bearer token generated vi…
Paths & Operations 86
Across 63 paths, the API surfaces 86 operations — 2 DELETE, 51 GET, 9 PATCH, 24 POST. Each is listed below with its method, path, parameters, and response codes.
Ad 86
GET
/ad_accounts
List ad accounts
POST
/ad_accounts
Create ad account
GET
/ad_accounts/{ad_account_id}
Get ad account
GET
/ad_accounts/{ad_account_id}/ad_groups
List ad groups
POST
/ad_accounts/{ad_account_id}/ad_groups
Create ad groups
PATCH
/ad_accounts/{ad_account_id}/ad_groups
Update ad groups
GET
/ad_accounts/{ad_account_id}/ad_groups/analytics
Get ad group analytics
GET
/ad_accounts/{ad_account_id}/ad_groups/targeting_analytics
Get targeting analytics for ad groups
POST
/ad_accounts/{ad_account_id}/ad_groups/audience_sizing
Get audience sizing
GET
/ad_accounts/{ad_account_id}/ad_groups/{ad_group_id}
Get ad group
POST
/ad_accounts/{ad_account_id}/ad_previews
Create ad preview with pin or image
GET
/ad_accounts/{ad_account_id}/ads
List ads
POST
/ad_accounts/{ad_account_id}/ads
Create ads
PATCH
/ad_accounts/{ad_account_id}/ads
Update ads
GET
/ad_accounts/{ad_account_id}/ads/analytics
Get ad analytics
GET
/ad_accounts/{ad_account_id}/ads_credit/discounts
Get ads credit discounts
POST
/ad_accounts/{ad_account_id}/ads_credit/redeem
Redeem ad credits
GET
/ad_accounts/{ad_account_id}/ads/targeting_analytics
Get targeting analytics for ads
GET
/ad_accounts/{ad_account_id}/ads/{ad_id}
Get ad
GET
/ad_accounts/{ad_account_id}/analytics
Get ad account analytics
GET
/ad_accounts/{ad_account_id}/audience_insights
Get audience insights
GET
/ad_accounts/{ad_account_id}/audiences
List audiences
POST
/ad_accounts/{ad_account_id}/audiences
Create audience
GET
/ad_accounts/{ad_account_id}/audiences/{audience_id}
Get audience
PATCH
/ad_accounts/{ad_account_id}/audiences/{audience_id}
Update audience
POST
/ad_accounts/{ad_account_id}/audiences/custom
Create custom audience
POST
/ad_accounts/{ad_account_id}/bid_floor
Get bid floors
GET
/ad_accounts/{ad_account_id}/billing_profiles
Get billing profiles
POST
/ad_accounts/{ad_account_id}/bulk/download
Get advertiser entities in bulk
POST
/ad_accounts/{ad_account_id}/bulk/upsert
Create/update ad entities in bulk
GET
/ad_accounts/{ad_account_id}/bulk/{bulk_request_id}
Download advertiser entities in bulk
GET
/ad_accounts/{ad_account_id}/campaigns
List campaigns
POST
/ad_accounts/{ad_account_id}/campaigns
Create campaigns
PATCH
/ad_accounts/{ad_account_id}/campaigns
Update campaigns
GET
/ad_accounts/{ad_account_id}/campaigns/analytics
Get campaign analytics
GET
/ad_accounts/{ad_account_id}/campaigns/targeting_analytics
Get targeting analytics for campaigns
GET
/ad_accounts/{ad_account_id}/campaigns/{campaign_id}
Get campaign
GET
/ad_accounts/{ad_account_id}/conversion_tags
Get conversion tags
POST
/ad_accounts/{ad_account_id}/conversion_tags
Create conversion tag
GET
/ad_accounts/{ad_account_id}/conversion_tags/ocpm_eligible
Get Ocpm eligible conversion tags
GET
/ad_accounts/{ad_account_id}/conversion_tags/page_visit
Get page visit conversion tags
GET
/ad_accounts/{ad_account_id}/conversion_tags/{conversion_tag_id}
Get conversion tag
POST
/ad_accounts/{ad_account_id}/customer_lists
Create customer lists
GET
/ad_accounts/{ad_account_id}/customer_lists
Get customer lists
GET
/ad_accounts/{ad_account_id}/customer_lists/{customer_list_id}
Get customer list
PATCH
/ad_accounts/{ad_account_id}/customer_lists/{customer_list_id}
Update customer list
POST
/ad_accounts/{ad_account_id}/events
Send conversions
GET
/ad_accounts/{ad_account_id}/insights/audiences
Get audience insights scope and type
GET
/ad_accounts/{ad_account_id}/keywords
Get keywords
POST
/ad_accounts/{ad_account_id}/keywords
Create keywords
PATCH
/ad_accounts/{ad_account_id}/keywords
Update keywords
GET
/ad_accounts/{ad_account_id}/keywords/metrics
Get country's keyword metrics
GET
/ad_accounts/{ad_account_id}/lead_forms
Get lead forms
GET
/ad_accounts/{ad_account_id}/lead_forms/{lead_form_id}
Get lead form by id
POST
/ad_accounts/{ad_account_id}/lead_forms/{lead_form_id}/test
Create lead form test data
POST
/ad_accounts/{ad_account_id}/leads/subscriptions
Create lead ads subscription
GET
/ad_accounts/{ad_account_id}/leads/subscriptions
Get lead ads subscriptions
GET
/ad_accounts/{ad_account_id}/leads/subscriptions/{subscription_id}
Get lead ads subscription
DELETE
/ad_accounts/{ad_account_id}/leads/subscriptions/{subscription_id}
Delete lead ads subscription
GET
/ad_accounts/{ad_account_id}/mmm_reports
Get advertiser Marketing Mix Modeling (MMM) report.
POST
/ad_accounts/{ad_account_id}/mmm_reports
Create a request for a Marketing Mix Modeling (MMM) report
GET
/ad_accounts/{ad_account_id}/order_lines
Get order lines
GET
/ad_accounts/{ad_account_id}/order_lines/{order_line_id}
Get order line
POST
/ad_accounts/{ad_account_id}/product_group_promotions
Create product group promotions
PATCH
/ad_accounts/{ad_account_id}/product_group_promotions
Update product group promotions
GET
/ad_accounts/{ad_account_id}/product_group_promotions
Get product group promotions
GET
/ad_accounts/{ad_account_id}/product_group_promotions/{product_group_promotion_id}
Get a product group promotion by id
GET
/ad_accounts/{ad_account_id}/product_groups/analytics
Get product group analytics
GET
/ad_accounts/{ad_account_id}/product_groups/catalogsdeprecated
Get catalog product groups
GET
/ad_accounts/{ad_account_id}/reports
Get the account analytics report created by the async call
POST
/ad_accounts/{ad_account_id}/reports
Create async request for an account analytics report
DELETE
/ad_accounts/{ad_account_id}/sandbox
Delete ads data for ad account in API Sandbox
GET
/ad_accounts/{ad_account_id}/ssio/accounts
Get Salesforce account details including bill-to information.
POST
/ad_accounts/{ad_account_id}/ssio/insertion_orders
Create insertion order through SSIO.
PATCH
/ad_accounts/{ad_account_id}/ssio/insertion_orders
Edit insertion order through SSIO.
GET
/ad_accounts/{ad_account_id}/ssio/insertion_orders/status
Get insertion order status by ad account id.
GET
/ad_accounts/{ad_account_id}/ssio/insertion_orders/{pin_order_id}/status
Get insertion order status by pin order id.
GET
/ad_accounts/{ad_account_id}/ssio/order_lines
Get Salesforce order lines by ad account id.
GET
/ad_accounts/{ad_account_id}/targeting_analytics
Get targeting analytics for an ad account
GET
/ad_accounts/{ad_account_id}/targeting_templates
List targeting templates
POST
/ad_accounts/{ad_account_id}/targeting_templates
Create targeting templates
PATCH
/ad_accounts/{ad_account_id}/targeting_templates
Update targeting templates
GET
/ad_accounts/{ad_account_id}/templates
List templates
POST
/ad_accounts/{ad_account_id}/templates/{template_id}/reports
Create async request for an analytics report using a template
GET
/ad_accounts/{ad_account_id}/terms_of_service
Get terms of service
GET
/resources/ad_account_countries
Get ad accounts countries
Schemas 201
The contract defines 201 schemas that model the data the API accepts and returns. The most detailed are TemplateResponse (25 properties), SSIOOrderLine (22 properties), AudienceRule (20 properties), AdCommon (19 properties). Each schema is shown below with its type and property counts.
ProductGroupPromotionResponseElement
object
AdsCreditDiscountsResponse
object
7 properties
MatchTypeResponse
stringnull
Keyword match type
CampaignCommon
object
Campaign Data
10 properties
TargetingTemplateUpdateRequest
object
2 properties
2 required
AdArrayResponse
object
1 property
AdsAnalyticsFilterOperator
string
Filter operator for sync reporting
AdAccountCreateSubscriptionResponse
object
4 properties
OptimizationGoalMetadata
object
3 properties
CampaignCreateResponseItem
object
2 properties
Paginated
object
2 properties
1 required
Keyword
object
AdPinId
object
1 property
OrderLines
object
Order Line
11 properties
AdsCreditRedeemResponse
object
3 properties
AudienceCreateRequest
object
AdsAnalyticsFilterColumn
string
Reporting columns for sync reporting data filter
Granularity
string
Granularity
MMMReportingColumn
string
Marketing Mix Modeling (MMM) Reporting Columns
LeadFormTestRequest
object
Request to create test data for lead data test API.
1 property
1 required
TargetingSpec
object
Ad group targeting specification defining the ad group target audience. For example, {"APPTYPE":["iphone"], "GENDER":["male"], "LOCALE":["en-US"], "LOCATION":[…
11 properties
SSIOInsertionOrderCommon
object
12 properties
AdsAnalyticsGetAsyncResponse
object
3 properties
MatchType
string
Keyword match type
KeywordUpdateBody
object
1 property
1 required
ObjectiveType
string
Campaign objective type. If set as one of ["AWARENESS", "CONSIDERATION", "WEBCONVERSION", "CATALOGSALES"] the campaign is considered as a Campaign Budget Optim…
SSIOAccountAddress
object
4 properties
SSIOAccountItem
object
9 properties
AudienceDefinitionResponse
object
1 property
ConversionTagCommon
object
9 properties
BulkUpsertRequestUpdate
object
Request for creation of entities in bulk.
5 properties
ConversionTagsOcpmEligibleResponse
object
ProductGroupPromotionResponseItem
object
2 properties
CustomColumnId
string
Custom Column ID
AdGroupSummaryStatus
string
Summary status for ad group
BulkReportingJobStatus
string
Possible status for a bulk reporting job
BulkUpsertResponse
object
ID of the bulk request.
1 property
CampaignResponse
object
CreateMMMReportRequest
object
7 properties
7 required
PacingDeliveryType
string
Ad group pacing delivery type. With ACCELERATED, an ad group budget is spent as fast as possible. With STANDARD, an ad group budget is spent smoothly over a da…
ActionType
string
Ad group billable event type. For update, only draft ad groups may update billable event.
AdGroupCommon
object
18 properties
ConversionTagResponse
object
ConversionAttributionWindowDays
integer
EnhancedMatchStatusType
stringnull
The enhanced match status of the tag
AdUpdateRequest
object
CreateMMMReportResponse
object
2 properties
KeywordsMetricsArrayResponse
object
1 property
Board
object
Board
11 properties
1 required
ProductGroupPromotionCreateRequest
object
2 properties
2 required
AdAccountAnalyticsResponse
array
MMMReportingTargetingType
string
Ad targeting types for MMM report
TargetingTypeFilter
object
1 property
AdPreviewURLResponse
object
1 property
CampaignIsFlexibleDailyBudgets
boolean
Determine if a campaign has flexible daily budgets setup.
ProductGroupPromotionUpdateRequest
object
2 properties
2 required
AdGroupArrayResponseElement
object
2 properties
SSIOAccountPMPName
object
2 properties
Audience
object
11 properties
AudienceDescription
string
Audience description.
ConversionTagConfigs
object
7 properties
SSIOInsertionOrderStatus
object
3 properties
BulkOutputFormat
string
Bulk file output format
LeadFormStatus
string
Status of the lead form
OrderLineStatus
string
Order Line Status
AudienceUpdateOperationType
string
Audience operation type (update or remove).
CustomerList
object
11 properties
AudienceUpdateRequest
object
PinPromotionSummaryStatus
string
Summary status for pin promotions
DetailedError
object
Used for including extra details to a base error
3 properties
3 required
UserListType
string
User list type
ProductGroupSummaryStatus
string
Summary status for product group
SSIOAccountResponse
object
6 properties
Country
string
Country ID from ISO 3166-1 alpha-2.
BulkUpsertRequestCreate
object
Request for creation of entities in bulk.
5 properties
AdGroupUpdateRequest
object
AudienceRule
object
JSON object defining targeted audience users. Example rule formats per audience type: CUSTOMERLIST: { "customerlistid": "
20 properties
BidFloor
object
2 properties
DataOutputFormat
string
Format of generated report
AdGroupAudienceSizingRequest
object
6 properties
ConversionEvents
object
A list of events (one or more) encapsulated by a data object.
1 property
1 required
TargetingTemplateGetResponseData
object
BudgetType
string
Budget type. If DAILY, an ad group's daily spend will not exceed the budget parameter value. If LIFETIME, the endtime parameter is REQUIRED, and the ad group s…
KeywordsRequest
object
2 properties
2 required
GetMMMReportResponse
object
4 properties
AudienceDemographicValue
object
Demographic detail for a single audience demographic
3 properties
CampaignIsAutomatedCampaign
boolean
Specifies whether the campaign was created in the automated campaign flow
AudienceCommon
object
3 properties
BidFloorRequest
object
2 properties
1 required
BulkUpsertStatusResponse
object
ID of the bulk request.
2 properties
AdCountry
string
Country ID from ISO 3166-1 alpha-2.
AdAccount
object
8 properties
AdPreviewRequest
BusinessAccessRole
string
Permission role for business access.
AdsAnalyticsCreateAsyncResponse
object
3 properties
AdCommon
object
Creation fields
19 properties
SSIOOrderLine
object
22 properties
ProductGroupAnalyticsResponse
array
ConversionTagListResponse
object
1 property
AudienceDefinition
object
Queryable audience representation.
3 properties
TargetingTemplateResponseData
object
TargetingTemplateCreate
object
ConversionTagType
string
conversion tag type
TargetingAdvertiserCountry
stringnull
Advertiser's ISO two character country code.
CampaignUpdateResponse
object
KeywordsCommon
object
3 properties
2 required
ConversionReportAttributionType
string
Attribution type. Refers to the Pinterest Tag endpoints
AdAccountCreateRequest
object
3 properties
AudienceDefinitionScope
string
Generated audience scope to request.
1 property
ConversionEventsUserData
object
Object containing customer information data. Note, It is required at least one of 1) em, 2) hashedmaids or 3) pair clientipaddress + clientuseragent.
12 properties
BillingProfilesResponse
object
5 properties
ConversionEventResponse
object
4 properties
CampaignCreateResponse
object
1 property
UserListOperationType
string
User list operation type (add or remove)
AdAccountsCountryResponse
object
1 property
GridClickType
stringnull
Where a user is taken after clicking on an ad in grid. Note: This parameter is read-only and is set to DIRECTTODESTINATION by default for direct links supporte…
ProductGroupPromotionCreateRequestElement
object
QuizPinOption
objectnull
This field contains multiple options to a quiz question.
2 properties
SSIOInsertionOrderStatusResponse
AdArrayResponseElement
object
2 properties
EntityStatus
string
Entity status
TargetingTemplateAudienceSizing
objectnull
Gets an audience size estimate for a set of given targeting spec data. Returns: An object containing an audience size estimate that has a reach estimate (numbe…
1 property
KeywordUpdate
object
3 properties
1 required
AdCreateRequest
object
OrderLinePaidType
stringnull
Order Line Paid Type
Currency
string
Currency Codes from ISO 4217
ReportingColumnAsync
string
Reporting columns
CampaignCreateResponseData
object
ConversionTagCreate
object
1 property
1 required
TemplateResponse
object
Template fields
25 properties
AdGroupResponse
object
Error
object
2 properties
2 required
AudienceInsightsResponse
object
Audience interests and demographics.
6 properties
PlacementGroupType
string
Campaign placement group type
AudienceCreateCustomRequest
object
AdGroupArrayResponse
object
1 property
AudienceDemographics
object
Audience demographics
5 properties
KeywordMetrics
object
Keyword metrics JSON
2 properties
MetricsReportingLevel
string
Level of the reporting request
BulkUpsertStatus
string
CampaignCreateRequest
object
SSIOCreateInsertionOrderRequest
object
AdsAnalyticsCreateAsyncRequest
object
AdGroupCreateRequest
object
AdAccountGetSubscriptionResponse
object
QuizPinData
objectnull
This field includes all quiz data including questions, options, and results.
2 properties
Exception
object
2 properties
AudienceCategory
object
6 properties
QuizPinResult
objectnull
The result, and link out, based on the users choice.
5 properties
CampaignCreateCommon
object
MetricsResponse
object
1 property
TermsOfService
object
4 properties
BulkUpsertRequest
object
Two set of objects to be managed asyncronusly by bulk. One for creations, one for modifications.
2 properties
AdAccountCreateSubscriptionRequest
object
5 properties
1 required
LeadFormTestResponse
object
Response for lead data test API.
1 property
BulkEntityType
string
Refers ads entity type
LeadFormQuestion
object
4 properties
SSIOEditInsertionOrderRequest
object
ProductGroupPromotion
object
17 properties
AdsAnalyticsResponse
array
AdsAnalyticsTargetingType
string
Reporting targeting type
OrderLine
object
AdResponse
object
AdGroupsAnalyticsResponse
array
AdAccountsCountryResponseData
object
4 properties
ConversionApiResponse
object
Schema describing the object in the response, which contains information about the events that were received and processed.
3 properties
3 required
CampaignsAnalyticsResponse
array
KeywordError
object
2 properties
CampaignSummaryStatus
string
Summary status for campaign
CampaignUpdateRequest
object
TargetingTemplateCommon
object
6 properties
KeywordMetricsResponse
object
2 properties
LeadFormQuestionType
string
Lead form question type
TargetingTemplateKeyword
object
2 properties
BulkDownloadResponse
object
1 property
TrackingUrls
objectnull
Third-party tracking URLs. Up to three tracking URLs - with a max length of 2,000 - are supported for each event type. Tracking URLs set at the ad group or ad…
5 properties
CreativeType
string
Ad creative type enum. For update, only draft ads may update creative type. Note: SHOPTHEPIN has been deprecated. Please use COLLECTION instead.
BulkDownloadRequest
object
Ad entities to get in bulk request.
5 properties
AudienceSharingType
string
Audience sharing type: ["CUSTOM", "SYNDICATED"]
LeadFormQuestionFieldType
stringnull
Lead form question field type
AudienceInsightType
string
SSIOCreateInsertionOrderResponse
object
1 property
AdGroupAudienceSizingResponse
object
2 properties
QuizPinQuestion
objectnull
A specific quiz inquiry.
3 properties
AudienceDefinitionType
string
Generated audience type to request.
1 property
AdsCreditRedeemRequest
object
2 properties
2 required
CustomerListRequest
object
4 properties
2 required
ProductGroupPromotionResponse
object
1 property
SSIOEditInsertionOrderResponse
object
1 property
ConversionReportTimeType
string
Conversion report time type
LeadFormCommon
object
Creation fields
7 properties
CampaignId
object
1 property
AudienceDataParty
string
Whether the data is owned by the partner (1p) or by the data provider (3p)
AudienceType
string
Audience type
KeywordsResponse
object
2 properties
CustomerListUpdateRequest
object
3 properties
2 required
BoardOwner
object
1 property
AdsAnalyticsMetricsFilter
object
3 properties
3 required
CampaignIsCampaignBudgetOptimization
boolean
Determines if a campaign automatically generate ad-group level budgets given a campaign budget to maximize campaign outcome. When transitioning from non-cbo to…
LeadFormResponse
object
CatalogProductGroup
object
non-promoted catalog product group entity
12 properties
Specification
The full machine-readable OpenAPI contract behind this narrative.
Source
More from Pinterest 12
Other APIs Pinterest publishes across the network.
Pinterest Access API
Pinterest Accounts API
Pinterest Ad_groups API
Pinterest Ads API
Pinterest Analytics API
Pinterest Assets API
Pinterest Audience API
Pinterest Audience_insights API
Pinterest Audiences API
Pinterest Batch API
Pinterest Bid API
Pinterest Billing API
#Ad
Where this information came from
This is an independent, third-party profile of Pinterest Ad API, published by API Evangelist. We do not operate, host, resell, or support these APIs, and we are not affiliated with or endorsed by the company unless stated above. Everything here is built from publicly available information — the company's own site, developer portal, documentation, public repositories, and the specifications it publishes for public use. Nothing is obtained by breaching a system, defeating an access control, or using credentials.
The Kin Score and Agent Readiness rating are independently calculated assessments of a company's public API artifacts, scored against a published rubric. They are not certifications, endorsements, security assessments, or audits.
Corrections, re-scores, and removal are free — no partnership or purchase required, and you do not need to justify the request. A removed company is recorded as unrated, never scored zero for having asked. Acknowledgement within one business day; removal within two.
info@apievangelist.com
·
Read the full data-sourcing policy →
On a security or compliance team? Put security in the subject line and
you will get a person, not a form — we will tell you exactly which public URLs this profile was built from.