Skip to main content

Pinterest

Availability:
Available Airbyte CloudAvailable Airbyte OSSAvailable PyAirbyte
Support Level:
Airbyte Connector
Connector Version:
2.0.10(Last updated a day ago)
CDK Version:
4.3.2(Latest)
Sync Success Rate:
Usage Rate:

This page contains the setup guide and reference information for the Pinterest source connector.

Prerequisites​

When setting up the Pinterest source connector with Airbyte Cloud, be aware that Pinterest does not allow configuring permissions during the OAuth authentication process. Therefore, the following permissions will be requested during authentication:

  • See all of your advertising data, including ads, ad groups, campaigns, etc.
  • See your public boards, including group boards you join.
  • See your secret boards.
  • See all of your catalogs data.
  • See your public Pins.
  • See your secret Pins.
  • See your user accounts and followers.

For more information on the scopes required for Pinterest OAuth, please refer to the Pinterest API Scopes documentation.

To set up the Pinterest source connector with Airbyte Open Source, you'll need your Pinterest App ID and secret key and the refresh token.

Setup guide​

For Airbyte Cloud:

  1. Log into your Airbyte Cloud account.
  2. Click Sources and then click + New source.
  3. On the Set up the source page, select Pinterest from the Source type dropdown.
  4. Enter the name for the Pinterest connector.
  5. For Start Date, enter the date in YYYY-MM-DD format. The data added on and after this date will be replicated. If this field is blank, Airbyte will replicate all data. As per Pinterest API restriction, the date cannot be more than 90 days in the past.
  6. The OAuth2.0 authorization method is selected by default. Click Authenticate your Pinterest account. Log in and authorize your Pinterest account.
  7. (Optional) Enter a Start Date using the provided date picker, or by manually entering the date in YYYY-MM-DD format. Data added on and after this date will be replicated. If no date is set, it will default to the latest allowed date by the report API (913 days from today).
  8. (Optional) Select one or multiple status values from the dropdown menu. For the ads, ad_groups, and campaigns streams, specifying a status will filter out records that do not match the specified ones. If a status is not specified, the source will default to records with a status of either ACTIVE or PAUSED.
  9. (Optional) Add custom reports if needed. For more information, refer to the corresponding section.
  10. Click Set up source.

For Airbyte Open Source:

  1. Navigate to the Airbyte Open Source dashboard.
  2. Click Sources and then click + New source.
  3. On the Set up the source page, select Pinterest from the Source type dropdown.
  4. Enter the name for the Pinterest connector.
  5. For Start Date, enter the date in YYYY-MM-DD format. The data added on and after this date will be replicated. If this field is blank, Airbyte will replicate all data. As per Pinterest API restriction, the date cannot be more than 90 days in the past.
  6. The OAuth2.0 authorization method is selected by default. For Client ID and Client Secret, enter your Pinterest App ID and secret key. For Refresh Token, enter your Pinterest Refresh Token.
  7. (Optional) Enter a Start Date using the provided date picker, or by manually entering the date in YYYY-MM-DD format. Data added on and after this date will be replicated. If no date is set, it will default to the latest allowed date by the report API (913 days from today).
  8. (Optional) Select one or multiple status values from the dropdown menu. For the ads, ad_groups, and campaigns streams, specifying a status will filter out records that do not match the specified ones. If a status is not specified, the source will default to records with a status of either ACTIVE or PAUSED.
  9. (Optional) Add custom reports if needed. For more information, refer to the corresponding section.
  10. Click Set up source.

Supported sync modes​

The Pinterest source connector supports the following sync modes:

Supported Streams​

Custom reports​

Custom reports in the Pinterest connector allow you to create personalized analytics reports for your account. You can tailor these reports to your specific needs by choosing from various properties:

  1. Name: A unique identifier for the report.
  2. Level: Specifies the data aggregation level, with options like ADVERTISER, CAMPAIGN, AD_GROUP, etc. The default level is ADVERTISER.
  3. Granularity: Determines the data granularity, such as TOTAL, DAY, HOUR, etc. The default is TOTAL, where metrics are aggregated over the specified date range.
  4. Columns: Identifies the data columns to be included in the report.
  5. Click Window Days (Optional): The number of days used for conversion attribution from a pin click action. This applies to Pinterest Tag conversion metrics. Defaults to 30 days if not specified.
  6. Engagement Window Days (Optional): The number of days used for conversion attribution from an engagement action. Engagements include saves, closeups, link clicks, and carousel card swipes. This applies to Pinterest Tag conversion metrics. Defaults to 30 days if not specified.
  7. View Window Days (Optional): The number of days used as the conversion attribution window for a view action. This applies to Pinterest Tag conversion metrics. Defaults to 1 day if not specified.
  8. Conversion Report Time (Optional): Indicates the date by which the conversion metrics returned will be reported. There are two dates associated with a conversion event: the date of ad interaction and the date of conversion event completion. The default is TIME_OF_AD_ACTION.
  9. Attribution Types (Optional): Lists the types of attribution for the report, such as INDIVIDUAL or HOUSEHOLD.
  10. Start Date (Optional): The start date for the report in YYYY-MM-DD format, defaulting to the latest allowed date by the report API (913 days from today).

For more detailed information and guidelines on creating custom reports, please refer to the Pinterest API documentation.

Performance considerations​

The connector is restricted by the Pinterest requests limitation.

Reference​

Config fields reference

Field
Type
Property name
string
start_date
arraynull
status
object
credentials
array<object>
custom_reports

Changelog​

Expand to review
VersionDatePull RequestSubject
2.0.102024-08-1043642Update dependencies
2.0.92024-08-0343280Update dependencies
2.0.82024-07-3039559Ensure config_error when state has improper format and update CDK version
2.0.72024-07-2742603Update dependencies
2.0.62024-07-2042343Update dependencies
2.0.52024-07-1341765Update dependencies
2.0.42024-07-1041449Update dependencies
2.0.32024-07-0639972Update dependencies
2.0.22024-06-1039367Fix type error when start date was not provided
2.0.12024-06-0439037[autopull] Upgrade base image to v1.2.1
2.0.02024-05-2037698Migrate to low-code
1.3.32024-04-2436655Schema descriptions and CDK 0.80.0
1.3.22024-04-0836912Fix icon
1.3.12024-04-0336806Update airbyte-cdk count bug to emit recordCount as float
1.3.02024-03-1936267Pin airbyte-cdk version to ^0
1.2.02024-02-2035465Per-error reporting and continue sync on stream failures
1.1.12024-02-1235159Manage dependencies with Poetry.
1.1.02023-11-2232747Update docs and spec. Add missing placement_traffic_type field to AdGroups stream
1.0.02023-11-1632595Add airbyte_type: timestamp_without_timezone to date-time fields across all streams. Rename Advertizer* streams to Advertiser*
0.8.22023-11-2032672Fix backoff waiting time
0.8.12023-11-1632601added ability to create custom reports
0.8.02023-11-1632592Make start_date optional; add suggested streams; add missing fields
0.7.22023-11-0832299added default AvailabilityStrategy, fixed bug which cases duplicated requests, added new streams: Catalogs, CatalogsFeeds, CatalogsProductGroups, Audiences, Keywords, ConversionTags, CustomerLists, CampaignTargetingReport, AdvertizerReport, AdvertizerTargetingReport, AdGroupReport, AdGroupTargetingReport, PinPromotionReport, PinPromotionTargetingReport, ProductGroupReport, ProductGroupTargetingReport, ProductItemReport, KeywordReport
0.7.12023-11-0132078handle non json response
0.7.02023-10-2531876Migrated to base image, removed token based authentication mthod becuase access_token is valid for 1 day only
0.6.02023-07-2528672Add report stream for CAMPAIGN level
0.5.32023-07-0527964Add id field to owner field in ad_accounts stream
0.5.22023-06-0226949Update BoardPins stream with note property
0.5.12023-05-1125984Add pattern for start_date
0.5.02023-05-1726188Add product_tags field to the BoardPins stream
0.4.02023-05-1626112Add is_standard field to the BoardPins stream
0.3.02023-05-0925915Add creative_type field to the BoardPins stream
0.2.62023-04-2625548Fix format issue for boards stream schema for fields with date-time
0.2.52023-04-190Update AMOUNT_OF_DAYS_ALLOWED_FOR_LOOKUP to 89 days
0.2.42023-02-2523457Add missing columns for analytics streams for pinterest source
0.2.32023-03-0123649Fix for HTTP - 400 Bad Request when requesting data >= 90 days
0.2.22023-01-2722020Set AvailabilityStrategy for streams explicitly to None
0.2.12022-12-1520532Bump CDK version
0.2.02022-12-1320242Add data-type normalization up to the schemas declared
0.1.92022-09-0615074Add filter based on statuses
0.1.82022-10-2118285Fix type of start_date
0.1.72022-09-2917387Set start_date dynamically based on API restrictions.
0.1.62022-09-2817304Use CDK 0.1.89
0.1.52022-09-1616799Migrate to per-stream state
0.1.42022-09-0616161Add ability to handle 429 - Too Many Requests error with respect to Max Rate Limit Exceeded Error
0.1.32022-09-0216271Add support of OAuth2.0 authentication method
0.1.22021-12-2210223Fix naming of AD_ID and AD_ACCOUNT_ID fields
0.1.12021-12-229043Update connector fields title/description
0.1.02021-10-297493Release Pinterest CDK Connector
Was this page helpful?