Facebook Ads API Configuration
Request
POST https://api.fivetran.com/v1/connections
{
"group_id": "group_id",
"service": "facebook_ads",
"trust_certificates": true,
"trust_fingerprints": true,
"run_setup_tests": true,
"paused": false,
"pause_after_trial": false,
"sync_frequency": 1440,
"data_delay_sensitivity": "NORMAL",
"data_delay_threshold": 0,
"daily_sync_time": "14:00",
"schedule_type": "auto",
"connect_card_config": {
"redirect_uri": "https://your.site/path",
"hide_setup_guide": true
},
"proxy_agent_id": "proxy_agent_id",
"private_link_id": "private_link_id",
"networking_method": "Directly",
"hybrid_deployment_agent_id": "hybrid_deployment_agent_id",
"config": {
"custom_tables": [
{
"prebuilt_report_name": "string",
"use_unified_attribution_setting": true,
"view_attribution_window": "NONE | DAY_1 | DAY_1_EV | DAY_7 | DAY_28",
"level": "ad | adset | campaign | account | none",
"breakdowns": [
"ad_format_asset | age | app_id | body_asset | call_to_action_asset | country | description_asset | dma | gender | frequency_value | hourly_stats_aggregated_by_advertiser_time_zone | hourly_stats_aggregated_by_audience_time_zone | image_asset | impression_device | link_url_asset | place_page_id | placement | device_platform | product_id | publisher_platform | platform_position | region | skan_conversion_id | title_asset | video_asset | coarse_conversion_value | fidelity_type | hsid | is_conversion_id_modeled | postback_sequence_index | redownload | skan_campaign_id | action_converted_product_id | mmm | user_segment_key"
],
"click_attribution_window": "NONE | DAY_1 | DAY_1_EV | DAY_7 | DAY_28",
"aggregation": "Day | Week | Month | Lifetime",
"table_name": "table_1",
"action_report_time": "impression | conversion | mixed",
"engaged_view_attribution_window": "NONE | DAY_1 | DAY_1_EV | DAY_7 | DAY_28",
"action_breakdowns": [
"action_canvas_component_name | action_carousel_card_id | action_carousel_card_name | action_destination | action_device | action_link_click_destination | action_reaction | action_target_id | action_type | action_video_sound | action_video_type"
],
"config_type": "Prebuilt | Custom",
"fields": [
"account_currency | account_id | account_name | action_values | actions | ad_id | ad_name | adset_id | adset_name | app_store_clicks | attribution_setting | buying_type | call_to_action_clicks | campaign_id | campaign_name | canvas_avg_view_percent | canvas_avg_view_time | canvas_component_avg_pct_view | catalog_segment_value | click_to_app_deeplink | click_to_app_store | click_to_website | clicks | conversion_rate_ranking | conversion_values | conversions | converted_product_quantity | converted_product_value | cost_per_10_sec_video_view | cost_per_action_type | cost_per_conversion | cost_per_estimated_ad_recallers | cost_per_inline_link_click | cost_per_inline_post_engagement | cost_per_outbound_click | cost_per_thruplay | cost_per_total_action | cost_per_unique_action_type | cost_per_unique_click | cost_per_unique_inline_link_click | cost_per_unique_outbound_click | cpc | cpm | cpp | ctr | date_start | date_stop | deeplink_clicks | engagement_rate_ranking | estimated_ad_recall_rate | estimated_ad_recallers | frequency | full_view_impressions | full_view_reach | gender_targeting | impressions | inline_link_click_ctr | inline_link_clicks | inline_post_engagement | instant_experience_clicks_to_open | instant_experience_clicks_to_start | instant_experience_outbound_clicks | labels | location | mobile_app_purchase_roas | newsfeed_avg_position | newsfeed_clicks | newsfeed_impressions | objective | optimization_goal | outbound_clicks | outbound_clicks_ctr | purchase_roas | quality_ranking | reach | relevance_score | social_clicks | social_impressions | social_reach | social_spend | spend | total_action_value | total_actions | total_unique_actions | unique_actions | unique_clicks | unique_ctr | unique_impressions | unique_inline_link_click_ctr | unique_inline_link_clicks | unique_link_clicks_ctr | unique_outbound_clicks | unique_outbound_clicks_ctr | unique_social_clicks | video_10_sec_watched_actions | video_15_sec_watched_actions | video_30_sec_watched_actions | video_avg_percent_watched_actions | video_avg_time_watched_actions | video_continuous_2_sec_watched_actions | video_p100_watched_actions | video_p25_watched_actions | video_p50_watched_actions | video_p75_watched_actions | video_p95_watched_actions | video_play_actions | video_play_curve_actions | video_thruplay_watched_actions | website_clicks | website_ctr | website_purchase_roas | ad_click_actions | ad_impression_actions | auction_bid | auction_competitiveness | auction_max_competitor_bid | catalog_segment_actions | catalog_segment_value_mobile_purchase_roas | catalog_segment_value_omni_purchase_roas | catalog_segment_value_website_purchase_roas | cost_per_15_sec_video_view | cost_per_2_sec_continuous_video_view | cost_per_ad_click | cost_per_dda_countby_convs | cost_per_one_thousand_ad_impression | created_time | dda_countby_convs | instagram_upcoming_event_reminders_set | interactive_component_tap | place_page_name | qualifying_question_qualify_answer_rate | video_play_retention_0_to_15s_actions | video_play_retention_20_to_60s_actions | video_play_retention_graph_actions | video_time_watched_actions | wish_bid | user_segment_key"
]
}
],
"sync_mode": "AllAccounts | SpecificAccounts",
"sync_metadata": true,
"timeframe_months": "THREE | SIX | TWELVE | TWENTY_FOUR | ALL_TIME",
"accounts": [
"string"
],
"schema": "schema_name"
},
"auth": {
"access_token": "my_access_token",
"client_access": {
"client_secret": "my_client_secret",
"client_id": "my_client_id"
},
"user_access_token": "string"
}
}Config parameters
| Name | Description |
|---|---|
custom_tables | List of custom tables. Each custom table corresponds to a table within the schema to which connector will sync the data. |
custom_tables[0].prebuilt_report_name | The report name to which connector will sync the data. Possible prebuilt_report values. |
custom_tables[0].use_unified_attribution_setting | |
custom_tables[0].view_attribution_window | Time period to attribute conversions based on views. Possible view_attribution_window values. |
custom_tables[0].level | |
custom_tables[0].breakdowns | List of breakdowns which connector will sync. Possible breakdowns values. |
custom_tables[0].click_attribution_window | Time period to attribute conversions based on clicks. Possible click_attribution_window values. |
custom_tables[0].aggregation | Options to select aggregation duration. Possible aggregation values. |
custom_tables[0].table_name | The table name within the schema to which the connector will sync the data. It must be unique within the connector and must comply with Fivetran's naming conventions. |
custom_tables[0].action_report_time | The report time of action stats. Possible action_report time values. |
custom_tables[0].engaged_view_attribution_window | Time period to attribute conversions based on engaged views. Possible view_attribution_window values. |
custom_tables[0].action_breakdowns | List of action_breakdowns which connector will sync. Possible action_breakdowns values. |
custom_tables[0].config_type | Option to select Prebuilt Reports or Custom Reports. Possible config_type values. |
custom_tables[0].fields | List of fields which connector will sync. Possible field values. |
sync_mode | Option to select connector should sync all accounts or specific accounts. Possible sync_mode values. |
sync_metadata | Parameter defining whether to enable or disable metadata synchronisation. Default value: TRUE. |
timeframe_months | Number of months' worth of reporting data you'd like to include in your initial sync. This cannot be modified once the connector is created. Default value: THREE. |
accounts | List of accounts of which connector will sync the data. |
schema | Destination schema name. Schema name is permanent and cannot be changed after connection creation |
Authorization
There are two ways to authorize this connector type:
By specifying the values for the
client_accessandaccess_tokenparameters in theauthsection.POST https://api.fivetran.com/v1/connections{ "service": "facebook_ads", "group_id": "group_id", "auth": { "client_access": { "client_secret": "my_client_secret", "client_id": "my_client_id" }, "access_token": "my_access_token" } }Auth Parameters
Name Description access_tokenThe long-lived Access tokenalong with theclient_idandclient_secretparameters carry the information necessary to query the Facebook Ads APIclient_accessYour application client access fields.`` client_access.client_secretClient Secretof your Facebook client application.client_access.client_idClient IDof your Facebook client application.By using the Connect Card or the Fivetran dashboard.