Facebook Ads is a comprehensive digital advertising platform that enables businesses to create, manage, and optimize advertising campaigns across Facebook, Instagram, Messenger, and Audience Network, providing advanced targeting, analytics, and automation tools to maximize marketing ROI.
Power end-to-end data operations for your Facebook Ads API with Nexla. Our bi-directional Facebook Ads connector is purpose-built for Facebook Ads, making it simple to ingest data, sync it across systems, and deliver it anywhere — all with no coding required. Nexla turns API-sourced data into ready-to-use, reusable data products and makes it easy to send data to Facebook Ads or any other destination. With comprehensive monitoring, lineage tracking, and access controls, Nexla keeps your Facebook Ads workflows fast, secure, and fully governed.
Features
Type: API
SourceDestination
Seamless API Integration: Connect to any endpoint as source or destination without coding, with automatic data product creation
Visual Composition & Chaining: Build complex integrations using visual templates, chain API calls, and compose workflows with data validation and filtering
API Proxy: Expose curated slices of your data securely with a secure and customizable API proxy that validates and transforms data on the fly
Request optimization with intelligent batching, retry, and caching to minimize API calls and costs
Before creating a Facebook Ads credential, you need to obtain a System User Access Token from your Facebook Business account. The System User Access Token is required to authenticate with the Facebook Ads API.
To obtain your System User Access Token, you need to have a Facebook Business account with API access enabled and a System User configured. Once you have access to your account, you can generate a System User Access Token from your Facebook Business Manager. The System User Access Token must have permissions to the Facebook resources you want to access. The access token is sent in the Authorization header with the Bearer prefix for all API requests to the Facebook Ads API. For detailed information about System User setup and authentication, refer to the Facebook Marketing API documentation.
After selecting the data source/destination type, click the Add Credential tile to open the Add New Credential overlay.
New Credential Overlay – Facebook Ads
Enter a name for the credential in the Credential Name field and a short, meaningful description in the Credential Description field.
Enter your Facebook System User Access Token in the System User Access Token field. This is the System User Access Token you obtained from your Facebook Business Manager (see Prerequisites). The System User Access Token must have permissions to the Facebook resources you want to access. The access token is sent in the Authorization header with the Bearer prefix (e.g., Bearer {token}) for all API requests to the Facebook Ads API.
Keep your System User Access Token secure and do not share it publicly. The System User Access Token provides access to your Facebook Ads account and should be treated as sensitive information. For detailed information about System User setup, obtaining access tokens, and managing permissions, see the Facebook Marketing API documentation.
Click the Save button at the bottom of the overlay. The newly added credential will now appear in a tile on the Authenticate screen during data source/destination creation.
To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Select the Facebook Ads connector tile, then select the credential that will be used to connect to the Facebook Ads instance, and click Next; or, create a new Facebook Ads credential for use in this flow.
Nexla provides pre-built templates that can be used to rapidly configure data sources to ingest data from common Facebook Ads endpoints. Each template is designed specifically for the corresponding Facebook Ads endpoint, making data source setup easy and efficient. Select the endpoint from which this source will fetch data from the Endpoint pulldown menu. Available endpoint templates are listed in the expandable boxes below. Click on an endpoint to see more information about it and how to configure your data source for this endpoint.
Get My Ad Accounts
This endpoint fetches all ad accounts associated with this user. This resulting dataset will contain id, account_id and name of each ad account. Use this endpoint when you need to access ad account information, account lists, or account data from your Facebook Ads account.
Enter the Facebook Marketing API version in the Facebook API Version field. This is the API version to use for requests (e.g., v23.0). The default value is v23.0 if not specified.
The endpoint uses GET requests to https://graph.facebook.com/{api_version}/me/adaccounts?fields=id,account_id,name where {api_version} is the Facebook API Version you provide. The endpoint URL is automatically constructed based on the Facebook Graph API base URL and the API version.
The endpoint uses URL-based pagination, automatically fetching additional pages as needed. When a response includes a paging.next value, Nexla automatically uses it as the URL for the subsequent request to fetch the next page of results.
The endpoint will return all ad accounts associated with the user. The response data is extracted from the data array in the API response ($.data[*]), with each ad account record processed individually.
The Facebook API Version should match a valid Facebook Marketing API version. The endpoint uses URL-based pagination (iteration.type: paging.next.url) through the paging.next mechanism. When a response includes a paging.next value, Nexla automatically uses it as the URL for the subsequent request. The response data path is $.data[*], which extracts all items from the data array in the API response. For detailed information about listing ad accounts, see the Facebook Marketing API documentation.
Get Custom Audiences for an Ad Account
This endpoint retrieves the ad account's custom audiences. These help you target ads to people who already have a relationship with your business. Use this endpoint when you need to access custom audience information, audience lists, or audience data from your Facebook Ads account.
Select the Ad Account ID for which you want to fetch custom audiences from the Ad Account ID dropdown menu. This is the ad account ID for fetching custom audiences. You can select from ad accounts retrieved using the "Get My Ad Accounts" endpoint, or enter a custom ad account ID.
Enter the Facebook Marketing API version in the Facebook API Version field. This is the API version to use for requests (e.g., v23.0). The default value is v23.0 if not specified.
The endpoint uses GET requests to https://graph.facebook.com/{api_version}/act_{ad_account_id}/customaudiences?fields=id,name,subtype,time_created,time_updated,time_content_updated,approximate_count_upper_bound,approximate_count_lower_bound,sharing_status where {api_version} is the Facebook API Version and {ad_account_id} is the Ad Account ID you provide. The endpoint URL is automatically constructed based on the Facebook Graph API base URL, the API version, and the ad account ID.
The endpoint uses URL-based pagination, automatically fetching additional pages as needed. When a response includes a paging.next value, Nexla automatically uses it as the URL for the subsequent request to fetch the next page of results.
The endpoint will return all custom audiences for the specified ad account. The response data is extracted from the data array in the API response ($.data[*]), with each custom audience record processed individually.
Ad Account IDs can be obtained from the "Get My Ad Accounts" endpoint, which returns all ad accounts with their corresponding IDs. The endpoint uses URL-based pagination (iteration.type: paging.next.url) through the paging.next mechanism. The response data path is $.data[*], which extracts all items from the data array in the API response. For detailed information about listing custom audiences, see the Facebook Marketing API documentation.
Get Insights for an Ad Account
This endpoint gets insights on your advertising performance for an ad account. Select the appropriate date preset for the relative time range. Use this endpoint when you need to access advertising performance metrics, insights data, or analytics information from your Facebook Ads account.
Select the Ad Account ID for which you want to fetch insights from the Ad Account ID dropdown menu. This is the ad account ID for fetching insights. You can select from ad accounts retrieved using the "Get My Ad Accounts" endpoint, or enter a custom ad account ID.
Select the insight time range from the Insight for Time Range dropdown menu. This represents a relative time range for fetching insights. Available options include:
today: Today's data
yesterday: Yesterday's data (default)
this_month: This month's data
last_month: Last month's data
this_quarter: This quarter's data
maximum: Maximum available data
last_3d: Last 3 days
last_7d: Last 7 days
last_14d: Last 14 days
last_28d: Last 28 days
last_30d: Last 30 days
last_90d: Last 90 days
And other time range options
The default value is yesterday if not specified.
Enter the Facebook Marketing API version in the Facebook API Version field. This is the API version to use for requests (e.g., v23.0). The default value is v23.0 if not specified.
The endpoint uses GET requests to https://graph.facebook.com/{api_version}/act_{ad_account_id}/insights?date_preset={date_preset} where {api_version} is the Facebook API Version, {ad_account_id} is the Ad Account ID, and {date_preset} is the Insight for Time Range you select. The endpoint URL is automatically constructed based on the Facebook Graph API base URL, the API version, the ad account ID, and the date preset.
The endpoint uses URL-based pagination, automatically fetching additional pages as needed. When a response includes a paging.next value, Nexla automatically uses it as the URL for the subsequent request to fetch the next page of results.
The endpoint will return insights for the specified ad account and time range. The response data is extracted from the data array in the API response ($.data[*]), with each insight record processed individually.
Ad Account IDs can be obtained from the "Get My Ad Accounts" endpoint. The date preset determines the time range for which insights are retrieved. The endpoint uses URL-based pagination (iteration.type: paging.next.url) through the paging.next mechanism. The response data path is $.data[*], which extracts all items from the data array in the API response. Click on the Facebook document link for more information about default fields returned. For detailed information about getting insights, see the Facebook Marketing API documentation.
Get Insights for an Ad Account (Async)
This endpoint gets insights on your advertising performance for an ad account using asynchronous processing. Check out Facebook API documentation for appropriate query format. Use this endpoint when you need to access advertising performance metrics for large datasets that require asynchronous processing.
Enter the Ad Account ID for which you want to fetch insights in the Ad Account ID field. This is the ad account ID for fetching insights.
Enter the query format for the insights request in the Query field. This should follow the Facebook API documentation format for insights queries. Check out Facebook API documentation for appropriate query format.
The endpoint uses a multi-step process: first, it sends a POST request to initiate an async insights report, then polls for completion, and finally retrieves the results. The endpoint URL is automatically constructed based on the Facebook Graph API base URL and the ad account ID.
The endpoint uses asynchronous polling to wait for report completion, then uses URL-based pagination to retrieve all results. When a response includes a paging.next value, Nexla automatically uses it as the URL for the subsequent request to fetch the next page of results.
The endpoint will return insights for the specified ad account. The response data is extracted from the data array in the API response ($.data[*]), with each insight record processed individually.
This endpoint uses asynchronous processing for large insights reports. The query format should follow the Facebook API documentation format. The endpoint uses async polling (iteration.type: async.poll) to wait for report completion, then URL-based pagination (iteration.type: paging.next.url) to retrieve results. The response data path is $.data[*], which extracts all items from the data array in the API response. For detailed information about async insights and query formats, see the Facebook Marketing API documentation.
Once the selected endpoint template has been configured, click the Test button to the right of the endpoint selection menu to retrieve a sample of the data that will be fetched. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right, allowing you to verify that the source is configured correctly before saving. If the sample data is not as expected, review the selected endpoint and associated settings, make any necessary adjustments, and test again.
Facebook Ads data sources can also be manually configured to ingest data from any valid Facebook Ads API endpoint, including endpoints not covered by the pre-built templates, chained API calls, or custom request parameters. Select the Advanced tab at the top of the configuration screen, and follow the instructions in Connect to Any API to configure the API method, endpoint URL, date/time and lookup macros, path to data, metadata, and request headers.
The Facebook Ads API base URL follows the pattern https://graph.facebook.com/{api_version}/{endpoint_path}, where {api_version} is the Facebook Marketing API version (e.g., v23.0). Facebook Ads API responses typically use a data array structure, so $.data[*] is the typical path to data for list endpoints. You do not need to include the Authorization header — Nexla automatically includes the System User Access Token as a Bearer token in every API request.
Once all of the relevant settings have been configured, click the Create button in the upper right corner of the screen to save and create the new Facebook Ads data source. Nexla will now begin ingesting data from the configured endpoint and will organize any data that it finds into one or more Nexsets.
Click the + icon on the Nexset that will be sent to the Facebook Ads destination, and select the Send to Destination option from the menu. Select the Facebook Ads connector from the list of available destination connectors, then select the credential that will be used to connect to the Facebook Ads organization, and click Next; or, create a new Facebook Ads credential for use in this flow.
Nexla provides pre-built templates that can be used to rapidly configure destinations to send data to common Facebook Ads endpoints. Each template is designed specifically for the corresponding Facebook Ads endpoint, making destination setup easy and efficient. Select the endpoint to which data will be sent from the Endpoint pulldown menu. Then, click on the template in the list below to expand it, and follow the instructions to configure additional endpoint settings.
Add Users to Custom Audience
This endpoint adds people to your ad's audience with a hash of data from your business. Configure the parameters below to define the mapping between dataset attributes and the custom audience fields. Use this endpoint when you need to add users to custom audiences in your Facebook Ads account from your data sources.
Enter the Custom Audience ID to which you want to add users in the Custom Audience ID field. This is the custom audience ID you want to add users to.
Enter the ordered schema fields for the payload in the Ordered Schema Fields for Payload field. This should be a comma-separated list of schema field names that define the structure of the data being sent. These fields should match the Facebook API requirements for custom audience data.
Enter the data mapping for rows of data in the Data Mapping for rows of data field. This should be a comma-separated list of dataset attribute names that correspond to the schema fields. These attributes will be mapped to the schema fields when sending data to Facebook.
Enter the Facebook Marketing API version in the Facebook API Version field. This is the API version to use for requests (e.g., v23.0). The default value is v23.0 if not specified.
Select the maximum parallelization level from the Max Parallelization dropdown menu. This controls the number of concurrent requests made to the Facebook API. Available options are 1, 2, 4, 8, 16, and 32. The default value is 16 if not specified. Update this value to increase or decrease the number of concurrent requests. This should be reduced only if you are observing rate limits from the Facebook API.
The endpoint uses POST requests to https://graph.facebook.com/{api_version}/{custom_audience_id}/users where {api_version} is the Facebook API Version and {custom_audience_id} is the Custom Audience ID you provide. The endpoint URL is automatically constructed based on the Facebook Graph API base URL, the API version, and the custom audience ID.
The endpoint sends data from your Nexset as the request body in JSON format. The request body is automatically formatted according to the schema fields and data mapping you configure. Each batch of records will be sent as a JSON object containing the payload with schema and data arrays.
Batch mode is enabled for this endpoint. Records are automatically batched into groups of 10,000 records per request. If you need to add multiple users, you can send multiple records, and they will be automatically batched for efficient processing.
This endpoint automatically creates a data source to track the responses received from the Facebook Ads API after each call.
Custom Audience IDs can be obtained from the "Get Custom Audiences for an Ad Account" data source endpoint. The schema fields and data mapping must be properly configured to match Facebook API requirements. The endpoint requires System User Access Token authentication via the Authorization: Bearer {token} header, which is handled automatically by your credential configuration. The Content-Type: application/json header is automatically included in requests. Batch mode is enabled (batch.mode: true) with a batch size of 10,000 records. This endpoint automatically creates a data source (create.datasource: true) to track responses. For detailed information about adding users to custom audiences, including schema requirements and data formats, see the Facebook Marketing API documentation.
Delete Custom Audiences By Id
This endpoint deletes custom audiences from your Facebook account. Each record must contain an attribute whose value is equal to the Custom Audience Id. Note that this will wipe out any record with that Id, so make sure the values of the Id attribute are valid. Use this endpoint when you need to delete custom audiences from your Facebook Ads account from your data sources.
Enter the dataset attribute that corresponds to the Custom Audience ID that must be deleted in the Audience Id Dataset Attribute field. This should be the name of the attribute in your Nexset that contains the Custom Audience ID you want to delete.
Enter the Facebook Marketing API version in the Facebook API Version field. This is the API version to use for requests (e.g., v23.0). The default value is v23.0 if not specified.
The endpoint uses DELETE requests to https://graph.facebook.com/{api_version}/{audience_id} where {api_version} is the Facebook API Version and {audience_id} is the Custom Audience ID from the dataset attribute you specify. The endpoint URL is automatically constructed based on the Facebook Graph API base URL, the API version, and the audience ID from your Nexset data.
The endpoint sends data from your Nexset as the request body in JSON format. Each record in your Nexset will be sent as a JSON object containing any additional deletion data. The request body should follow the Facebook API specification for deleting custom audiences.
Batch mode is disabled by default for this endpoint. Each record in your Nexset will be sent as a separate API request to delete a custom audience. If you need to delete multiple audiences, you can send multiple records, but each will be processed as a separate request.
This endpoint automatically creates a data source to track the responses received from the Facebook Ads API after each call.
The Audience Id Dataset Attribute should match the name of the attribute in your Nexset that contains the Custom Audience ID. The endpoint uses the audience ID from your Nexset data to construct the URL path. The request body must be properly formatted JSON that matches the Facebook API specification for deleting custom audiences. The endpoint requires System User Access Token authentication via the Authorization: Bearer {token} header, which is handled automatically by your credential configuration. The Content-Type: application/json header is automatically included in requests. Batch mode is disabled by default (batch.mode: false), so each record will be sent as a separate request. This endpoint automatically creates a data source (create.datasource: true) to track responses. For detailed information about deleting custom audiences, see the Facebook Marketing API documentation.
Send Events to Pixel
This endpoint sends events to a Facebook Pixel ID using the Conversions API. Use this endpoint when you need to send conversion events or other events to your Facebook Pixel from your data sources.
Enter the Facebook Pixel ID to which you want to send events in the Pixel ID field. This is the Facebook Pixel ID you want to send events to.
Enter the Facebook Marketing API version in the Facebook API Version field. This is the API version to use for requests (e.g., v23.0). The default value is v23.0 if not specified.
The endpoint uses POST requests to https://graph.facebook.com/{api_version}/{pixel_id}/events where {api_version} is the Facebook API Version and {pixel_id} is the Pixel ID you provide. The endpoint URL is automatically constructed based on the Facebook Graph API base URL, the API version, and the pixel ID.
The endpoint sends data from your Nexset as the request body in JSON format. The request body is automatically formatted with a data array containing the events. Each record in your Nexset will be included in the data array.
Batch mode is enabled for this endpoint. Records are automatically batched into groups of 1,000 events per request. If you need to send multiple events, you can send multiple records, and they will be automatically batched for efficient processing.
Pixel IDs can be obtained from your Facebook Business Manager. The request body must be properly formatted JSON that matches the Facebook Conversions API specification. The endpoint requires System User Access Token authentication via the Authorization: Bearer {token} header, which is handled automatically by your credential configuration. The Content-Type: application/json header is automatically included in requests. Batch mode is enabled (batch.mode: true) with a batch size of 1,000 events. For detailed information about sending events to pixels, including event formats and requirements, see the Facebook Marketing API documentation.
Send Test Events to Pixel
This endpoint sends test events to a Facebook Pixel ID using the Conversions API. Use this endpoint when you need to send test conversion events or other test events to your Facebook Pixel from your data sources for testing purposes.
Enter the Facebook Pixel ID to which you want to send test events in the Pixel ID field. This is the Facebook Pixel ID you want to send test events to.
Enter the test event code in the Test Event Code field. This is the test event code provided by Facebook for testing events.
Enter the batch size for test events in the Batch Size field. This is the number of events to include in each batch. The default value is 1000 if not specified.
Enter the Facebook Marketing API version in the Facebook API Version field. This is the API version to use for requests (e.g., v23.0). The default value is v23.0 if not specified.
The endpoint uses POST requests to https://graph.facebook.com/{api_version}/{pixel_id}/events where {api_version} is the Facebook API Version and {pixel_id} is the Pixel ID you provide. The endpoint URL is automatically constructed based on the Facebook Graph API base URL, the API version, and the pixel ID.
The endpoint sends data from your Nexset as the request body in JSON format. The request body is automatically formatted with a test_event_code and a data array containing the events. Each record in your Nexset will be included in the data array.
Batch mode is enabled for this endpoint. Records are automatically batched according to the batch size you specify. If you need to send multiple test events, you can send multiple records, and they will be automatically batched for efficient processing.
Pixel IDs can be obtained from your Facebook Business Manager. Test event codes are provided by Facebook for testing purposes. The request body must be properly formatted JSON that matches the Facebook Conversions API specification. The endpoint requires System User Access Token authentication via the Authorization: Bearer {token} header, which is handled automatically by your credential configuration. The Content-Type: application/json header is automatically included in requests. Batch mode is enabled (batch.mode: true) with a configurable batch size. For detailed information about sending test events to pixels, including event formats and requirements, see the Facebook Marketing API documentation.
Facebook Ads destinations can also be manually configured to send data to any valid Facebook Ads API endpoint. Using manual configuration, you can also configure Nexla to automatically send the response received from the Facebook Ads API after each call to a new Nexla webhook data source. Select the Advanced tab at the top of the configuration screen, and follow the instructions in Connect to Any API to configure the API method, data format, endpoint URL, request headers, attribute exclusions, record batching, and response webhooks.
The Facebook Ads API base URL follows the pattern https://graph.facebook.com/{api_version}/{endpoint_path}, where {api_version} is the Facebook Marketing API version (e.g., v23.0). The Facebook Ads API primarily uses POST requests to create resources (e.g., adding users to custom audiences, sending events to pixels) and DELETE requests to remove data (e.g., deleting custom audiences), and typically expects JSON-formatted request bodies. You do not need to include the Authorization or Content-Type headers — Nexla automatically includes the System User Access Token as a Bearer token and sets Content-Type: application/json for JSON request bodies.
Once all endpoint settings have been configured, click the Done button in the upper right corner of the screen to save and create the destination. To send the data to the configured Facebook Ads endpoint, open the destination resource menu, and select Activate.
The Nexset data will not be sent to the Facebook Ads endpoint until the destination is activated. Destinations can be activated immediately or at a later time, providing full control over data movement.
