You can connect Facebook Lead Ads Connector with your Facebook Page or Ad Account to import Leads data into Treasure Data.

This topic includes:


  • Basic knowledge of Treasure Data, including the TD Toolbelt

  • A Facebook Page/Ad account with Leads retrieval permission

  • Authorized Treasure Data account access

Obtain Get Ad ID and Form ID


You can retrieve the Ad ID by adding the Ad ID column to your Ads Manager screen. From the Ads Manager screen, click the (+) sign from the right-hand-side, select Customize Columns... and search for the Ad ID column as shown on the image

Form ID

You can retrieve Form ID from Publishing Tools > Lead Ads Form and hover over the existing Form as shown.

Getting the Lead Form’s Field Name

1. Navigate to the Lead Ads Forms.

2. Select Download.
3. Select Download new leads.

4. Select CSV to download the CSV file.
5. Open the downloaded CSV file, the field names for your form are as shown:

Use the TD Console to Create Your Connection

You complete configuration in both the Facebook interface and in Treasure Data.

Create a New Connection

When you configure a data connection, you provide authentication to access the integration. In Treasure Data, you configure the authentication and then specify the source information.

1. Go to Integrations Hub >  Catalog and search and select Facebook Lead Ads.

The following dialog opens.

2. The method you use to authenticate Treasure Data with Facebook affects the steps you take to enable the data connector to import from Facebook.

3. Select Click here to connect to a new account.
You are redirected to Facebook to log in if you haven't login yet, or the consent page to grant access to Treasure Data.

4. Log into your Facebook account in the popup window:

After you grant access to Treasure Data, you are redirected back to TD Console.

5. Select Facebook Lead Ads again.
6. Select OAuth Authenticate method.
You see an OAuth connection with your account name in the dropdown list.
7. Select the account you want to use and then proceed to create the connection.

8. Select Continue
9. Provide Facebook Lead Ads authentication details.

10. Select Done.


You need a long-lived Access Token and optionally App Secret to authenticate using this method.
11. You can find more information on how to configure your connector using the Access token and App secret.
12. Enter the Access Token and App Secret and click Continue

13. Name your new Facebook Lead Ads Connection.
14. Select Done.

Transfer Your Facebook Leads Data to Treasure Data

After creating the authenticated connection, you are automatically taken to the Authentications tab. Look for the connection you created and click New Source.

  1. Search for the connection you created. 

  2. Select New Source. The Create Source dialog opens.

Name your Connection

  1. Type a name for your Source in the Data Transfer field.

  2. Select Next.

Source Table

    • When the checkbox Enable Guess Schema is checked, the connector downloads the first Lead Ad and performs schema guessing for field names and data type on this Ad only. If you have multiple forms and they differ in field names, data import may be missed or inconsistent. In this case, you must type all field names into the FORM FIELDS.

    • id, created_time, ad_id, ad_name, adset_id, adset_name, campaign_id, campaign_name, form_id, platform, is_organic are reserved words. Do not create a Facebook Form with these field names. Do not add these fields into the Form Fields, they are automatically added.

  1. Edit the following parameters:


    • Ad Account ID: (Optional) Your Facebook ad account id.
    • AD ID/Form ID: (Required if Ad Account ID is not set) Leads data can be imported by Ad Id or Form ID.

    • Created Time From: (Optional) Import Leads data submitted from this time until the current time. The field accepts ISO 8601 date-time format. For example, 2020-01-01T00:00:00+0700.

    • Incremental: Only import new data since the last run.

    • Enable Guess Schema: Use this feature to let the connector guess the form fields automatically, or you can type the form fields by clearing this and filling in the Field Name and Data Type in the FORM FIELDS.
      • Field Name: The Lead Form field name. 
      • Data Type: The data type of this field.

      • Timestamp format: You provide the timestamp format if the field is a timestamp field, for example, %Y-%m-%dT%H:%M:%S%z.

Data Settings

Data Settings allows you to customize the data transfer. 

Do not change the Column Name. Field names in the lead form are used as column names when import. However, special characters (not alphanumeric or underscore “_”) are not supported and will be converted to underscore.

  1. Select Next. The Data Settings page opens.

  2. Optionally, edit the data settings or skip this page of the dialog.

    • Skip invalid record(s): If selected, skips invalid Leads data and continues to import others. If not selected, jobs fail when invalid data is encountered.

    • Schema Settings: You can change the Data Type or Timestamp format column if you find the data type or timestamp format is invalid for that column.

Data Preview

You can see a preview of your data before running the import by selecting Generate Preview.

Data shown in the data preview is approximated from your source. It is not the actual data that is imported.

  1. Select Next.
    Data preview is optional and you can safely skip to the next page of the dialog if you want.

  2. To preview your data, select Generate Preview. Optionally, select Next

  3. Verify that the data looks approximately like you expect it to.

  4. Select Next.

Data Placement

For data placement, select the target database and table where you want your data placed and indicate how often the import should run.

  1.  Select Next. Under Storage you will create a new or select an existing database and create a new or select an existing table for where you want to place the imported data.

  2. Select a Database > Select an existing or Create New Database.

  3. Optionally, type a database name.

  4. Select a Table> Select an existing or Create New Table.

  5. Optionally, type a table name.

  6. Choose the method for importing the data.

    • Append (default)-Data import results are appended to the table.
      If the table does not exist, it will be created.

    • Always Replace-Replaces the entire content of an existing table with the result output of the query. If the table does not exist, a new table is created. 

    • Replace on New Data-Only replace the entire content of an existing table with the result output when there is new data.

  7. Select the Timestamp-based Partition Key column.
    If you want to set a different partition key seed than the default key, you can specify the long or timestamp column as the partitioning time. As a default time column, it uses upload_time with the add_time filter.

  8. Select the Timezone for your data storage.

  9. Under Schedule, you can choose when and how often you want to run this query.

    • Run once:
      1. Select Off.

      2. Select Scheduling Timezone.

      3. Select Create & Run Now.

    • Repeat the query:

      1. Select On.

      2. Select the Schedule. The UI provides these four options: @hourly, @daily and @monthly or custom cron.

      3. You can also select Delay Transfer and add a delay of execution time.

      4. Select Scheduling Timezone.

      5. Select Create & Run Now.

 After your transfer has run, you can see the results of your transfer in Data Workbench > Databases.

  • No labels