Facebook Ads (Meta)

Upload Custom Audiences to Meta Ads for targeted advertising on Facebook and Instagram. SignalSmith 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

SignalSmith 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 SignalSmith
2. Sign in with your Facebook Business account
3. Authorize the requested permissions (ads_management, ads_read)

OAuth tokens are valid for 60 days. SignalSmith 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 SignalSmith, 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

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

Required Mapping Fields

Default Destination Fields

Raw Identifiers (auto-hashed by SignalSmith)

email, phone, fn (First Name), ln (Last Name), ct (City), st (State), country, zip (Zip Code), madid (Mobile Advertiser ID), doby (Date of Birth Year), gen (Gender)

Pre-Hashed Identifiers (passed through as-is)

hashed_email, hashed_phone, hashed_fn, hashed_ln, hashed_ct, hashed_st, hashed_country, hashed_zip

Tip: If your data is already hashed with SHA256, use the hashed_* fields to avoid double-hashing. Otherwise, use the raw fields and SignalSmith handles hashing automatically.

How It Works

SignalSmith reads rows from your model query, applies field mapping, and extracts user identifiers (email, phone, external ID). 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, SignalSmith first clears the existing audience, then uploads the complete user set.

Each batch result is tracked individually — if some records fail, the sync continues with remaining batches and reports partial success.

Best Practices

Maximize match rates

Include as many identifier fields as possible. Meta matches users by cross-referencing multiple identifiers. An email alone yields ~30-50% match rates, but adding phone, name, and location can push rates above 70%.

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 first name, last name, city, state, and zip code in addition to email
• Use the madid (Mobile Advertiser ID) field if available from your mobile data

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 include more identifier fields to increase the match rate.

Rate limiting

Meta’s Marketing API enforces rate limits per ad account. SignalSmith uses 10,000-user batches to minimize API calls. If you encounter rate limiting, 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.