Skip to main content

Snapchat Marketing

This page guides you through the process of setting up the Snapchat Marketing source connector.

Prerequisites

For Airbyte Cloud:

  • An existing Snapchat Marketing business account

For Airbyte Open Source:

  • Client ID
  • Client Secret
  • Refresh Token

Setup guide

Step 1: Set up Snapchat

  1. Set up a Snapchat Business account

For Airbyte Open Source:

  1. Activate Access to the Snapchat Marketing API

  2. Add the OAuth2 app:

    • Adding the OAuth2 app requires the redirect_url parameter.
    • Save the Client ID and Client Secret
  3. Obtain a refresh token using OAuth2 authentication workflow.

    • Open the authorize link in a browser. It will look similar to this:
    https://accounts.snapchat.com/login/oauth2/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=snapchat-marketing-api&state=wmKkg0TWgppW8PTBZ20sldUwerf-m
    • Login & Authorize via UI
    • Locate the code query parameter in the redirect
    • Exchange the code for an access token and refresh token.

    Your request will appear similar to the following:

       curl -X POST \
    -d "code={one_time_use_code}" \
    -d "client_id={client_id}" \
    -d "client_secret={client_secret}" \
    -d "grant_type=authorization_code" \
    -d "redirect_uri=redirect_uri"
    https://accounts.snapchat.com/login/oauth2/access_token`

For more information on authenticating into the Snapchat API, read their documentation here You will receive the API key and refresh token in the response. Use this refresh token for the connector.

Step 2: Set up the source connector in Airbyte

For Airbyte Cloud:

  1. Log into your Airbyte Cloud account.
  2. In the left navigation bar, click Sources. In the top-right corner, click + new source.
  3. On the source setup page, select Snapchat Marketing from the Source type dropdown and enter a name for this connector.
  4. Click Authenticate your account.
  5. In the authentication window, log in and authorize access to your Snapchat account
  6. (Optional) Choose a Start Date. All data created on or after this date will be synced. If left blank, all records will be synced.
tip

The Start Date is required for the all streams that use start_time as a key (see Supported Streams section below).

  1. (Optional) Choose an End Date. All data created on or before this date will be synced. If left blank, all records will be synced.
  2. (Optional) Choose the Action Report Time, which specifies how conversions are reported. The default is set to conversion, and can be modified to impression.
  3. (Optional) Choose the 'Swip Up Attribution Window', which specifies the length of the attribution window for swipe up actions. The default is 28 days and can be adjusted.
  4. (Optional) Choose the View Attribution Window, which specifies the length of the attribution window for views. The default is 28 days and can be adjusted.
  5. Click 'Set up source'

For Airbyte Open Source:

  1. Open the Airbyte UI.
  2. In the left navigation bar, click Sources. In the top-right corner, click + new source.
  3. On the source setup page, select Snapchat Marketing from the Source type dropdown and enter a name for this connector.
  4. Add the Client ID, Client Secret, and Refresh Token obtained from the setup.
  5. (Optional) Choose a Start Date. All data created on or after this date will be synced. If left blank, all records will be synced.
tip

The Start Date is required for the all streams that use start_time as a key (see Supported Streams section below).

  1. (Optional) Choose an End Date. All data created on or before this date will be synced.
  2. (Optional) Choose the Action Report Time, which specifies how conversions are reported. The default is set to conversion, and can be modified to impression.
  3. (Optional) Choose the 'Swip Up Attribution Window', which specifies the length of the attribution window for swipe up actions. The default is 28 days and can be adjusted.
  4. (Optional) Choose the View Attribution Window, which specifies the length of the attribution window for views. The default is 28 days and can be adjusted.
  5. Click 'Set up source'

Supported streams and sync modes

StreamIncrementalKey
AdAccountsYes"id"
AdsYes"id"
AdSquadsYes"id"
CampaignsYes"id"
CreativesYes"id"
MediaYes"id"
OrganizationsYes"id"
SegmentsYes"id"
AdAccounts_Stats_HourlyYes["id", "granularity", "start_time"]
AdAccounts_Stats_DailyYes["id", "granularity", "start_time"]
AdAccounts_Stats_LifetimeNo["id", "granularity"]
Ads_Stats_HourlyYes["id", "granularity", "start_time"]
Ads_Stats_DailyYes["id", "granularity", "start_time"]
Ads_Stats_LifetimeNo["id", "granularity"]
AdSquads_Stats_HourlyYes["id", "granularity", "start_time"]
AdSquads_Stats_DailyYes["id", "granularity", "start_time"]
AdSquads_Stats_LifetimeNo["id", "granularity"]
Campaigns_Stats_HourlyYes["id", "granularity", "start_time"]
Campaigns_Stats_DailyYes["id", "granularity", "start_time"]
Campaigns_Stats_LifetimeNo["id", "granularity"]

Performance considerations

The Snapchat Marketing API limits requests to 1,000 items per page.

Syncing data with an hourly granularity often generates large data volumes and can take longer times to sync. We recommend syncing at a day granularity.

Reference

Config fields reference

Field
Type
Property name
string
client_id
string
client_secret
string
refresh_token
string
start_date
string
end_date
string
action_report_time
string
swipe_up_attribution_window
string
view_attribution_window

Changelog

Expand to review
VersionDatePull RequestSubject
1.2.62024-08-3144998Update dependencies
1.2.52024-08-2444735Update dependencies
1.2.42024-08-1743859Update dependencies
1.2.32024-08-1243826Fixed the bug with the missing spend field to supported *_stats_* streams
1.2.22024-08-1043539Update dependencies
1.2.12024-08-0343174Update dependencies
1.2.02024-07-3142010Migrate to CDK v4.1.0
1.1.22024-07-2742680Update dependencies
1.1.12024-07-2042366Update dependencies
1.1.02024-07-1642009Migrate to CDK v2.4.0
1.0.32024-07-1341855Update dependencies
1.0.22024-07-1041547Update dependencies
1.0.12024-07-0940132Update dependencies
1.0.02024-06-2039507Migrate to low-code CDK and add incremental functionality to organizations
0.6.22024-05-2238574Update authenticator package
0.6.12024-04-2436662Schema descriptions
0.6.02024-04-1030586Add attribution_windows,action_report_time as optional configurable params
0.5.02024-03-1936267Pin airbyte-cdk version to ^0
0.4.02024-02-2735660Add new fields to streams ads, adsquads, creatives, and media
0.3.22024-02-1235171Manage dependencies with Poetry.
0.3.02023-05-2226358Remove deprecated authSpecification in favour of advancedAuth
0.2.02023-05-1025948Introduce new field in the Campaigns stream schema
0.1.162023-04-2020897Add missing fields to Basic Stats schema
0.1.152023-03-0222869Specified date formatting in specification
0.1.142023-02-1022808Enable default AvailabilityStrategy
0.1.132023-01-2722023Set AvailabilityStrategy for streams explicitly to None
0.1.122023-01-1121267Fix parse empty error response
0.1.112022-12-2320865Handle 403 permission error
0.1.102022-12-1520537Run on CDK 0.15.0
0.1.92022-12-1420498Fix output state when no records are read
0.1.82022-10-0517596Retry 429 and 5xx errors when refreshing access token
0.1.62022-07-2114924Remove additionalProperties field from specs
0.1.52022-07-1314577Added stats streams hourly, daily, lifetime
0.1.42021-12-078429Update titles and descriptions
0.1.32021-11-107811Add oauth2.0, fix stream_state
0.1.22021-11-087499Remove base-python dependencies
0.1.12021-07-295072Fix bug with incorrect stream_state value
0.1.02021-07-264843Initial release supporting the Snapchat Marketing API