# Sync Audiences to Facebook Custom Audience

This guide lists the steps to configure Facebook Custom Audience as a destination in RudderStack and sync the created audiences to it.

Setup

Set up an audience in RudderStack using the Audience Builder.
Go to the Syncs tab of the audience page and click Add sync. Then, select Facebook Custom Audience.
Click New destination — you can also select an already-configured destination here.
Specify a unique name to identify this destination in RudderStack.
In the Event delivery account section, click Select to choose from an existing Facebook Ads account from the list. You can also click Add account and authenticate using a Facebook API access token:

Setting	Description
Account Name	Specify a unique Custom Audience account name
Access Token	Enter the access token of your business application set up for accessing the Facebook Marketing API
App Secret	This field is optional. Enter the app secret from the Basic app settings page of your Facebook Developer account

The Ad Account ID field is pre-populated based on the selected Facebook Ads account — select the ID.

Configure sync

This section lists the settings to correctly configure your audience syncs to the Facebook Custom Audience destination.

The following two audience types are supported:

Custom Audiences

Value-based lookalike audiences — see Create new value-based lookalike audiences section for more information.

Select audience

In this section, you can create a new audience or use an existing one.

Create new audience: Use this option to create a new custom audience in Facebook. You can specify the name and description of the new Facebook audience.

If you select Create new audience, a new audience is created in Facebook with the same Ad Account ID configured in the connection settings.

Use existing audience: Select an existing custom audience. This field is populated based on your connection settings.

Sync mode

RudderStack supports only Mirror mode for this integration.

Map identifiers

In this section, you can map your warehouse columns to specific Custom Audience fields that represent your audience’s identity.

Advanced settings

Setting	Description
Automatically hash PII data	When set to Yes, user data is hash-encoded irrespective of whether the data is already hashed or not. Note: Facebook expects the user data to be hash encoded using `SHA256`. See Data hashing section for more information.
Normalize data formatting	When set to Yes, Facebook automatically cleans and standardizes the audience data, like emails and phone numbers. See Data normalization section for more information.
Specify where your data originates from	Select the field that describes the origin of your data — this helps Facebook classify the user list and apply matching and privacy rules.
Specify identifier type	Choose the identifier type that Facebook Ads uses to match users to their profiles.

Sync settings

Two options are available to schedule your audience syncs:

Run syncs automatically based on a specified frequency (every 5 minutes, 10 minutes, 15 minutes, 30 minutes, 1 hour, 3 hours, 6 hours, 12 hours, or 24 hours) and a specific time (in UTC).
Run syncs manually — trigger a sync from the sync details page. You will need to run the sync each time.

Sync observability settings

Setting

Description

Retain sync logs

This setting is toggled on by default and instructs RudderStack to store the sync logs in your warehouse. You can also configure the below settings:

Setting	Description
Sync log retention	Specify the retention period of the sync logs in your warehouse. If you set it to 1, then RudderStack deletes any sync log older than a day (in UTC time).
Snapshot table retention	Specify the number of snapshot tables to retain.

Retry failed records

This setting is toggled on by default and causes RudderStack to continually retry sending the failed records.

Retain and show failures

This setting is toggled off by default. Turn it on to have RudderStack write the error recorded for every failed record to a failed records table in your warehouse and show it in the sync’s failed records view. It applies from the next sync and can take up to a minute to reach your data plane.

Setting	Description
Failure retention	Number of days RudderStack keeps each sync’s failed records in your warehouse. The default is 30 and the minimum is 7.

Storing sync logs, snapshot tables, and failed records may incur additional warehouse costs.

Enable sync

Once the setup is complete, enable the sync.

Manage value-based lookalike audiences

This section describes the steps to map your warehouse data to a new or existing value-based lookalike audience.

New audience

To create a new value-based lookalike audience, map a warehouse column to the Lookalike Value field in the Identifier mappings:

In the Select audience section, select Create new audience and specify the audience name and description.
In the Choose identifier mappings window, map a warehouse column to the Lookalike Value field.

Note that:

A value-based lookalike audience is not created if you do not include the Lookalike Value in your identifier mappings — a custom audience is created instead.

You can update the mapping for the Lookalike Value field after the audience is created.

Set up the other identifier mappings as per your requirement.
Continue with the rest of the setup.

Existing value-based lookalike audience

In the Select audience section, select Use existing audience and select the value-based lookalike audience from the dropdown.
In the Choose identifier mappings window, map a warehouse column to the Lookalike Value field.

You can update the mapping for the Lookalike Value field after the audience is created.

Set up the other identifier mappings as per your requirement.
Continue with the rest of the setup.

You cannot change the audience type from a value-based lookalike audience to a regular custom audience (and vice versa) after the audience is created.

Schema fields mapping

The following table details the schema field mappings specified in the dashboard:

Dashboard field name	Marketing API schema field
`EMAIL`	`EMAIL`
`PHONE`	`PHONE`
`GENDER`	`GEN`
`MADID`	`MADID`
`EXTERN_ID`	`EXTERN_ID`
`DOB YEAR (YYYY)`	`DOBY`
`DOB MONTH (MM)`	`DOBM`
`DOB DATE (DD)`	`DOBD`
`LAST NAME`	`LN`
`FIRST NAME`	`FN`
`FIRST NAME INITIAL`	`FI`
`CITY`	`CT`
`US STATES`	`ST`
`ZIP`	`ZIP`
`COUNTRY`	`COUNTRY`

Note that the MADID and EXTERN_ID fields are not hashed.

RudderStack modifies the schema names visible in the dashboard for readability. However, during the event call, the field names must be exactly the same as the schema names specified by Facebook Marketing API, as mentioned in the table above.

Data normalization

By default, RudderStack formats the data as prescribed by Facebook before sending it to the destination:

Schema field name	Example input	Formatted output (before hashing)
`EMAIL`	`ABC@gmail.com`	`abc@gmail.com`
`PHONE`	`0@96346895`	`96346895`
`GEN`	`FEMALE`	`f`
`DOBD`	`2`	`02`
`DOBM`	`1`	`01`
`LN & FN`	`Abc,@`	`abc@`
`FI`	`Mr.`	`mr.`
`CT`	`HN#`	`hn`
`ST`	`? AL ?`	`al`
`ZIP`	`11502 @bc`	`11502@bc`
`COUNTRY`	`IN`	`in`

If you enable the Normalize data formatting setting, user data is formatted as prescribed by the Facebook Marketing API.

After normalization, each field is validated before sending it to Facebook.

Invalid fields are not sent to Facebook.
If all fields in a row are invalid, then the entire row is rejected and marked as failed

Data is first normalized, then validated (skipping invalid rows), then hashed before sending to Facebook.

Data hashing

The Automatically hash PII data setting lets you hash your user data before sending it to Facebook. This setting is enabled by default.

Configure the setting to Yes if your incoming data is not pre-hashed
Configure this setting to No if your data is already hashed

Incorrect configuration of the Automatically hash PII data setting will result in failures.

If the Automatically hash PII data setting is configured to Yes and your data is pre-hashed, the event will fail.

If the Automatically hash PII data setting is configured to No and your data is not pre-hashed, the event will fail.

Such events are rejected with a clear error message, for example:

Hashing is disabled but the value for field EMAIL appears to be unhashed. Either enable hashing or send pre-hashed data.

You will also see errors in the Events tab for cases that were previously marked as successful but resulted in no matches, helping you identify and fix data quality or configuration issues.

FAQ

Where can I find the Ad Account ID?

Go to your Facebook Ads Manager account where you can find the Ad Account ID in the account’s drop-down menu:

You can click on See More Ad Accounts if the required Ad account is not visible.

Where can I find the user Access Token for the application?

To generate the user access token for your application, you must first add it as a system user asset with manage permissions.

Follow these steps to generate a user access token required to use the Facebook Marketing API:

Under the system user, click the Generate New Token button and select the app from the dropdown.

Choose the Token expiration time.

Under Available permissions, select ads_read and ads_management.

Click the Generate Token button and copy the token credentials.

Why am I seeing the error “Failed to update the custom audience. Facebook responded with error code: 2650?

This error is not explicitly documented by Facebook but is a known API-level limitation. Error 2650 typically occurs when attempting to add users to a custom audience that was created using a different data source.

For example:

Audience originally created via manual file upload
Audience created through another platform or integration

Facebook does not allow mixing data source types within the same custom audience.