{
"opencollection": "1.0.0",
"info": {
"name": "Pinterest Ads API",
"version": "5.13.0"
},
"items": [
{
"info": {
"name": "Ads",
"type": "folder"
},
"items": [
{
"info": {
"name": "Create ad preview with pin or image",
"type": "http"
},
"http": {
"method": "POST",
"url": "https://api.pinterest.com/v5/ad_accounts/:ad_account_id/ad_previews",
"params": [
{
"name": "ad_account_id",
"value": "",
"type": "path",
"description": "Unique identifier of an ad account."
}
],
"body": {
"type": "json",
"data": "{}"
},
"auth": {
"type": "oauth2",
"flow": "authorization_code",
"authorizationUrl": "https://www.pinterest.com/oauth/",
"accessTokenUrl": "https://api.pinterest.com/v5/oauth/token",
"credentials": {
"clientId": "{{clientId}}",
"clientSecret": "{{clientSecret}}"
}
}
},
"docs": "Create an ad preview given an ad account ID and either an existing organic pin ID or the URL for an image to be used to create the Pin and the ad. \nIf you are creating a preview from an existing Pin, that Pin must be promotable: that is, it must have a clickthrough link and meet other requirements. (See Ads Overview.) \nYou can view the returned preview URL on a webpage or iframe for 7 days"
},
{
"info": {
"name": "List ads",
"type": "http"
},
"http": {
"method": "GET",
"url": "https://api.pinterest.com/v5/ad_accounts/:ad_account_id/ads",
"params": [
{
"name": "ad_account_id",
"value": "",
"type": "path",
"description": "Unique identifier of an ad account."
},
{
"name": "campaign_ids",
"value": "",
"type": "query",
"description": "List of Campaign Ids to use to filter the results."
},
{
"name": "ad_group_ids",
"value": "",
"type": "query",
"description": "List of Ad group Ids to use to filter the results."
},
{
"name": "ad_ids",
"value": "",
"type": "query",
"description": "List of Ad Ids to use to filter the results."
},
{
"name": "entity_statuses",
"value": "",
"type": "query",
"description": "Entity status"
},
{
"name": "page_size",
"value": "",
"type": "query",
"description": "Maximum number of items to include in a single page of the response. See documentation on Pagination for more information."
},
{
"name": "order",
"value": "",
"type": "query",
"description": "The order in which to sort the items returned: ASCENDING or DESCENDING\nby ID. Note that higher-value IDs are associated with more-recently added\nitems."
},
{
"name": "bookmark",
"value": "",
"type": "query",
"description": "Cursor used to fetch the next page of items"
}
],
"auth": {
"type": "oauth2",
"flow": "authorization_code",
"authorizationUrl": "https://www.pinterest.com/oauth/",
"accessTokenUrl": "https://api.pinterest.com/v5/oauth/token",
"credentials": {
"clientId": "{{clientId}}",
"clientSecret": "{{clientSecret}}"
}
}
},
"docs": "List ads that meet the filters provided:\n - Listed campaign ids or ad group ids or ad ids\n - Listed entity statuses \nIf no filter is provided, all ads in the ad account are returned. \nNote:\nProvide only campaign_id or ad_group_id or ad_id. Do not provide more than one type. \nReview status is provided for each ad; if review_status is REJECTED, the rejected_reasons field will contain additional information.\nFor more, see For example, if the advertiser's currency is GBP (British pound sterling), all MICRO_DOLLARS fields will be in GBP microunits (1/1,000,000 British pound).
If a column has no value, it may not be returned"
},
{
"name": "granularity",
"value": "DAY",
"type": "query",
"description": "TOTAL - metrics are aggregated over the specified date range.
DAY - metrics are broken down daily.
HOUR - metrics are broken down hourly.
WEEKLY - metrics are broken down weekly.
MONTHLY - metrics are broken down monthly"
},
{
"name": "click_window_days",
"value": "1",
"type": "query",
"description": "Number of days to use as the conversion attribution window for a pin click action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `30` days."
},
{
"name": "engagement_window_days",
"value": "",
"type": "query",
"description": "Number of days to use as the conversion attribution window for an engagement action. Engagements include saves, closeups, link clicks, and carousel card swipes. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `30` days."
},
{
"name": "view_window_days",
"value": "",
"type": "query",
"description": "Number of days to use as the conversion attribution window for a view action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `1` day."
},
{
"name": "conversion_report_time",
"value": "TIME_OF_AD_ACTION",
"type": "query",
"description": "The date by which the conversion metrics returned from this endpoint will be reported. There are two dates associated with a conversion event: the date that the user interacted with the ad, and the date that the user completed a conversion event."
}
],
"auth": {
"type": "oauth2",
"flow": "authorization_code",
"authorizationUrl": "https://www.pinterest.com/oauth/",
"accessTokenUrl": "https://api.pinterest.com/v5/oauth/token",
"credentials": {
"clientId": "{{clientId}}",
"clientSecret": "{{clientSecret}}"
}
}
},
"docs": "Get analytics for the specified ads in the specified ad_account_id, filtered by the specified options.\n- The token's user_account must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via Business Access: Admin, Analyst, Campaign Manager.\n- If granularity is not HOUR, the furthest back you can are allowed to pull data is 90 days "
},
{
"info": {
"name": "Get ads credit discounts",
"type": "http"
},
"http": {
"method": "GET",
"url": "https://api.pinterest.com/v5/ad_accounts/:ad_account_id/ads_credit/discounts",
"params": [
{
"name": "ad_account_id",
"value": "",
"type": "path",
"description": "Unique identifier of an ad account."
},
{
"name": "bookmark",
"value": "",
"type": "query",
"description": "Cursor used to fetch the next page of items"
},
{
"name": "page_size",
"value": "",
"type": "query",
"description": "Maximum number of items to include in a single page of the response. See documentation on Pagination for more information."
}
],
"auth": {
"type": "oauth2",
"flow": "authorization_code",
"authorizationUrl": "https://www.pinterest.com/oauth/",
"accessTokenUrl": "https://api.pinterest.com/v5/oauth/token",
"credentials": {
"clientId": "{{clientId}}",
"clientSecret": "{{clientSecret}}"
}
}
},
"docs": "Returns the list of discounts applied to the account.\n\nThis endpoint might not be available to all apps. Learn more."
},
{
"info": {
"name": "Redeem ad credits",
"type": "http"
},
"http": {
"method": "POST",
"url": "https://api.pinterest.com/v5/ad_accounts/:ad_account_id/ads_credit/redeem",
"params": [
{
"name": "ad_account_id",
"value": "",
"type": "path",
"description": "Unique identifier of an ad account."
}
],
"body": {
"type": "json",
"data": "{}"
},
"auth": {
"type": "oauth2",
"flow": "authorization_code",
"authorizationUrl": "https://www.pinterest.com/oauth/",
"accessTokenUrl": "https://api.pinterest.com/v5/oauth/token",
"credentials": {
"clientId": "{{clientId}}",
"clientSecret": "{{clientSecret}}"
}
}
},
"docs": "Redeem ads credit on behalf of the ad account id and apply it towards billing.\n\nThis endpoint might not be available to all apps. Learn more."
},
{
"info": {
"name": "Get targeting analytics for ads",
"type": "http"
},
"http": {
"method": "GET",
"url": "https://api.pinterest.com/v5/ad_accounts/:ad_account_id/ads/targeting_analytics",
"params": [
{
"name": "ad_account_id",
"value": "",
"type": "path",
"description": "Unique identifier of an ad account."
},
{
"name": "ad_ids",
"value": "",
"type": "query",
"description": "List of Ad Ids to use to filter the results."
},
{
"name": "start_date",
"value": "",
"type": "query",
"description": "Metric report start date (UTC). Format: YYYY-MM-DD. Cannot be more than 90 days back from today."
},
{
"name": "end_date",
"value": "",
"type": "query",
"description": "Metric report end date (UTC). Format: YYYY-MM-DD. Cannot be more than 90 days past start_date."
},
{
"name": "targeting_types",
"value": "",
"type": "query",
"description": "Targeting type breakdowns for the report. The reporting per targeting type
is independent from each other. [\"AGE_BUCKET_AND_GENDER\"] is in BETA and not yet available to all users."
},
{
"name": "columns",
"value": "",
"type": "query",
"description": "Columns to retrieve, encoded as a comma-separated string. **NOTE**: Any metrics defined as MICRO_DOLLARS returns a value based on the advertiser profile's currency field. For USD,($1/1,000,000, or $0.000001 - one one-ten-thousandth of a cent). it's microdollars. Otherwise, it's in microunits of the advertiser's currency.
For example, if the advertiser's currency is GBP (British pound sterling), all MICRO_DOLLARS fields will be in GBP microunits (1/1,000,000 British pound).
If a column has no value, it may not be returned"
},
{
"name": "granularity",
"value": "DAY",
"type": "query",
"description": "TOTAL - metrics are aggregated over the specified date range.
DAY - metrics are broken down daily.
HOUR - metrics are broken down hourly.
WEEKLY - metrics are broken down weekly.
MONTHLY - metrics are broken down monthly"
},
{
"name": "click_window_days",
"value": "1",
"type": "query",
"description": "Number of days to use as the conversion attribution window for a pin click action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `30` days."
},
{
"name": "engagement_window_days",
"value": "",
"type": "query",
"description": "Number of days to use as the conversion attribution window for an engagement action. Engagements include saves, closeups, link clicks, and carousel card swipes. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `30` days."
},
{
"name": "view_window_days",
"value": "",
"type": "query",
"description": "Number of days to use as the conversion attribution window for a view action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `1` day."
},
{
"name": "conversion_report_time",
"value": "TIME_OF_AD_ACTION",
"type": "query",
"description": "The date by which the conversion metrics returned from this endpoint will be reported. There are two dates associated with a conversion event: the date that the user interacted with the ad, and the date that the user completed a conversion event."
},
{
"name": "attribution_types",
"value": "",
"type": "query",
"description": "List of types of attribution for the conversion report"
}
],
"auth": {
"type": "oauth2",
"flow": "authorization_code",
"authorizationUrl": "https://www.pinterest.com/oauth/",
"accessTokenUrl": "https://api.pinterest.com/v5/oauth/token",
"credentials": {
"clientId": "{{clientId}}",
"clientSecret": "{{clientSecret}}"
}
}
},
"docs": "Get targeting analytics for one or more ads. For the requested ad(s) and metrics,\nthe response will include the requested metric information (e.g. SPEND_IN_DOLLAR) for the requested target type\n(e.g. \"age_bucket\") for applicable values (e.g. \"45-49\"). \n- The token's user_account must either be the Owner of the specified ad account, or have one\nof the necessary roles granted to them via\nBusine"
},
{
"info": {
"name": "Get ad",
"type": "http"
},
"http": {
"method": "GET",
"url": "https://api.pinterest.com/v5/ad_accounts/:ad_account_id/ads/:ad_id",
"params": [
{
"name": "ad_account_id",
"value": "",
"type": "path",
"description": "Unique identifier of an ad account."
},
{
"name": "ad_id",
"value": "",
"type": "path",
"description": "Unique identifier of an ad."
}
],
"auth": {
"type": "oauth2",
"flow": "authorization_code",
"authorizationUrl": "https://www.pinterest.com/oauth/",
"accessTokenUrl": "https://api.pinterest.com/v5/oauth/token",
"credentials": {
"clientId": "{{clientId}}",
"clientSecret": "{{clientSecret}}"
}
}
},
"docs": "Get a specific ad given the ad ID. If your pin is rejected, rejected_reasons will\ncontain additional information from the Ad Review process.\nFor more information about our policies and rejection reasons see the Pinterest advertising standards."
}
]
}
],
"bundled": true
}