Facebook Ads (Meta)

Upload Custom Audiences to Meta Ads for targeted advertising on Facebook and Instagram. Zeotap syncs your warehouse segments directly to Facebook Custom Audiences, keeping your ad targeting in sync with your customer data.

Prerequisites

• A Meta Business Manager account
• A Facebook Ad Account with Custom Audience permissions
• Your Ad Account ID (numeric, without the act_ prefix)
• For system user tokens: a system user created in Business Manager with the ad account assigned
• For OAuth: a Meta app with ads_management and ads_read permissions

Permissions

Your Meta app or system user must have the following permissions:

The user or system user must have Advertiser or Admin role on the target Ad Account. Assign roles in Business Manager > Business Settings > Ad Accounts > People/Partners.

Authentication

Zeotap supports two authentication methods for Facebook Ads. System user tokens are recommended for production because they can be set to never expire and are not tied to a personal Facebook account.

OAuth 2.0

1. Click Connect with OAuth in Zeotap
2. Sign in with your Facebook Business account
3. Authorize the requested permissions (ads_management, ads_read)

OAuth tokens are valid for 60 days. Zeotap refreshes them automatically, but if the token is not used for 60 days, you will need to re-authenticate.

System User Token (Recommended)

System user tokens are long-lived access tokens created in Meta Business Manager. They are not tied to a personal Facebook account, making them ideal for production integrations.

1. Go to Meta Business Manager  and click Business Settings (gear icon)
2. In the left sidebar, navigate to Users > System Users
3. Click Add to create a new system user, or select an existing one
4. Set the system user role to Admin
5. Click Add Assets, select Ad Accounts, choose your target ad account, and grant Full Control
6. If you have an existing Meta app, click Add Assets, select Apps, and assign the app to the system user
7. Click Generate New Token
8. Select the app you assigned in step 6
9. Under token expiration, select Never for production use (or set a specific expiry)
10. Check the ads_management permission (and ads_read if listed)
11. Click Generate Token
12. Copy the token immediately — it will not be shown again
13. In Zeotap, select the System User Token tab when creating the destination
14. Paste the token into the Access Token field

Note: If you do not have a Meta app yet, create one at developers.facebook.com  > My Apps > Create App. Select Other as the use case and Business as the app type. Then return to Business Manager to assign it to your system user.

Configuration

Target Settings

Per-row Custom Audiences

Audience Name can be taken from a column instead of being fixed for the sync, so one sync fans out across several Custom Audiences.

To set it up, open the sync’s Destination Configuration, switch the field from Fixed value to From column, and pick the column. The switch adds a row to the sync’s field mapping, so you can also see and edit the binding — including adding a transform — in the Map fields editor. The fixed value you leave behind becomes the fallback applied to rows whose column is empty.

Zeotap groups each batch by the resolved name and calls the users endpoint once per distinct audience, reusing an existing audience of that name on the ad account or creating it on first sight.

Limiting how many Custom Audiences a run can create

Because a new Audience Name creates a Custom Audience, binding a high-cardinality column by mistake — a user id, say — would create one per profile. Max distinct values per run (default 500) caps this: if a run needs to create more than the limit allows, it fails with an error naming the field and the offending value, and nothing further is created. Set it to 0 for no limit.

Mirror mode cannot express a move. A profile that moves from one Custom Audience to another appears in the diff as a changed row carrying only its current value, so it is added to the new one but never removed from the old. Prefer Add and Remove sync modes when Audience Name comes from a column.

Supported Operations

Sync Modes

Audience Sync Modes

Features

• Field Mapping: Yes
• Schema Introspection: No
• Auto-Create Audiences: Yes — provide an Audience Name without an Audience ID; the audience is created only if none with that name exists
• Audience Boost: Yes — email and phone

Required Mapping Fields

Default Destination Fields

Raw Identifiers (auto-hashed by Zeotap)

email, phone

Pre-Hashed Identifiers (validated and passed through)

hashed_email, hashed_phone

Zeotap Custom Audience uploads match on email and phone (EMAIL_SHA256/PHONE_SHA256). Additional multi-key schema columns (first/last name, city, ZIP, mobile advertiser ID, …) are not yet part of the upload.

Each hashed_* field takes a SHA-256 hex digest (64 characters) of the normalized value — for email, the lowercase trimmed address; for phone, the E.164 number (digits with leading +).

Tip: If your data is already hashed with SHA256, use the hashed_* fields. Otherwise, use the raw fields and Zeotap handles normalization and hashing automatically. When both a raw field and its pre-hashed counterpart are mapped, the pre-hashed value wins; values that are not valid 64-hex digests are never uploaded — they are dropped (falling back to the raw column if mapped) and counted in the sync run logs. See Match Keys & Identifier Hashing for the full contract.

How It Works

Zeotap reads rows from your model query, applies field mapping, and extracts user identifiers (email and phone). Raw PII fields are normalized and hashed with SHA256 per Meta’s requirements — emails are lowercased and trimmed, phone numbers are normalized to E.164 format.

Users are uploaded to the Custom Audience in batches of up to 10,000 per API call. For Mirror mode, Zeotap first clears the existing audience, then uploads the complete user set.

Rows with neither an email nor a phone are not uploaded, because Meta has nothing to match them on. They are not counted as failed, so an audience made mostly of rows without either (web visitors known only by cookie, for example) still uploads in full-size batches. Expect the Custom Audience to be smaller than the run’s row counts in that case.

Each batch result is tracked individually — if some records fail, the sync continues with remaining batches and reports partial success. A row counts as failed only when it was sent and Meta did not accept it.

Retries

• Throttling and temporary errors — when Meta throttles an upload (HTTP 429 or one of its rate-limit error codes) or reports a temporary error, Zeotap waits and sends the same upload again, up to five attempts in all. It waits as long as Meta asks, or otherwise backs off from 2 seconds, doubling up to 1 minute, and never waits more than 5 minutes at a time. If the destination has a rate limit set, a throttle also pauses every other sync sending to it, so they back off together.
• Permanent errors — an invalid or expired token, a missing permission or a malformed request fails the same way every time, so it is not retried.

A heavily throttled run therefore takes longer, but delivers what it read instead of dropping the throttled uploads.

Audience Boost

Audience Boost can add emails and phones resolved from an identity graph. Meta accepts email and phone only, so those are the identifier types offered. The boosted members go to a separate Custom Audience named <Audience Name>_boosted, found by name and reused on every run. Boost needs a fixed Audience Name: a sync that targets an audience by Audience ID only, or takes the name from a column, runs without Boost.

Best Practices

Maximize match rates

Map both email and phone where you have them — those are the identifiers Zeotap uploads, and a row matched on either counts. To add more identifiers than your own data holds, enable Audience Boost.

Use consistent identifiers

Use the same email addresses and phone numbers that users registered with on Facebook. Work email addresses typically have very low match rates.

Audience sizing

Meta requires a minimum of approximately 1,000 matched users before an audience can be used for targeting. Audiences below this threshold appear with a size of “less than 1,000” and cannot be targeted.

Scheduling

For audience syncs, daily or hourly schedules work well. Meta processes audience uploads asynchronously — it may take up to 72 hours for newly uploaded audiences to fully populate.

Pre-hashed data

If your warehouse already stores SHA256-hashed PII (e.g., from an identity graph), use the hashed_* fields. This avoids unnecessary re-hashing and ensures the hashes match Meta’s expectations exactly.

Troubleshooting

Ad Account ID not found

Ensure you are using the numeric ID without the act_ prefix. Find it in Business Manager under Business Settings > Accounts > Ad Accounts. The ID is the number shown below the account name.

Insufficient permissions

The authenticated user or system user must have Advertiser or Admin role on the Ad Account with Full Control access. Check roles in Business Manager > Business Settings > Ad Accounts > People (for users) or System Users (for system users). Also verify the ads_management permission is granted on the token.

Token expired

OAuth tokens expire after 60 days of inactivity. If your sync fails with an authentication error, re-authenticate via OAuth or switch to a System User Token (recommended) which can be set to never expire.

Low audience match rate

Meta hashes user data before matching against its user base. To improve match rates:

• Ensure emails are lowercase with no extra whitespace
• Include country codes on phone numbers (e.g., +1 for US)
• Map phone in addition to email
• Enable Audience Boost to add emails and phones resolved from an identity graph

Audience size shows “less than 1,000”

Meta requires a minimum of approximately 1,000 matched users for privacy reasons. If your audience is smaller than this, it cannot be used for ad targeting. Expand your source audience, or map both email and phone to increase the match rate.

Rate limiting

Meta’s Marketing API enforces rate limits per ad account. Zeotap uses 10,000-user batches to minimize API calls and retries throttled uploads automatically (see Retries). If runs regularly spend a long time throttled, reduce sync frequency or contact Meta to request a higher rate limit tier for your ad account.

Custom Audience creation failed

Verify that your ad account has not reached the maximum number of Custom Audiences (typically 500 per ad account). Delete unused audiences in Ads Manager > Audiences to free up capacity.