Facebook Custom Audiences

Empower your marketing team to run highly granular retargeting and lookalike campaigns on Facebook

Overview

Deliver even more relevant ads by combining data from various sources within your data warehouse to build custom audiences for Facebook Ads. By keeping your custom audiences updated automatically, never show an ad to someone after they purchase the item you were promoting.

Supported syncing

Sync Type	Description	Supported Sync Modes	API reference
Audiences	Create and update custom audiences in Facebook	Add, Remove	Custom Audiences docs

For more information about sync modes, refer to the sync modes docs.

Connect to Facebook Custom Audiences

Go to the Destinations overview page and click the Add destination button. Select Facebook Custom Audiences and click Continue. You can then authenticate Hightouch to Facebook Custom Audiences either with a system user token or with OAuth.

Since the OAuth flow requires you to manually refresh this connection every 60 days, we strongly recommend using a system user token for indefinite access.

Make sure to select an Ad Account on the destination configuration page. Otherwise, your sync fails with an 'undefined' does not exist error.

Authenticate with a system user token

When authenticating with a system user token you can choose to either use an existing one or create a new one for the Hightouch integration. To use an existing system user token, you must meet the following prerequisites:

The system user whose token you'd like to use has Admin access.
You've created an app to add as an assigned asset to the system user. For detailed instructions, see steps 1 - 3 from creating a new system user token.
You've assigned the ad account that you want to create audiences for to the system user. For detailed instructions, see step 5 from creating a new system user token.

If you haven't met these prerequisites, follow the instructions for creating a new system user token.

Create a new system user token

To create a new token, you first need to add a new app.

Open your Facebook Business account and navigate to Business Settings > Accounts > Apps.

Screenshot of the Facebook Business account UI

Use type None, name your app, then click Create app.

Make sure the app has Ads Management Standard Access permissions. You can find this setting in App Review > Permissions and Features.

Navigate to Business Settings > Users > System users and add a new system user with Admin access.

Use the Add assets button to assign both the app you created and the ad account that you want to create audiences for to the system user. Be sure to give both the app and the ad account Full Control, not Partial Access.

Once a new system user account is created, select Generate new token. When prompted, select the relevant app and the ads_management permission, then click Generate token.

Copy the generated token. Since this token won't be stored in Facebook, you may want to consider storing it in a secure password vault as well.

Back in Hightouch, select Use system user token as the Authentication method, then paste the token you generated as the System User Token, select the relevant Ads Account, and click Continue.

Use an existing system user token

If you already have a Facebook app and system user setup, open your Facebook Business account and navigate to Business Settings > Users > System users.

Select the system user you'd like to generate a new token for.
Select Generate new token. When prompted, select the relevant app and the ads_management permission, then click Generate token.

Copy the generated token. Since this token won't be stored in Facebook, you may want to consider storing it in a secure password vault as well.

Back in Hightouch, select Use system user token as the Authentication method, then paste the token you generated as the System User Token, select the relevant Ads Account, and click Continue.

Authenticate with OAuth

For the Authentication method, select Log in to Facebook and log into your Facebook account.

Once successful, you will be redirected back to Hightouch to enter a descriptive name for your destination and complete setup.

Sync configuration

Once you've set up your Facebook Custom Audiences destination and have a model to pull data from, you can set up your sync configuration to begin syncing data. Go to the Syncs overview page and click the Add sync button to begin. Then, select the relevant model and the Facebook Custom Audiences destination you want to sync to.

Syncing custom audiences

Hightouch lets you create and maintain custom audiences via the Facebook Custom Audience API. Each sync adds new users and updates existing users' identifiers you include in record matching. You can remove users that leave your model's query result by selecting this option in the sync's delete behavior.

Select an existing audience or create a new one

You can create a new audience or use an existing one. When creating a new audience, you can optionally enter a name; otherwise, Hightouch defaults to the name of the associated model. To use an existing audience, select the desired audience from the dropdown.

User identifiers

To identify which users to add or update in an audience, select model columns and the corresponding Facebook Custom Audience fields. You can match on default, custom, and Facebook-specific fields.

Facebook-specific fields include:

External ID: a custom identifier that you send to Facebook via its APIs or tracking pixels
Page-scoped ID: an ID used for Facebook messenger apps and Facebook pages

To increase the match rate for your records, include as many fields as possible.

Increase match rates in Facebook Custom Audiences by enabling Match Booster.

Value-based audiences

If you're creating a new Facebook Audience, you can create a value-based audience by mapping a numerical model column containing lifetime values to the Lookalike Value field.

Screenshot of Lookalike Value field mapping

You can then create a lookalike audience in Facebook that finds the people most similar to your highest value customers. For more information refer to Facebook's docs.

Handling PII and hashing

By default, Hightouch automatically hashes the following fields before sending requests to Facebook:

Email
Phone
Gender
First Name
Last Name
First Initial
State
City
Zip Code
Country

You can disable this behavior in the sync configuration. If disabled, the data from the model should be appropriately normalized and hashed according to Facebook's hashing requirements.

Optionally share this audience with another Facebook advertising account.

Delete behavior

You can choose how to handle user records in Facebook when the corresponding rows are deleted in your source.

Behavior	Description
Do nothing	Keep the contact in your Facebook Custom Audience
Remove from list	Remove the contact from your Facebook Custom Audience

Tips and troubleshooting

Matched users count

Hightouch retrieves the audience metadata from Facebook in real-time. The matched number displayed in Hightouch should reflect what you see in Facebook. Note that the matched numbers are approximated to maintain privacy thresholds. Hightouch takes the matched count to calculate a match rate for your sync, where applicable. The calculation breakdown:

matched_user_count / # of rows queried in the latest sync run

The match rate is

not

calculated when:

syncing to an existing segment because the total number of records to ever be uploaded to the segment is unknown
removed users from your model is not removed in Facebook because the matched user count would be inflated in the calculation

Common causes for low match rates:

Your audience model is too small. Most ad platforms do not display the matched number unless there's at least one thousand matched users to maintain privacy thresholds.
The upload is still processing. We recommend waiting at least
72 hours
from the first sync run for numbers to settle.
Your data isn’t cleaned or hashed properly. Hightouch normalizes and hashes your data according to destination requirements, but it’s still good to make sure that the data is as clean as possible. Note that Hightouch cannot clean your data if you opt to hash it yourself. In that case, ensure you follow the data cleaning requirements forFacebook.

Facebook returns 1k as the default when there is no data or audience is too small

Common errors

If you encounter an error or question not listed below and need assistance, don't hesitate to . We're here to help.

Custom Audience Terms not yet accepted

The full error message is:

An error occurred when creating the audience. Facebook Custom Audiences API returned error with code 400: Custom Audience Terms not yet accepted: You'll need to agree to the Custom Audience terms before you can create or edit an audience or an ad set. See Facebook, Custom Audience Terms.

To resolve this error, go to Audiences in your Facebook Ads Manger account and click Create a Custom Audience to create a list a manually. This prompts the Terms of Service to appear so you can agree to them.

You can also go to https://business.facebook.com/ads/manage/customaudiences/tos/?{ACCOUNT_ID} to accept the Terms of Service for each ad account that you want to use. Replace {ACCOUNT_ID} with the ad account ID in act_xxxx format.

Once you've accepted the Terms of Service, rerun your sync with the error.

Error Code 400: Missing schema attribute in payloads

By default, Hightouch automatically hashes certain fields before sending them to Facebook. The error occurs when Hightouch attemps to hash a null value or null values are being sent to Facebook.

To resolve this, remove rows containing null values from your model's query results or enable the Don't sync null values option in the advanced mapper.

Unsupported post request. Object with ID 'undefined' does not exist

This error occurs if you don't select an Ad Account on the destination configuration page. Make sure to follow the destination setup procedure outlined in the Connect to Facebook Custom Audiences section.

401 - Error validating access token

As explained in the Connect to Facebook Custom Audiences section, authenticating with OAuth requires you to reauthorize your destination every 60 days. Otherwise, your syncs fail with this error message.

Authenticate with a system user token to avoid this reauthorization requirement.

400 - (#100) unsupported get request

The full error may look like: 400 - {"error":("message":"(#100) Unsupported get request. Please read the Graph API documentation at https://developers.facebook.com/docs/graph-api {...}.

This error usually happens when one or multiple Facebook pages that were granted access to the system user have age restrictions or country restrictions enabled. To resolve the error, edit your system user to remove all pages that have these age or country restrictions. Otherwise, you can edit the page settings to remove the restrictions from these pages.

Live debugger

Hightouch provides complete visibility into the API calls made during each of your sync runs. We recommend reading our article on debugging tips and tricks to learn more.

Sync alerts

Hightouch can alert you of sync issues via Slack, PagerDuty, SMS, or email. For details, please visit our article on alerting.