Meta Custom Audiences

Sync first-party audiences to Meta Ads Manager for better targeting, lookalikes, and suppression across your campaigns.

View Meta Custom Audiences's documentation and status page.

Overview

Deliver even more relevant ads by combining data from various sources within your data warehouse to build custom audiences for Meta 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 Meta	Add, Remove	Custom Audiences docs

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

Connect to Meta Custom Audiences

Go to the Destinations overview page and click the Add destination button. Select Meta Custom Audiences and click Continue. You can then authenticate Hightouch to Meta 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 - 7 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 9 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 Meta Business account and navigate to Business Settings > Accounts > Apps. Click Add.

Screenshot of the Facebook Business account UI

Choose Create a new app ID.

Name your app.

Select the use case as Other.

Set the app type to Business.

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 and assets are assigned, select Generate token.

Choose the app you created to generate the token.
Select the expiration policy for the token.

Ensure that the ads_management permission is selected, then click Generate token.

Copy the generated token. Since this token won't be stored in Meta, 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 Meta app and system user setup, open your Meta Business account and navigate to Business Settings > Users > System users.

Once you've selected the existing user and assets are assigned, select Generate token.

Choose the app you created to generate the token.
Select the expiration policy for the token.

Ensure that the ads_management permission is selected, 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 Meta and log into your Meta 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 Meta 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 Meta Custom Audiences destination you want to sync to.

Syncing custom audiences

Hightouch lets you create and maintain custom audiences via the Meta 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 Meta Custom Audience fields. You can match on default, custom, and Meta-specific fields.

Meta-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 Meta messenger apps and Meta 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 Meta 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 Meta that finds the people most similar to your highest value customers. For more information refer to Meta's docs.

Handling PII and hashing

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

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 Meta's hashing requirements.

Optionally share this audience with another Meta advertising account.

Delete behavior

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

Behavior	Description
Do nothing	Keep the contact in your Meta Custom Audience
Remove from list	Remove the contact from your Meta 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.

Meta 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. Meta 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 Meta, Custom Audience Terms.

To resolve this error, go to Audiences in your Meta Ads Manager 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 Meta. The error occurs when Hightouch attemps to hash a null value or null values are being sent to Meta.

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 Meta Custom Audiences section.

401 - Error validating access token

As explained in the Connect to Meta 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 Meta 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.