# Connect Reverse ETL Source to Facebook Custom Audience


This guide takes you through the steps to connect a [Reverse ETL source]({{< ref "sources/reverse-etl/" >}}) to your Facebook Custom Audience destination.

{{< success >}}
You can connect multiple Reverse ETL sources to the Facebook Custom Audience destination.
{{< /success >}}

##  Setup

1. Set up and configure your Reverse ETL source.
2. In the **Overview** tab of the source page, click **Add destination** > **Create new destination**. You can also select an already-configured destination here.
3. From the list of destinations, select **Facebook Custom Audience** and click **Continue**.
4. Specify a unique name to identify this destination in RudderStack.
5. 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 | <div style="width: 350px;">Description</div> |
| :----| :-----|
| Account Name | Specify a unique Custom Audience account name |
| Access Token | Enter the [access token](#where-can-i-find-the-user-access-token-for-the-application) of your business application set up for accessing the Facebook Marketing API |
| App Secret | This field is **optional**. Enter the [app secret](https://developers.facebook.com/docs/facebook-login/security/#appsecret) from the **Basic app settings** page of your [Facebook Developer account](https://developers.facebook.com/) |

6. The **Ad Account ID** field is automatically populated based on the selected Facebook Ads account — select the relevant ID from the dropdown. Then, click **Continue**.

## Mapping settings

This section lists the settings to correctly map data from your Reverse ETL source to the Facebook Custom Audience destination.

{{< info >}}
RudderStack supports syncing to the following two audience types:

- [Custom Audiences](https://developers.facebook.com/docs/marketing-api/audiences/guides/custom-audiences)
- [Value-based lookalike audiences](https://en-gb.facebook.com/business/help/917879191754763?id=401668390442328) — see [Create new value-based lookalike audiences](#create-new-audience) section for more information.
{{< /info >}}

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

{{< info >}}
If you select the **Create new audience** option, RudderStack creates a new audience in Facebook with the same **Ad Account ID** configured in the [connection settings](#setup).
{{< /info >}}

- **Use existing audience**: Use this option if you have an existing custom audience. RudderStack automatically populates this field with the relevant audiences based on your specified [connection settings](#setup).

### Sync mode

RudderStack supports only [Mirror mode]({{< ref "data-pipelines/reverse-etl/developer-guides/sync-modes.md#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.

{{< image src="images/audiences/destinations/fb-custom-audience/identifier-mapping.webp" >}}

### Advanced settings

| Setting | <div style="width: 350px;">Description</div> |
| :----| :-----|
| Automatically hash PII data | When set to **Yes**, RudderStack hash-encodes user data irrespective of whether the data is already hashed or not. <br /><br />**Note**:  Facebook expects the user data to be hash encoded using `SHA256`. <br /><br />See [Data hashing](#data-hashing) section for more information. |
| Normalize data formatting | When set to **Yes**, RudderStack automatically cleans and standardizes the audience data, like emails and phone numbers. <br /><br />See [Data normalization](#data-normalization) section for more information. |
| Specify where your data originates from | Select the relevant field from the dropdown that describes the origin of your data — this helps Facebook classify the user list and apply appropriate matching and privacy rules. | 
| Specify identifier type | Choose the relevant identifier type from the dropdown that allows Facebook Ads to match users to their profiles. | 

## Sync settings

{{< customreadfile "/includes/retl/schedule-syncs.md" >}}

#### Sync observability settings

{{< customreadfile "/includes/retl/sync-observability-settings.md" >}}

## 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](https://en-gb.facebook.com/business/help/917879191754763?id=401668390442328), map a relevant warehouse column to the **Lookalike Value** field in the [Identifier mappings](#map-identifiers):

1. In the [Select audience](#select-audience) section, select **Create new audience** and specify the audience name and description.
2. In the **Choose identifier mappings** window, map a relevant warehouse column to the **Lookalike Value** field.

{{< info >}}
Note that:

- RudderStack will not create a value-based lookalike audience if you do not include the **Lookalike Value** in your identifier mappings — it will create a [custom audience](https://developers.facebook.com/docs/marketing-api/audiences/guides/custom-audiences) instead.
- You can update the mapping for the **Lookalike Value** field after the audience is created.
{{< /info >}}

{{< image src="images/audiences/destinations/fb-custom-audience/lookalike-value-mapping.webp" >}}

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

#### Existing value-based lookalike audience

1. In the [Select audience](#select-audience) section, select **Use existing audience** and select the value-based lookalike audience from the dropdown.
2. In the **Choose identifier mappings** window, map a relevant warehouse column to the **Lookalike Value** field.

{{< info >}}
You can update the mapping for the **Lookalike Value** field after the audience is created.
{{< /info >}}

{{< image src="images/event-stream-destinations/existing-audience-lookalike-value.webp" >}}

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

{{< warning >}}
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.
{{< /warning >}}

## Schema fields mapping

The following table details the schema fields mappings specified in the RudderStack dashboard:

| Dashboard field name | Marketing API schema field (RudderStack-supported field name) | 
| :-------------- | :------------ | 
| `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.

{{< warning >}}
RudderStack modifies the schema names visible in the dashboard to ensure better 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.
{{< /warning >}}

## Data normalization

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

| 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](#advanced-settings) setting, RudderStack formats the user data as prescribed by the Facebook Marketing API.

After normalization, RudderStack validates each field before sending it to Facebook. 

- If a field is determined to be invalid, RudderStack **does not** send it to Facebook.
- If all fields in a row are invalid, then the entire row is rejected and marked as failed

{{< info >}}
RudderStack first normalizes the data and then validates it, skipping any invalid rows. Then, it [hashes the data](#data-hashing) before sending it to Facebook.
{{< /info >}}

## Data hashing

The [Automatically hash PII data](#advanced-settings) 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

{{< warning >}}
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.
{{< /warning >}}

RudderStack rejects such events with a clear error message, for example:

```text
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 were effectively resulting in no matches, helping you quickly identify and fix any data quality or configuration issues.

## FAQ

#### Where can I find the Custom Audience ID?

1. To get your Custom Audience ID, go to the Facebook Ads Manager account. On the left navigation bar, select **Audiences** and choose the Ad account you have created the custom audience for.

{{< image src="images/event-stream-destinations/fb-custom-audience-id-1.webp" alt="Customer audience ID" >}}

2. Click **All Audiences** and select the specific custom audience from the list.
3. Finally, click the **History** tab. Here, you will find the audience ID under the **Item Changed** column:

{{< image src="images/event-stream-destinations/fb-custom-audience-id-2.webp" alt="Customer audience ID" >}}

#### What are the prerequisites for creating an audience list?

Before creating a new audience list, make sure that:

- You are an [admin system user](https://en-gb.facebook.com/business/help/327596604689624?id=2190812977867143). To check, go to **Users** > **System users** in your [Facebook business](https://business.facebook.com/) account.

{{< image src="images/event-stream-destinations/fb-system-user.webp" alt="Facebook Ads system user" >}}

- The ad account under which the audience list is created should be added as an asset for the system user, with manage permissions.
- The app for which you are [creating the access token](#where-can-i-find-the-user-access-token-for-the-application) should be added as an [asset of the system user](#how-do-i-add-an-app-as-a-system-user-asset-with-manage-permissions) with full control.

#### How do I add an app as a system user asset with manage permissions?

1. Log in to your [Facebook Business Manager](https://business.facebook.com/) account.
2. Click **Business settings**.

{{< image src="images/event-stream-destinations/fb-custom-audience-business-settings.webp" alt="Business Settings" >}}

3. Under **Users**, click **System users**.

{{< image src="images/event-stream-destinations/fb-custom-audience-system-users.webp" alt="System users setting" >}}

4. Choose the system user from the opened list.
5. Click **Add Assets** for the above user.

{{< image src="images/event-stream-destinations/fb-custom-audience-add-assets.webp" alt="Add Assets option" >}}

6. Under **Select asset type**, click **Apps** and choose your app from the **Select assets** tab.

{{< image src="images/event-stream-destinations/fb-custom-audience-asset-type.webp" alt="Asset type" >}}

7. In the right-most **App** tab, enable the **Manage app** setting. Then, click **Save Changes**.

{{< image src="images/event-stream-destinations/fb-custom-audience-manage-app.webp" alt="Manage app setting" >}}

#### How do I create a new audience list?

1. Log in to your [Facebook business](https://business.facebook.com/) account.
2. Click **All tools** in the left panel.

{{< image src="images/event-stream-destinations/fb-custom-audience-2.webp" alt="Facebook custom audience creation" >}}

3. Hover over **Create Audience** and select **Custom Audience**.

{{< image src="images/event-stream-destinations/fb-custom-audience-3.webp" alt="Facebook custom audience creation" >}}

4. Select **Customer List** and click **Next**.

{{< image src="images/event-stream-destinations/fb-custom-audience-4.webp" alt="Facebook custom audience creation" >}}

5. Prepare your customer list by selecting and mapping the identifiers. Make sure you have enough identifiers before uploading the list.

{{< image src="images/event-stream-destinations/fb-custom-audience-5.webp" alt="Facebook custom audience creation" >}}

6. Upload the CSV file you want to use for your new custom audience. Under the **Does your list include a column for customer value?** setting, make sure to select **No, continue with a customer list that doesn't include customer value**.

{{< info >}}
You can also download the file template CSV and upload it.
{{< /info >}}

{{< image src="images/event-stream-destinations/fb-custom-audience-add-customer-list.webp" alt="Facebook custom audience add customer list" >}}

7. Finally, click **Import and create** to create the audience.

{{< warning >}}
The custom audience you create should have [edit permissions](#how-do-i-check-if-the-custom-audience-has-edit-permissions). Otherwise, RudderStack will not be able to add or remove users from the list. 
{{< /warning >}}

#### How do I check if the custom audience has edit permissions?

To check if the audience has edit permissions enabled, go to the **Audiences** tab, select your custom audience, and check the **Actions** dropdown. You should see the **Edit** option as seen below:

{{< image src="images/event-stream-destinations/fb-custom-audience-edit-permissions.webp" alt="Customer audience edit permissions" >}}

#### How do I obtain the Ad Account ID?

Go to your Facebook [Ads Manager account](https://www.facebook.com/adsmanager/manage/) where you can find the Ad Account ID in the account's drop-down menu:

{{< image src="images/event-stream-destinations/ads-account-id-fb.webp" alt="Audience source" >}} 

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?

{{< warning >}}
To generate the user access token for your application, you must first [add it as a system user asset](#how-do-i-add-an-app-as-a-system-user-asset-with-manage-permissions) with manage permissions.
{{< /warning >}}

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

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

{{< image src="images/event-stream-destinations/fb-custom-audience-generate-new-token.webp" alt="Generate new token" >}}

{{< image src="images/event-stream-destinations/fb-custom-audience-token-select-app.webp" alt="Select app for the token" >}}

2. Choose the **Token expiration** time.

{{< image src="images/event-stream-destinations/fb-custom-audience-token-settings.webp" alt="Token settings" >}}

3. Under **Available permissions**, select `ads_read` and `ads_management`.

{{< image src="images/event-stream-destinations/fb-custom-audience-available-permissions-1.webp" alt="Token permissions" >}}
{{< image src="images/event-stream-destinations/fb-custom-audience-available-permissions-2.webp" alt="Token permissions" >}}

4. Click the **Generate Token** button and copy the token credentials.

#### Should I use `sessionIdAdd` or `sessionIdDelete` before adding or removing users in Custom Audience?

`sessionIdAdd` and `sessionIdDelete` helps you track and use a particular session ID while adding or removing users. This is useful when you are sending data in chunks. If you do not include these fields, Facebook creates a session ID itself.

See the [Facebook documentation](https://developers.facebook.com/docs/marketing-api/audiences/guides/custom-audiences#step-2--specify-a-list-of-users) for more information.

#### 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

{{< info >}}
Facebook does not allow mixing data source types within the same custom audience.
{{< /info >}}

<br />