- Introduction
-
Getting Started
- Creating an Account in Hevo
- Subscribing to Hevo via AWS Marketplace
- Subscribing to Hevo via Snowflake Marketplace
- Connection Options
- Familiarizing with the UI
- Creating your First Pipeline
- Data Loss Prevention and Recovery
- Upgrading Pipeline from Standard to Edge
-
Data Ingestion
- Types of Data Synchronization
- Ingestion Modes and Query Modes for Database Sources
- Ingestion and Loading Frequency
- Data Ingestion Statuses
- Deferred Data Ingestion
- Handling of Primary Keys
- Handling of Updates
- Handling of Deletes
- Hevo-generated Metadata
- Best Practices to Avoid Reaching Source API Rate Limits
-
Edge
- Data Ingestion
- Core Concepts
-
Pipelines
- Familiarizing with the Pipelines UI
- Creating an Edge Pipeline
- Working with Edge Pipelines
- Pipeline Job History
- Pipeline Overview
- Needs Attention
- Object and Schema Management
- Activity Log
-
Sources
- Connect AI
- PostgreSQL
- Oracle
- MySQL
- SQL Server
- Troubleshooting Database Sources
- CockroachDB
- MongoDB
- SharePoint
- Salesforce Bulk API V2
- Ordergroove
- BambooHR
- Stripe
- NetSuite SuiteAnalytics
- Shopify
- Slack
- ClickUp
- Monday.com
- Pipedrive
- Workable
- Fathom
- HubSpot
- Salesforce Marketing Cloud
- Google Analytics 4
- Google Ads
- Facebook Ads
- Microsoft Ads
- LinkedIn Ads
- Xero
- Instagram Business
- Amazon Selling Partner
- TikTok Ads
- StackAdapt
- Amazon Ads
- Pinterest Organic
- Zendesk Support
- Snapchat Ads
- TikTok Organic
- Google Search Console
- Klaviyo v2
- Braintree Payments
- Facebook Pages
- Tempo
- PayPal
- Auth0
- Pinterest Ads
- Apple Search Ads
- Permit.io
- Amplitude Analytics
- Customer.io
- Paddle
- Jira Cloud
- Fullstory
- GitHub
- WorkOS
- ActiveCampaign
- Campaign Monitor
- Infobip
- Mailgun Send
- Metaplane
- Notion
- Recharge
- sevdesk
- Statuspage
- Teamwork.com
- Workday RaaS
- Yotpo
- TikTok Shop Partner Center
- Linear
- Microsoft Dynamics 365 Business Central
- Checkout.com
- Pylon
- Increase
- Microsoft Teams
- Rollbar
- Toggl Track
- QuickBooks Online
- Zoho Desk
- Livestorm
- Attentive
- SendGrid
- Bitly
- Shortcut
- Buzzsprout
- Persona
- Mailjet
- Open Exchange Rates
- PagerDuty
- CircleCI
- SonarQube
- Chargebee
- Freshdesk
- Bing Webmaster Tools
- Rundeck
- Cal.com
- Mixpanel
- Matomo
- Walmart Marketplace
- Xray
- Reddit Ads
- Postmark
- Zoho Recruit
- HiBob
- Freshchat
- Zoho Books
- Marketo
- LaunchDarkly
- Outreach
- Airtable
- Attio
- Okta
- Zendesk Chat
- Bigin by Zoho CRM
- Brevo
- Harvest
- dbt Cloud
- Naming Conventions for Source Data Entities
- Destinations
- Transformations
- Alerts
- Activate
- Custom Connectors
-
Data Loading
- Loading Data in a Database Destination
- Loading Data to a Data Warehouse
- Optimizing Data Loading for a Destination Warehouse
- Deduplicating Data in a Data Warehouse Destination
- Manually Triggering the Loading of Events
- Scheduling Data Load for a Destination
- Loading Events in Batches
- Data Loading Statuses
- Data Spike Alerts
- Name Sanitization
- Table and Column Name Compression
- Parsing Nested JSON Fields in Events
-
Pipelines
- Data Flow in a Pipeline
- Familiarizing with the Pipelines UI
- Working with Pipelines
- Managing Objects in Pipelines
- Pipeline Jobs
-
Transformations
-
Python Code-Based Transformations
- Supported Python Modules and Functions
-
Transformation Methods in the Event Class
- Create an Event
- Retrieve the Event Name
- Rename an Event
- Retrieve the Properties of an Event
- Modify the Properties for an Event
- Fetch the Primary Keys of an Event
- Modify the Primary Keys of an Event
- Fetch the Data Type of a Field
- Check if the Field is a String
- Check if the Field is a Number
- Check if the Field is Boolean
- Check if the Field is a Date
- Check if the Field is a Time Value
- Check if the Field is a Timestamp
-
TimeUtils
- Convert Date String to Required Format
- Convert Date to Required Format
- Convert Datetime String to Required Format
- Convert Epoch Time to a Date
- Convert Epoch Time to a Datetime
- Convert Epoch to Required Format
- Convert Epoch to a Time
- Get Time Difference
- Parse Date String to Date
- Parse Date String to Datetime Format
- Parse Date String to Time
- Utils
- Examples of Python Code-based Transformations
-
Drag and Drop Transformations
- Special Keywords
-
Transformation Blocks and Properties
- Add a Field
- Change Datetime Field Values
- Change Field Values
- Drop Events
- Drop Fields
- Find & Replace
- Flatten JSON
- Format Date to String
- Format Number to String
- Hash Fields
- If-Else
- Mask Fields
- Modify Text Casing
- Parse Date from String
- Parse JSON from String
- Parse Number from String
- Rename Events
- Rename Fields
- Round-off Decimal Fields
- Split Fields
- Examples of Drag and Drop Transformations
- Effect of Transformations on the Destination Table Structure
- Transformation Reference
- Transformation FAQs
-
Python Code-Based Transformations
-
Schema Mapper
- Using Schema Mapper
- Mapping Statuses
- Auto Mapping Event Types
- Manually Mapping Event Types
- Modifying Schema Mapping for Event Types
- Schema Mapper Actions
- Fixing Unmapped Fields
- Resolving Incompatible Schema Mappings
- Resizing String Columns in the Destination
- Changing the Data Type of a Destination Table Column
- Schema Mapper Compatibility Table
- Limits on the Number of Destination Columns
- File Log
- Troubleshooting Failed Events in a Pipeline
- Mismatch in Events Count in Source and Destination
- Audit Tables
- Activity Log
-
Pipeline FAQs
- Can multiple Sources connect to one Destination?
- What happens if I re-create a deleted Pipeline?
- Why is there a delay in my Pipeline?
- Can I change the Destination post-Pipeline creation?
- Why is my billable Events high with Delta Timestamp mode?
- Can I drop multiple Destination tables in a Pipeline at once?
- How does Run Now affect scheduled ingestion frequency?
- Will pausing some objects increase the ingestion speed?
- Can I see the historical load progress?
- Why is my Historical Load Progress still at 0%?
- Why is historical data not getting ingested?
- How do I set a field as a primary key?
- How do I ensure that records are loaded only once?
- Why can't I see my Pipelines after logging in?
- Events Usage
-
Sources
- Free Sources
-
Databases and File Systems
- Data Warehouses
-
Databases
- Connecting to a Local Database
- Amazon DocumentDB
- Amazon DynamoDB
- Elasticsearch
-
MongoDB
- Generic MongoDB
- MongoDB Atlas
- Support for Multiple Data Types for the _id Field
- Example - Merge Collections Feature
-
Troubleshooting MongoDB
-
Errors During Pipeline Creation
- Error 1001 - Incorrect credentials
- Error 1005 - Connection timeout
- Error 1006 - Invalid database hostname
- Error 1007 - SSH connection failed
- Error 1008 - Database unreachable
- Error 1011 - Insufficient access
- Error 1028 - Primary/Master host needed for OpLog
- Error 1029 - Version not supported for Change Streams
- SSL 1009 - SSL Connection Failure
- Troubleshooting MongoDB Change Streams Connection
- Troubleshooting MongoDB OpLog Connection
-
Errors During Pipeline Creation
- SQL Server
-
MySQL
- Amazon Aurora MySQL
- Amazon RDS MySQL
- Azure MySQL
- Generic MySQL
- Google Cloud MySQL
- MariaDB MySQL
-
Troubleshooting MySQL
-
Errors During Pipeline Creation
- Error 1003 - Connection to host failed
- Error 1006 - Connection to host failed
- Error 1007 - SSH connection failed
- Error 1011 - Access denied
- Error 1012 - Replication access denied
- Error 1017 - Connection to host failed
- Error 1026 - Failed to connect to database
- Error 1027 - Unsupported BinLog format
- Failed to determine binlog filename/position
- Schema 'xyz' is not tracked via bin logs
- Errors Post-Pipeline Creation
-
Errors During Pipeline Creation
- MySQL FAQs
- Oracle
-
PostgreSQL
- Amazon Aurora PostgreSQL
- Amazon RDS PostgreSQL
- Azure PostgreSQL
- Generic PostgreSQL
- Google Cloud PostgreSQL
- Heroku PostgreSQL
- Upgrading Pipelines with PostgreSQL Sources to Use the pgoutput Plugin
-
Troubleshooting PostgreSQL
-
Errors during Pipeline creation
- Error 1003 - Authentication failure
- Error 1006 - Connection settings errors
- Error 1011 - Access role issue for logical replication
- Error 1012 - Access role issue for logical replication
- Error 1014 - Database does not exist
- Error 1017 - Connection settings errors
- Error 1023 - No pg_hba.conf entry
- Error 1024 - Number of requested standby connections
- Errors Post-Pipeline Creation
-
Errors during Pipeline creation
-
PostgreSQL FAQs
- Can I track updates to existing records in PostgreSQL?
- How can I migrate a Pipeline created with one PostgreSQL Source variant to another variant?
- How can I prevent data loss when migrating or upgrading my PostgreSQL database?
- Why do FLOAT4 and FLOAT8 values in PostgreSQL show additional decimal places when loaded to BigQuery?
- Why is data not being ingested from PostgreSQL Source objects?
- Troubleshooting Database Sources
- Database Source FAQs
- File Storage
- Engineering Analytics
- Finance & Accounting Analytics
-
Marketing Analytics
- ActiveCampaign
- AdRoll
- Amazon Ads
- Apple Search Ads
- AppsFlyer
- CleverTap
- Criteo
- Drip
- Facebook Ads
- Facebook Page Insights
- Firebase Analytics
- Freshsales
- Google Ads
- Google Analytics 4
- Google Analytics 360
- Google Play Console
- Google Search Console
- HubSpot
- Instagram Business
- Klaviyo v2
- Lemlist
- LinkedIn Ads
- Mailchimp
- Mailshake
- Marketo
- Microsoft Ads
- Onfleet
- Outbrain
- Pardot
- Pinterest Ads
- Pipedrive
- Recharge
- Segment
- SendGrid Webhook
- SendGrid
- Salesforce Marketing Cloud
- Snapchat Ads
- SurveyMonkey
- Taboola
- TikTok Ads
- Twitter Ads
- Typeform
- YouTube Analytics
- Product Analytics
- Sales & Support Analytics
- Source FAQs
-
Destinations
- Familiarizing with the Destinations UI
- Cloud Storage-Based
- Databases
-
Data Warehouses
- Amazon Redshift
- Amazon Redshift Serverless
- Azure Synapse Analytics
- Databricks
-
Google BigQuery
- Clustering in BigQuery
- Partitioning in BigQuery
- Structure of Data in the Google BigQuery Data Warehouse
- Loading Data to a Google BigQuery Data Warehouse
- Near Real-time Data Loading using Streaming
- Modifying BigQuery Destinations to Use Service Account Authentication
- Troubleshooting Google BigQuery
- Google BigQuery FAQs
- Hevo Managed Google BigQuery
- Snowflake
- Troubleshooting Data Warehouse Destinations
-
Destination FAQs
- Can I change the primary key in my Destination table?
- Can I change the Destination table name after creating the Pipeline?
- How can I change or delete the Destination table prefix?
- Why does my Destination have deleted Source records?
- How do I filter deleted Events from the Destination?
- Does a data load regenerate deleted Hevo metadata columns?
- How do I filter out specific fields before loading data?
- Transform
- Alerts
- Account Management
- Activate
- MCP Server
- Glossary
-
Releases-
2026 Releases
- Release 2.53 (August 24 – September 21, 2026)
- Release 2.52 (July 27 – August 24, 2026)
- Release 2.51 (Jun 29 – July 27 , 2026)
- Release 2.50 (Jun 01–29, 2026)
- Release 2.49 (May 04-Jun 01, 2026)
- Release 2.48 (Apr 06-May 04, 2026)
- Release 2.47 (Mar 09-Apr 06, 2026)
- Release 2.46 (Feb 09-Mar 09, 2026)
- Release 2.45 (Jan 12-Feb 09, 2026)
-
2025 Releases
- Release 2.44 (Dec 01, 2025-Jan 12, 2026)
- Release 2.43 (Nov 03-Dec 01, 2025)
- Release 2.42 (Oct 06-Nov 03, 2025)
- Release 2.41 (Sep 08-Oct 06, 2025)
- Release 2.40 (Aug 11-Sep 08, 2025)
- Release 2.39 (Jul 07-Aug 11, 2025)
- Release 2.38 (Jun 09-Jul 07, 2025)
- Release 2.37 (May 12-Jun 09, 2025)
- Release 2.36 (Apr 14-May 12, 2025)
- Release 2.35 (Mar 17-Apr 14, 2025)
- Release 2.34 (Feb 17-Mar 17, 2025)
- Release 2.33 (Jan 20-Feb 17, 2025)
-
2024 Releases
- Release 2.32 (Dec 16 2024-Jan 20, 2025)
- Release 2.31 (Nov 18-Dec 16, 2024)
- Release 2.30 (Oct 21-Nov 18, 2024)
- Release 2.29 (Sep 30-Oct 22, 2024)
- Release 2.28 (Sep 02-30, 2024)
- Release 2.27 (Aug 05-Sep 02, 2024)
- Release 2.26 (Jul 08-Aug 05, 2024)
- Release 2.25 (Jun 10-Jul 08, 2024)
- Release 2.24 (May 06-Jun 10, 2024)
- Release 2.23 (Apr 08-May 06, 2024)
- Release 2.22 (Mar 11-Apr 08, 2024)
- Release 2.21 (Feb 12-Mar 11, 2024)
- Release 2.20 (Jan 15-Feb 12, 2024)
-
2023 Releases
- Release 2.19 (Dec 04, 2023-Jan 15, 2024)
- Release Version 2.18
- Release Version 2.17
- Release Version 2.16 (with breaking changes)
- Release Version 2.15 (with breaking changes)
- Release Version 2.14
- Release Version 2.13
- Release Version 2.12
- Release Version 2.11
- Release Version 2.10
- Release Version 2.09
- Release Version 2.08
- Release Version 2.07
- Release Version 2.06
-
2022 Releases
- Release Version 2.05
- Release Version 2.04
- Release Version 2.03
- Release Version 2.02
- Release Version 2.01
- Release Version 2.00
- Release Version 1.99
- Release Version 1.98
- Release Version 1.97
- Release Version 1.96
- Release Version 1.95
- Release Version 1.93 & 1.94
- Release Version 1.92
- Release Version 1.91
- Release Version 1.90
- Release Version 1.89
- Release Version 1.88
- Release Version 1.87
- Release Version 1.86
- Release Version 1.84 & 1.85
- Release Version 1.83
- Release Version 1.82
- Release Version 1.81
- Release Version 1.80 (Jan-24-2022)
- Release Version 1.79 (Jan-03-2022)
-
2021 Releases
- Release Version 1.78 (Dec-20-2021)
- Release Version 1.77 (Dec-06-2021)
- Release Version 1.76 (Nov-22-2021)
- Release Version 1.75 (Nov-09-2021)
- Release Version 1.74 (Oct-25-2021)
- Release Version 1.73 (Oct-04-2021)
- Release Version 1.72 (Sep-20-2021)
- Release Version 1.71 (Sep-09-2021)
- Release Version 1.70 (Aug-23-2021)
- Release Version 1.69 (Aug-09-2021)
- Release Version 1.68 (Jul-26-2021)
- Release Version 1.67 (Jul-12-2021)
- Release Version 1.66 (Jun-28-2021)
- Release Version 1.65 (Jun-14-2021)
- Release Version 1.64 (Jun-01-2021)
- Release Version 1.63 (May-19-2021)
- Release Version 1.62 (May-05-2021)
- Release Version 1.61 (Apr-20-2021)
- Release Version 1.60 (Apr-06-2021)
- Release Version 1.59 (Mar-23-2021)
- Release Version 1.58 (Mar-09-2021)
- Release Version 1.57 (Feb-22-2021)
- Release Version 1.56 (Feb-09-2021)
- Release Version 1.55 (Jan-25-2021)
- Release Version 1.54 (Jan-12-2021)
-
2020 Releases
- Release Version 1.53 (Dec-22-2020)
- Release Version 1.52 (Dec-03-2020)
- Release Version 1.51 (Nov-10-2020)
- Release Version 1.50 (Oct-19-2020)
- Release Version 1.49 (Sep-28-2020)
- Release Version 1.48 (Sep-01-2020)
- Release Version 1.47 (Aug-06-2020)
- Release Version 1.46 (Jul-21-2020)
- Release Version 1.45 (Jul-02-2020)
- Release Version 1.44 (Jun-11-2020)
- Release Version 1.43 (May-15-2020)
- Release Version 1.42 (Apr-30-2020)
- Release Version 1.41 (Apr-2020)
- Release Version 1.40 (Mar-2020)
- Release Version 1.39 (Feb-2020)
- Release Version 1.38 (Jan-2020)
-
2026 Releases
- Early Access New
Pinterest Ads is Pinterest’s advertising platform that enables businesses to promote their Pins to people who are searching for and saving ideas on Pinterest. It allows advertisers to organize their advertising into ad accounts, campaigns, and ad groups, promote Pins as ads, and measure ad performance through reporting.
Hevo uses the Pinterest REST API to replicate data from your Pinterest Ads account to the Destination of your choice.
Hevo supports the following authentication methods to connect to your Pinterest Ads account:
-
Open Authorization (OAuth): Allows Hevo to connect to your account through an authorization flow, where you sign in to Pinterest and grant Hevo access to your account data.
-
OAuth app: Allows Hevo to connect to your account using the client ID, client secret, and refresh token of an OAuth app that you create in Pinterest.
Note: To create a Pipeline with Pinterest Ads as the Source using an OAuth app, you must use the Create a Pipeline endpoint through the Hevo API. This method is not available in the Hevo UI. Read Creating a Pipeline with Hevo API for the steps to create the Pipeline.
Supported Features
| Feature Name | Supported |
|---|---|
| Capture deletes | No |
| History mode | No |
| Custom data (user-configured tables & fields) | Yes |
| Data blocking (skip objects and fields) | Yes |
| Resync (objects and Pipelines) | Yes |
| API configurable | Yes |
Prerequisites
-
An active Pinterest Ads account from which data is to be ingested.
-
You have the Owner or Admin role on the Pinterest ad account(s) you want to sync, to ingest data for all the objects. If you have a different role, such as Analyst or Campaign Manager, Hevo ingests only the objects that your role can access. The other objects are shown as inaccessible on the Configure Objects page.
Configure Pinterest Ads as a Source in your Pipeline
Perform the following steps to configure your Pinterest Ads Source:
-
Click Pipelines in the Navigation Bar.
-
Click + Create Pipeline in the Pipelines List View.
-
On the Select Source Type page, select Pinterest Ads.
-
On the Select Destination Type page, select the type of Destination you want to use.
-
On the Select Pipeline Type page, click Edge, and then click Continue.

This page appears only if the selected Destination type is supported in Edge and your Team has an existing Pinterest Ads Pipeline with the same Destination type. Otherwise, you can proceed to create an Edge Pipeline.
-
In the Configure Source screen, specify the following:

-
Source Name: A unique name for your Source, not exceeding 255 characters. For example, Pinterest Ads Source.
-
In the Connect to your Pinterest Ads account section, click Authenticate Your Pinterest Ads Account, log in to your Pinterest account, and grant Hevo the requested permissions.
-
In the Sync Settings section, specify the following:

-
Ad Account Selection: Select whether you want Hevo to sync all ad accounts or only specific ones:
-
Sync all ad accounts: Syncs data for all ad accounts that Hevo has access to.
-
Sync specific ad accounts: Syncs data only for specific ad accounts you select. If you select this option, in the Ad Accounts to Sync section, select the specific Pinterest ad accounts whose data you want to sync. Ad accounts that you add to Pinterest later are synced only after you select them here.

-
-
-
In the Report Settings section, specify the following:
-
Click Attribution Window: The number of days between a person clicking your ad and taking an action. Default value: 30 days.
-
View Attribution Window: The number of days between a person viewing your ad and taking an action. This value cannot exceed the click attribution window. Default value: 1 day.
-
Conversion Report Time: The date on which conversions are reported, based on when the person interacted with the ad or when the conversion happened. Default value: Ad event.
-
Report Granularity: The time period that each row in the report tables covers. You cannot change this setting after the Pipeline is created. Default value: Daily. Select one of the following options:
-
Daily: Creates one row per entity for each day.
-
Hourly: Creates one row per entity for each hour. Hourly reports include data only for the last 8 days and do not include conversion metrics.
-
Weekly: Creates one row per entity for each week, from Monday to Sunday. Each row is identified by the first day of the week, and the current week’s row is updated as new data arrives.
-
Monthly: Creates one row per entity for each month. Each row is identified by the first day of the month, and the current month’s row is updated as new data arrives.
-
Total (last 30 days): Creates one row per entity that holds its totals for the last 30 days. Hevo updates the row in each sync if the entity had activity in that period. Otherwise, the entity keeps its last row.
Note: The MMM Ad Group Targeting Daily Report and MMM Campaign Targeting Daily Report objects always contain daily data, irrespective of the granularity you select.
-
-
Historical Sync Duration: The duration for which you want to ingest existing data for the report objects from the Source. You cannot change this setting after the Pipeline is created. Default value: 3 months.
-
-
(Optional) In the Custom Reports section, click + Custom Report to define a report. Each report you define is ingested into its own table in the Destination. For each report, specify the following:

-
Report name: A name for the report, which is used as the name of its Destination table. The name must be unique across your custom reports, contain only letters, numbers, and underscores, and must not start with a number. It also cannot be the same as the name of an existing Pinterest Ads object, such as campaign_report.
Note: If you rename a report after the Pipeline is created, you must resync the report’s object. Hevo then creates a table with the new name in the Destination. The table with the earlier name remains in the Destination with its existing data.
-
Breakdown: From the drop-down, select the level at which the report data is broken down, for example, one row per campaign or per ad group. Select one of Advertiser, Campaign, Ad group, Pin promotion, Pin promotion targeting, Product group, Product group targeting, Keyword, Campaign targeting, Ad group targeting, or Advertiser targeting. The targeting breakdowns add one row for each targeting value, such as age, gender, or location.
-
Granularity: From the drop-down, select the time period that each row of the report covers. Select one of Daily, Hourly, Weekly, Monthly, or Total (last 30 days). This value applies only to this report and is used instead of the Report Granularity setting. Hourly reports include data only for the last 8 days and do not include conversion metrics.
-
(Optional) Click Attribution Window: The number of days between a person clicking the ad and taking an action. Select one of 1 day, 7 days, 30 days, or 60 days. If you leave this field blank, Hevo uses the value of the Click Attribution Window field in the Report Settings section.
-
(Optional) View Attribution Window: The number of days between a person viewing the ad and taking an action. This value cannot exceed the click attribution window. Select one of 1 day, 7 days, 30 days, or 60 days. If you leave this field blank, Hevo uses the value of the View Attribution Window field in the Report Settings section.
-
(Optional) Conversion Report Time: The date on which conversions are reported. Select Ad event to report a conversion on the day of the ad interaction, or Conversion event to report it on the day of the conversion. If you leave this field blank, Hevo uses the value of the Conversion Report Time field in the Report Settings section.
-
Metrics: The metrics to include as columns in the report’s table. You can browse the metrics by category, such as Spend & impressions and Conversion rates, or search for them by name. The conversion metrics are calculated based on the attribution windows and conversion report time of the report.
Note:
-
Click Save to add each report. Any report that is not saved before you click Test & Continue is not included in the Pipeline.
-
If you change a custom report after the Pipeline is created, such as its name, breakdown, granularity, attribution windows, or metrics, you must resync the report’s object for the changes to take effect.
-
-
-
Click Test & Continue to test the connection to your Pinterest Ads Source. Once the test is successful, you can proceed to set up your Destination.
Note: If any custom report is configured incorrectly, such as with a duplicate report name or no metrics selected, clicking Test & Continue fails the Source configuration. Hevo lists all configuration issues in your custom reports. You can fix these issues by editing the reports before retrying.
Configure Pinterest Ads as a Source Using the Hevo API
You can connect Hevo to your Pinterest Ads account with an OAuth app created in your Pinterest developer account. This method is available only through the Hevo API. Specify the credentials of the app in the request that creates the Pipeline, and Hevo uses them to authenticate with your account.
The following credentials from your OAuth app are required to authenticate the connection:
-
Client ID: The unique identifier of your app. In Pinterest, this identifier is the app ID. Read How do I find a client ID (or app ID)? for more information.
-
Client Secret: The private key of your app. Hevo sends it with the client ID to authenticate the request. In Pinterest, this key is the secret key. Read How do I find my app’s secret key? for more information.
-
Refresh Token: A long-lived token that your app receives the first time a Pinterest user authorizes it. Hevo exchanges this token for a short-lived access token when the Pipeline is created, and refreshes that token automatically, so the connection keeps working without anyone signing in again. Read Refresh a token for more information.
Create the app in your Pinterest developer account and request the following scopes:
| Scope | Allows Hevo to |
|---|---|
ads:read |
Read your ad accounts, campaigns, ad groups, ads, and their reports. |
boards:read |
Read your public and protected boards, which Hevo replicates in the Board History object. Hevo also needs it, along with pins:read, to read your Pins. |
boards:read_secret |
Read your secret boards. |
pins:read |
Read your Pins, which Hevo replicates in the Pin History object. |
pins:read_secret |
Read your secret Pins. |
catalogs:read |
Read your product catalogs and their feeds, which Hevo replicates in the Catalog Feed History object. |
user_accounts:read |
Read your Pinterest account details, which Hevo replicates in the User Account object. Hevo also uses this scope to test the Source connection when you create the Pipeline. |
Read Connect app for the steps to create the app, and Available scopes for more information about the scopes.
Prepare the Source Configuration
Before you build your request, retrieve the settings that the Pinterest Ads connector currently accepts. Refer to Read the Connector Configuration for the steps to retrieve them, and Using your own OAuth app for the keys that this method accepts.
In the response, the auth object describes the credentials of your own OAuth app. In the connector configuration response, Hevo returns the auth object under data.schema.properties.auth, and the connector settings under data.schema.properties.config. Only a connector that accepts an OAuth app has an auth property. Each credential carries "type": "string". Every credential except client_id also carries "format": "password" and "writeOnly": true. The following example shows part of the auth object:
{
"auth": {
"required": [
"client_access"
],
"properties": {
"client_access": {
"required": [
"client_id",
"client_secret"
],
"properties": {
"client_id": {
"title": "Client ID"
},
"client_secret": {
"title": "Client Secret"
}
}
},
"refresh_token": {
"title": "Refresh Token"
},
"access_token": {
"title": "Access Token"
}
},
"anyOf": [
{
"required": [
"refresh_token"
]
},
{
"required": [
"access_token"
]
}
]
}
}
The anyOf block in the schema accepts either refresh_token or access_token, because that part of the schema is the same for every connector. For a Pinterest Ads Source, send refresh_token. Hevo needs the refresh token to keep the Source authorized, so a request that sends only an access token fails while the Pipeline is being created.
By default Hevo syncs every ad account, because config.sync_mode defaults to ALL_AD_ACCOUNTS. To sync only some of them, set it to SPECIFIC_AD_ACCOUNTS and list the ad account IDs as strings in config.selected_ad_accounts.
Specify the credentials of your app in the auth object. The following example shows the source object for a Pinterest Ads Source:
{
"name": "<source_name>",
"connector_id": "pinterest_ads",
"type": "PINTEREST_ADS",
"config": {
"historical_sync_timeframe": "THREE"
},
"auth": {
"client_access": {
"client_id": "<client_id>",
"client_secret": "<client_secret>"
},
"refresh_token": "<refresh_token>"
}
}
Note: Replace the placeholder values in the example with your own. For example, <source_name> with My Pinterest Ads Account.
Specify this source object in the request that creates your Pipeline. Read Creating a Pipeline with Hevo API for the complete request and the remaining steps.
Hevo validates the credentials and tests the Source and Destination connections before it saves anything. To test the Source connection, Hevo uses the credentials in the auth object to generate an access token. If a credential is rejected or a test fails, the request returns an error, and no Pipeline is created. Hevo also deletes the access token that it generated.
Note: Hevo does not store these credentials in the Source configuration. It exchanges them for a token when the Pipeline is created and refreshes that token from then on. Hevo does not return them if you retrieve the Source configuration later. If you revoke the credentials in Pinterest, Hevo cannot authenticate with the Source. As a result, all active jobs for the Pipeline fail, and no data is replicated. To resume data replication, send the new credentials using the Modify Source Configuration in a Pipeline endpoint. Read Modifying the Source Configuration for the steps to send them.
Data Replication
Hevo replicates data for all the objects selected on the Configure Objects page during Pipeline creation. By default, all supported objects and their available fields are selected. However, you can modify this selection while creating or editing the Pipeline.
Selecting a parent object automatically includes all its associated child objects for replication. However, you can select or deselect the child objects individually, and you can select a child object without selecting its parent object.
Hevo ingests the following types of data from your Source objects:
-
Historical Data: The first run of the Pipeline ingests historical data for the selected objects, based on the Historical Sync Duration specified when configuring the Source, and loads it into the Destination.
-
Incremental Data: Once the historical load is complete, new and updated records for objects are ingested as per the sync frequency.
For the following objects, Hevo ingests only the incremental data in subsequent Pipeline runs:
-
Advertiser Report
-
Ad Group Report
-
Campaign Report
-
Keyword Report
-
MMM Ad Group Targeting Daily Report
-
MMM Campaign Targeting Daily Report
-
Pin Promotion Report
-
Pin Promotion Targeting Report
-
Product Group Report
-
Product Group Targeting Report
-
Product Item Report
Custom report objects are also ingested this way. If you add a custom report after the Pipeline is created, Hevo ingests its historical data based on the Historical Sync Duration specified when configuring the Source.
For the report objects, Hevo also re-fetches the data every 24 hours. This captures any updates made to previously ingested data and keeps your Destination up to date.
For custom report objects, Hevo re-fetches the data of the last 7 days, or of the report’s click attribution window if it is longer, once every 24 hours. This captures conversions that Pinterest reports with a delay. For reports with the Hourly granularity, Hevo re-fetches at most the last 8 days. For reports with the Weekly or Monthly granularity, Hevo re-fetches the data from the start of the week or month in which this period begins. For reports with the Total (last 30 days) granularity, Hevo ingests the data of the last 30 days during each sync.
For all other objects, Hevo ingests the entire data during each Pipeline run.
Pinterest enforces a rate limit on the number of requests that can be made to its API in a given period of time. If this limit is exceeded, a rate limit exception occurs. To understand how Hevo handles such scenarios, read Handling Rate Limit Exceptions.
Note: You can create a Pipeline with this Source only using the Merge load mode. The Append mode is not supported for this Source.
Schema and Primary Keys
Hevo uses the following schema to upload the records to the Destination. For a detailed view of the objects, fields, and relationships, click the ERD.
Data Model
The following is the list of tables (objects) that are created at the Destination when you run the Pipeline:
| Object | Description |
|---|---|
| Advertiser History | Contains a record of changes made over time to each Pinterest ad account, which is used to create, manage, and pay for ads. Includes details such as the account’s name, country, currency, owner, and the permissions granted on it. |
| Advertiser Report | Contains performance metrics for each ad account, such as impressions, clicks, engagements, and spend, combined across all the ads it runs. |
| Ad Group History | Contains a record of changes made over time to each set of ads within a campaign that share the same budget, targeting, bidding, placement, and schedule settings. It includes a child object, Product Group History. |
| Ad Group Report | Contains performance metrics, such as impressions, clicks, engagements, and spend, for each set of ads within a campaign. |
| Audience History | Contains a record of changes made over time to each audience owned by your ad accounts, which is a group of people you can target with your ads. Includes details such as the audience’s name, type, size, and status. |
| Board History | Contains details about the boards that are available to your ad accounts, such as the board’s name, description, privacy setting, and owner. It includes the following child objects: - Board Pin Thumbnail URL - Board Section |
| Campaign History | Contains a record of changes made over time to each campaign, including its objective and the ads associated with it. |
| Campaign Report | Contains performance metrics, such as impressions, clicks, engagements, and spend, for each campaign and its ads. |
| Catalog Feed History | Contains a record of changes made over time to each catalog feed, which is a product data file that Pinterest fetches on a schedule. Includes details such as the feed’s name, format, location, and status. It includes a child object, Catalog Product Groups History. |
| Conversion Tag History | Contains details about the Pinterest tags of your ad accounts, which track the actions people take on your website after viewing or clicking your ads. Includes details such as the tag’s name, status, and when it last fired. It includes a child object, Conversion Tag Config. |
| Customer List History | Contains a record of changes made over time to each customer list owned by your ad accounts. Includes details such as the list’s name, status, and upload counts. It does not include the uploaded customer records. |
| Keyword History | Contains details about the targeting and negative keywords added to your ad accounts, campaigns, and ad groups, such as the keyword’s value, match type, and bid. |
| Keyword Report | Contains performance metrics, such as impressions, clicks, engagements, and spend, for each keyword in each ad, based on search traffic that matches the keyword. |
| MMM Ad Group Targeting Daily Report | Contains daily Marketing Mix Modeling (MMM) metrics, such as impressions, clicks, and spend, for each ad group, broken down by app type, gender, location, and creative type. |
| MMM Campaign Targeting Daily Report | Contains daily Marketing Mix Modeling (MMM) metrics, such as impressions, clicks, and spend, for each campaign, broken down by app type, gender, location, and creative type. |
| Pin History | Contains details about the Pins that are available to your ad accounts, such as the Pin’s title, description, link, media type, and the board it belongs to. It includes the following child objects: - Pin App Type Report - Pin Media - Pin Media Image |
| Pin Promotion History | Contains a record of changes made over time to each ad, which is a paid Pin used to reach a wider audience. Includes details such as the advertised Pin, its status, and tracking information. It includes the following child objects: - Ad Rejected Label History - Rejected Reason History |
| Pin Promotion Report | Contains performance metrics for each paid Pin, such as impressions, clicks, engagements, and spend. |
| Pin Promotion Targeting Report | Contains performance metrics, such as impressions, clicks, engagements, and spend, for each paid Pin, broken down by targeting type and value. |
| Product Group Report | Contains performance metrics, such as impressions, clicks, engagements, and spend, for each product group promoted in an ad group. |
| Product Group Targeting Report | Contains performance metrics, such as impressions, clicks, engagements, and spend, for each promoted product group, broken down by targeting type and value. |
| Product Item Report | Contains performance metrics, such as impressions, clicks, engagements, and spend, for each catalog product promoted in an ad group. |
| Targeting Age Bucket | Contains the list of age ranges that you can use to target your ads. |
| Targeting App Type | Contains the list of device and app types, such as mobile web and tablet, that you can use to target your ads. |
| Targeting Gender | Contains the list of genders that you can use to target your ads. |
| Targeting Geo | Contains the list of countries that you can use to target your ads. |
| Targeting Geo Metro | Contains the list of metropolitan areas, such as US Designated Market Areas (DMAs), that you can use to target your ads. |
| Targeting Geo Region | Contains the list of regions, such as states and provinces, that you can use to target your ads. |
| Targeting Interest | Contains Pinterest’s list of interests that you can use to target your ads, including each interest’s level and parent interest. |
| Targeting Locale | Contains the list of languages that you can use to target your ads. |
| Targeting Location | Contains the list of country and metropolitan area codes that you can use to target your ads by location. |
| User Account | Contains details of the Pinterest profile that owns the ad accounts, such as its username, whether it is a business or personal profile, and its business name. |
In addition to the objects listed above, you can define custom reports in the Source configuration. Each custom report you create is ingested into its own table, named after the report, containing the metrics you select.
Additional Information
Read the detailed Hevo documentation for the following related topics:
Source Considerations
-
Pinterest retains up to 30 months of daily report data and up to 8 days of hourly report data.
-
Hourly reports do not include conversion metrics.
-
Pinterest does not provide hourly keyword data. Hence, if you select the Hourly report granularity, the Keyword Report object is shown as inaccessible on the Configure Objects page. Similarly, a custom report with the Keyword breakdown and the Hourly granularity is shown as inaccessible on the Configure Objects page.
-
Pinterest provides product item data only for the last 366 days. Hence, the Product Item Report object cannot ingest data older than 366 days, irrespective of the Historical Sync Duration you select. If you select the Hourly report granularity, Hevo ingests daily data for this object.
-
Pinterest provides Pin analytics only for the last 90 days. Hence, the Pin App Type Report object contains organic engagement data, such as impressions, saves, and clicks, only for the last 90 days.
-
In the MMM Ad Group Targeting Daily Report and MMM Campaign Targeting Daily Report objects, Pinterest adds a prefix to the IDs, for example, A549763713300 for an ad account ID. Hence, you must remove the prefix to join these objects with other objects, such as Campaign History.
Revision History
Refer to the following table for the list of key updates made to this page:
| Date | Release | Description of Change |
|---|---|---|
| Oct-19-2026 | 2.54 | Added section, Configure Pinterest Ads as a Source Using the Hevo API. |
| Oct-15-2026 | 2.54 | Updated sections: - Prerequisites to add the objects that are ingested for users with roles other than Owner and Admin. - Configure Pinterest Ads as a Source in your Pipeline to add the Custom Reports section and update the field descriptions in the Sync Settings and Report Settings sections. - Data Replication and Data Model to add information about custom report objects. - Source Considerations to add that Pinterest does not provide hourly keyword data. - Supported Features to mark custom data as supported. |
| Oct-01-2026 | 2.54 | New document. |