ContextQMD
Back to Airbyte

Snapchat Marketing

docs/integrations/sources/snapchat-marketing.md

2.0.017.5 KB
Original Source

Snapchat Marketing

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

Prerequisites

<!-- env:cloud -->

For Airbyte Cloud:

  • An existing Snapchat Marketing business account
<!-- /env:cloud --> <!-- env:oss -->

For Airbyte Open Source:

  • Client ID
  • Client Secret
  • Refresh Token
<!-- /env:oss -->

Setup guide

Step 1: Set up Snapchat

  1. Set up a Snapchat Business account
<!-- env:oss -->

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:

    text
       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.

<!-- /env:oss -->

Step 2: Set up the source connector in Airbyte

<!-- env:cloud -->

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). ::: 7. (Optional) Choose an End Date. All data created on or before this date will be synced. If left blank, all records will be synced. 8. (Optional) Choose the Action Report Time, which specifies how conversions are reported. The default is set to conversion, and can be modified to impression. 9. (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. 10. (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. 11. Click 'Set up source'

<!-- /env:cloud --> <!-- env:oss -->

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). ::: 6. (Optional) Choose an End Date. All data created on or before this date will be synced. 7. (Optional) Choose the Action Report Time, which specifies how conversions are reported. The default is set to conversion, and can be modified to impression. 8. (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. 9. (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. 10. Click 'Set up source'

<!-- /env:oss -->

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.

Changelog

<details> <summary>Expand to review</summary>
VersionDatePull RequestSubject
1.5.312026-03-1074573Update dependencies
1.5.302026-03-0372736Update dependencies
1.5.292026-02-2473634fix(source-snapchat-marketing): add lookback_window P2D to mitigate UTC timezone mismatch (AI-Triage PR)
1.5.282026-01-2070672Update dependencies
1.5.272025-11-2570083Update dependencies
1.5.262025-11-1869489Update dependencies
1.5.252025-10-2968815Update dependencies
1.5.242025-10-2268591Add suggestedStreams
1.5.232025-10-2168234Update dependencies
1.5.222025-10-1467746Update dependencies
1.5.212025-10-0767447Update dependencies
1.5.202025-09-3066898Update dependencies
1.5.192025-09-2466264Update dependencies
1.5.182025-09-0965393Update dependencies
1.5.172025-08-1864940Re-release connector with fixed docker image entrypoint
1.5.162025-08-1163276Fix start time for stats streams
1.5.152025-08-1064480Update dependencies
1.5.142025-07-2663088Update dependencies
1.5.132025-07-0262488Fix end datetime to include today
1.5.122025-06-2860513Update dependencies
1.5.112025-05-1060113Update dependencies
1.5.102025-05-0459625Update dependencies
1.5.92025-04-2758395Update dependencies
1.5.82025-04-1257957Update dependencies
1.5.72025-04-0557412Update dependencies
1.5.62025-03-2956907Update dependencies
1.5.52025-03-2256300Update dependencies
1.5.42025-03-0855595Update dependencies
1.5.32025-03-0154546Update dependencies
1.5.22025-02-1554091Update dependencies
1.5.12025-02-0853569Update dependencies
1.5.02024-11-2644170Added Optional filters - Organization & Ad Account IDs
1.4.22025-02-0153083Update dependencies
1.4.12025-01-2552403Update dependencies
1.4.02025-01-2352110Make incremental per-partition streams concurrent
1.3.72025-01-1851999Update dependencies
1.3.62025-01-1151431Update dependencies
1.3.52024-12-2850796Update dependencies
1.3.42024-12-2150308Update dependencies
1.3.32024-12-1449414Update dependencies
1.3.22024-11-0548375Re-implement advanced_auth in connector spec
1.3.12024-10-2947837Update dependencies
1.3.02024-10-1546927Promoting release candidate 1.3.0-rc.1 to a main version.
1.3.0-rc.12024-10-0846570Migrate to Manifest-only
1.2.122024-10-1246800Update dependencies
1.2.112024-10-0546419Update dependencies
1.2.102024-09-2846106Update dependencies
1.2.92024-09-2145780Update dependencies
1.2.82024-09-1445477Update dependencies
1.2.72024-09-0745278Update dependencies
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
</details>