Skip to main content

Facebook Ads Destination

Nexla's bi-directional connectors allow data to flow both to and from any location, making it simple to create a sync or streaming data flow that sends data to a Facebook Ads location.
fb_ads_api.png

Facebook Ads

Create a Facebook Ads Destination​

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

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

  3. In Nexla, Facebook Ads destinations can be created using pre-built endpoint templates, which expedite destination setup for common Facebook Ads endpoints. Each template is designed specifically for the corresponding Facebook Ads endpoint, making destination configuration easy and efficient.
    • To configure this destination using a template, follow the instructions in Configure Using a Template.

    Facebook Ads destinations can also be configured manually, allowing you to send data to Facebook Ads endpoints not included in the pre-built templates or apply further customizations to exactly suit your needs.
    • To configure this destination manually, follow the instructions in Configure Manually.

Configure Using a Template​

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.

  • To configure this destination using a template, 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.

Configure Manually​

Facebook Ads destinations can be manually configured to send data to any valid Facebook Ads API endpoint. Manual configuration provides maximum flexibility for accessing endpoints not covered by pre-built templates or when you need custom API configurations.

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.

API Method​

  1. To manually configure this destination, select the Advanced tab at the top of the configuration screen.

  2. Select the API method that will be used for calls to the Facebook Ads API from the Method pulldown menu. The Facebook Ads API primarily uses POST and DELETE requests for data writing operations. The most common methods are:

    • POST: For creating new resources or performing actions (e.g., adding users to custom audiences, sending events to pixels)
    • DELETE: For removing data (e.g., deleting custom audiences)
    • PUT: For updating existing data
    • PATCH: For partial updates to existing data

Data Format​

  1. Select the format in which the Nexset data will be sent to the Facebook Ads API from the Content Format pulldown menu. Nexla will automatically convert the data to the selected format for each API call. The Facebook Ads API typically uses JSON format for request bodies.

API Endpoint URL​

  1. Enter the URL of the Facebook Ads API endpoint to which you want to send the Nexset data in the URL field. This should be the complete URL including the protocol (https://) and any required path parameters. Facebook Ads API endpoints typically follow the pattern https://graph.facebook.com/{api_version}/{endpoint_path} where {api_version} is the Facebook Marketing API version (e.g., v23.0).

Ensure the API endpoint URL is correct and accessible with your current credentials. You can test the endpoint using the Test button after configuring the URL. The endpoint requires System User Access Token authentication via the Authorization: Bearer {token} header, which is handled automatically by your credential configuration. For detailed information about Facebook Ads API endpoints and available APIs, see the Facebook Marketing API documentation.

Request Headers​

Optional

  • If Nexla should include any additional request headers in API calls to this destination, enter the headers & corresponding values as comma-separated pairs in the Request Headers field (e.g., header1:value1,header2:value2). Additional headers are often required for API versioning, content type specifications, or custom authentication requirements.

    You do not need to include any headers already present in the credentials. Common headers like Authorization, Content-Type, and Accept are typically handled automatically by Nexla based on your credential configuration. The Facebook Ads API 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 typically set automatically for JSON request bodies.

Request Body​

Optional

  • If the API endpoint requires a specific request body format, configure how Nexla should format the request body from your Nexset data. The request body can be sent as JSON, XML, or form data, depending on the API endpoint requirements.

    • For JSON format, select JSON from the Request Body Format dropdown, and the Nexset data will be sent as a JSON object in the request body. Facebook Ads API endpoints typically use JSON format for request bodies.

    • For XML format, select XML from the Request Body Format dropdown, and the Nexset data will be converted to XML format in the request body.

    • For Form data format, select Form Data from the Request Body Format dropdown, and the Nexset data will be sent as form-encoded data in the request body.

Save the Destination​

  1. Once all configuration steps have been completed, click the Save button to save your destination configuration.

  2. The destination will now be available in your data flow and will begin sending data to the Facebook Ads endpoint according to the configured settings.