Pinterest Ad Analytics Report

Pinterest Ad Analytics Report API

Before You Begin

In order to access the Pinterest API, you must first create and register an application with Pinterest, which will result in the ability to make API calls. Please see the directions outlined here to accomplish this.

Configuration Parameters

Any instance where an entry in the below configuration has a leading $ represents a parameter that needs to be replaced with a static value.

Parameters in this document:

$app_id and $app_secret - The App ID and App Secret will be used to authenticate calls to the Pinterest API. These values are provided upon completion of the application creation and registration.
$ad_account_id - The unique identifier for your ad account, which can be found by following these steps:
- Log in to your Pinterest Ads Manager.
- In the upper-lefthand corner of the page, click on the Pinterest button to open the menu.
- Under the Ads section, click on the Ad Account Overview option.
- In the upper-righthand corner of the page, click on your account name to open a dropdown menu.
- With the dropdown menu opened, locate the ID, which will be a 12-digit number that starts with 549. This is your Ad Account ID, and will be used for this parameter value.
$start_date - The Start Date of the data that you would like to receive, given in yyyy-mm-DD format.
$end_date - The End Date of the data that you would like to receive, given in yyyy-mm-DD format.
$columns - The metric and entity columns that you would like to include in the report, which will be given as an array list (e.g. ["AD_ID","PAID_IMPRESSION","SPEND_IN_DOLLAR"]. For a full list of available column values, see the list here under the Request Body > columns section.
$level - The data level for the report, such as CAMPAIGN or PRODUCT_GROUP. For a full list of available level values, see the list here under the Request Body > level section.
$granularity - The date granularity for the report, such as TOTAL or Day. For a full list of available granularity values, see the list here under the Request Body > granularity section.

Connector configuration

Base url: {url}
Method: GET

Destination Table naming convention is ultimately up to you as the data owner. One common structure used for this API is pinterest_ads_analytics_report. If you are creating multiple connectors for different columns, levels, and/or granularities, adjusting the name to better describe the report structure would be recommended, such as pinterest_ads_campaign_costs_by_day.

Authorization

Authorization: OAuth2
Authorization URL: https://www.pinterest.com/oauth/
Access Token URL: https://api.pinterest.com/v5/oauth/token
Client Id: {app_id}
Client Secret: {app_secret}
Scope: ads:read
Access Token header key: Authorization
Token prefix: Bearer
Add to: Headers

Refresh access token

Enable:
Use refresh token once:
URL: https://api.pinterest.com/v5/oauth/token
Method: POST
POST data: {"grant_type":"refresh_token","scope":"ads:read"}
Headers: {"Content-Type":"application/x-www-form-urlencoded","Authorization":"{basic_auth}"}
Access token response key: access_token
Refresh token response key: refresh_token
Use Bearer authentication:
Error status codes: 401; 403

Variables

Variables

Variable name	Variable value
start_date	$start_date
end_date	$end_date
columns	$columns
level	$level
granularity	$granularity

Secured Variables:

Variable name	Variable value
app_id	$app_id
app_secret	$app_secret

Async API

Enable:

Async Trigger

URL: https://api.pinterest.com/v5/ad_accounts/$ad_account_id/reports
Method: POST
POST data: Raw JSON
JSON:

{
    "start_date": "{start_date}",
    "end_date": "{end_date}",
    "granularity": "{granularity}",
    "level":"{level}",
    "columns": {columns},
    "report_format": "CSV"
}

Additional JSON Entries

In addition to the above values (start_date, end_date, etc.), additional parameters can be provided as part of the JSON body to further specify the API call and impact the response that is ultimately ingested into Panoply. For a full list of these additional parameters, see here. Additionally for an example of how these values are to be input within the JSON structure above, see the Request Sample that can be found on the righthand side of the Create async request for an account analytics report.

Headers: {"Content-Type":"application/json"}
Async identifier: token

Async status check

URL: https://api.pinterest.com/v5/ad_accounts/$ad_account_id/reports
Method: GET
URL Parameters: token={token}
Headers: {"Content-Type":"application/json"}
Repeat Frequency: 5
Maximum iterations: 100
Completion key: report_status
Completion value: FINISHED
Result identifier: url

Advanced Settings

Disable configuration validation:
Downloadable link:
Files Encoding: UTF-8

Primary Key

The Primary Key should be a combination of {date}, the $level value, and the columns selected that are entities (CAMPAIGN_ID,AD_GROUP_ID, AD_ID, etc.). Do not include columns that are metrics (CTR, PAID_IMPRESSION, SPEND_IN_DOLLAR, etc.)

As an example, if the report being ingested is with a $level of AD_GROUP and $columns of ["CAMPAIGN_ID","AD_GROUP_ID","PAID_IMPRESSION","SPEND_IN_DOLLAR"], then the Primary Key definition would be {date}-{ad_group}-{campaign_id}-{ad_group_id}