Facebook Ads Setup Guide

Follow our setup guide to connect Facebook Ads to Fivetran.

Prerequisites

To connect Facebook Ads to Fivetran, you need:

• An active Meta Ads Manager account with the following permissions for the accounts you'd like to sync:

  • An ads_read permission to sync Ads report information for any Ad accounts that you own or have been granted access to through this permission.
  • An ads_management permission to sync Ads accounts' metadata. This permission also requests the id and account_timezone fields of Ad accounts. The account_timezone field is required to save the correct report date in the destination.
  • A leads_retrieval permission to sync lead data collected from Facebook Lead Ads forms, including field responses and custom disclaimer acknowledgments.
  • A business_management permission is mandatory to ensure a successful setup. Without this permission, setup tests will fail.

• The breakdowns and fields you'd like to sync.

Setup instructions

Begin Fivetran configuration

1. In the connection setup form, enter the Destination schema name of your choice.

2. (Hybrid Deployment only) If your destination is configured for Hybrid Deployment, the Hybrid Deployment Agent associated with your destination is pre-selected for the connection. To assign a different agent, click Replace agent, select the agent you want to use, and click Use Agent.

3. Select the Authentication Method you want to use:

   • Select Grant User Access to authorize through OAuth. Click Authorize to allow Fivetran access to your Facebook Ads account using OAuth. We recommend this authentication method to most users because it bases the API's rate limit on the Fivetran application instead of a user's advertising account. The Fivetran application has a higher rate limit than a system user token. See our Facebook Ads troubleshooting article on rate limits for more information.

     We recommend logging in while in Incognito mode to ensure authorization of the correct account.

   • Select Use System User Token to authorize through a System User Token. We recommend this authentication method to organizations that don't want to ask their end-users to grant user access. Such organizations may include digital marketing agencies or Powered by Fivetran users.

     1. You must grant the ads_read, ads_management, business_management, pages_read_engagement, leads_retrieval and pages_show_list permissions while generating the system user token.
     2. In the Access Token field, enter your System User Token.
     3. Click Validate system user access token to validate the token permissions.
   The app for which you generated the system token must have the Standard or Advanced access level. If the app has the default No Access level, the system user tokens generated for these apps can not query the Ads API. Note that requirements for each access level are managed by a third party and can be changed at any time. If you see sudden access level errors after the connection setup, check your App review status and make sure the requirements for the specified access level are met.

4. (Optional) If you want to manage your credentials outside of Fivetran, enable the Use External Secrets Manager toggle. For some connectors and destinations, this toggle only appears after you select a credential-based authentication method. See the External Secret Managers documentation for more information.

   • If you have already configured External Secret Managers for your account, select one from the drop-down menu. Note that the list is filtered by the deployment model of the destination: if the destination uses SaaS Deployment, External Secret Managers configured for Hybrid Deployment won't be available, and vice versa.
   • To edit the details of the selected External Secret Manager, click Edit manager details in Account Settings.
   • To set up a new External Secret Manager, click Configure a new secrets manager. See the Create New External Secret Manager documentation for prerequisites and setup instructions.
   • You can manage all your External Secret Managers at any time under Account Settings. See the External Secret Managers documentation for more information.
   • When ESM is enabled, credential fields are replaced by ESM key fields. In each ESM key field, enter the name of the secret stored in your external secrets manager that corresponds to that credential — not the credential value itself. For more information, see External Secret Managers.

5. Select your sync mode:

   • Select Sync All Accounts to sync all accounts you have access to.
   • Select Sync Specific Accounts to sync specific accounts only. Use the Accounts list to add accounts you'd like to sync.

(Optional) Set up custom report

1. Click + Custom report if you want to sync a custom report.

2. Enter the Report name. It must be unique within this connection.

3. Select the type of time Aggregation for the report.

4. (optional) Set the Show Advanced Options toggle to ON if you want to sync the optional fields.

5. (optional) Select an Action Report Time for the report.

6. (optional) Select one or more Attribution windows for the report. The default selection is 7-day click, 1-day view, and Incrementality. You can choose any combination of the following values: 1-day click, 7-day click, 28-day click, 1-day view, 1-day engaged view, Incrementality, Incrementality (first conversion), and Incrementality (all conversions). These values map directly to Meta's action_attribution_windows API parameter.

7. (optional) Set the Use unified attribution setting toggle to ON if you want the Facebook API to return your ads results using the unified attribution settings defined at the ad set level.

8. Click Next.

9. (optional) Select Breakdowns you want to include in the report.

10. (optional) Select Action Breakdowns you want to include in the report.

11. Add at least one field to finalize your report.

    To sync conversions and actions data, include the action_type field from the Action Breakdowns selection as well as the following fields:

    • For conversions: conversions and actions from the Fields selection.
    • For conversion values: conversion_values and action_values from the Fields selection. To avoid discrepancies, we recommend using a union of the two resulting child tables (for example, <table_name>_conversions and <table_name>_actions).

    For more information on this configuration and the output of this data, see our Conversions and actions documentation.

12. Click Save to add your Custom report.

    Repeat the 12 steps above if you want to add another Custom report.

Finish Fivetran configuration

1. In the Historical Sync Time Frame drop-down, select how many months' worth of reporting data you'd like to include in your initial sync.

   Fivetran can only retrieve up to 37 months` worth of data from Facebook Ads. This limitation is from the source side.

2. (Optional) Set the Sync all metadata toggle to OFF if you want to sync only report data without any metadata.

3. Click Save & Test. Fivetran will take it from here and sync metadata and insights from your Facebook account.

Fivetran tests and validates the Facebook Ads connection. On successful completion of the setup tests, you can sync your Facebook Ads data to your destination.

Setup tests

Fivetran performs the following Facebook Ads connection tests:

• The Validating custom report names test checks that all custom report names are unique and valid.
• The Validate access for Ad accounts test verifies that Fivetran can query the Facebook Marketing API for each of your selected Ad accounts.
• The Validating action field is selected for action breakdowns test checks that you have selected an action field whenever action breakdowns are included in a custom report.
• The Validating selection of proper combination of fields & breakdowns test checks the selected fields and breakdowns for each custom report against a set of specific incompatibility rules, rather than validating only the compatibilities.
• The Validating restrictions for Off-Meta action metrics test checks that the selected breakdowns and fields comply with the restrictions for Off-Meta (off-Facebook) action metrics. This test is a warning rather than a pass-or-fail check and does not block the connection setup.
• The Validating retention of sync level test verifies that the sync level has not been changed for existing reports, which would require a data resync.
• The Validating user access token permissions test checks that the access token you provided has the required permissions to sync data from Facebook Ads.
• The Validate access for insights data test verifies that Fivetran can query the Facebook Insights API for your first Ad account.

Related articles

Connector Overview

Schema Information

Release Notes

API Connector Configuration

Documentation Home