Taboola
Sync first-party audience segments to Taboola for native advertising targeting. Zeotap uploads hashed user identifiers to Taboola’s Backstage API, enabling you to build and manage audience lists for your Taboola campaigns.
Prerequisites
- A Taboola Backstage account with API access enabled
- API client credentials (Client ID and Client Secret), provided by your Taboola account manager
- Your Taboola advertiser Account ID
Authentication
Taboola uses OAuth 2.0 Client Credentials authentication.
- Contact your Taboola account manager to request API credentials (Client ID and Client Secret)
- In Zeotap, navigate to Destinations and click Add Destination
- Select Taboola and enter your Client ID and Client Secret
Zeotap automatically obtains and refreshes access tokens using these credentials. Tokens are valid for 12 hours and are refreshed automatically before expiry.
Configuration
| Field | Type | Required | Description |
|---|---|---|---|
| Account ID | Text | Yes | Your Taboola advertiser account identifier. Provided by your Taboola account manager. |
Target Settings
| Field | Type | Required | Description |
|---|---|---|---|
| Audience Name | Text | Yes | Name of the Taboola first-party audience to create or update. If the name already exists, Zeotap uses the existing audience. |
| Audience ID | Text | No | Existing audience ID to update. Leave blank to create a new audience automatically. |
| Audience TTL (Hours) | Number | No | How long users remain in the audience, in hours. Default is 8760 (365 days). |
Supported Operations
Sync Modes
This destination is audience-only and does not support standard data sync modes.
Audience Sync Modes
| Mode | Supported | Description |
|---|---|---|
| Add | Yes | Add users to the Taboola audience |
| Remove | Yes | Remove users from the Taboola audience |
| Mirror | Yes | Full sync: adds new users and removes users no longer in the audience |
| Upsert | Yes | Add users (idempotent, equivalent to Add) |
Features
| Feature | Supported |
|---|---|
| Field Mapping | No |
| Schema Introspection | No |
How It Works
- Authentication: Zeotap obtains an OAuth2 access token using your client credentials
- Audience creation: If no Audience ID is provided, Zeotap creates a new first-party audience via the Backstage API. If an audience with the same name already exists, the existing audience is reused.
- Identity upload: User identifiers (email, phone, device ID) are normalized and SHA256-hashed, then uploaded to the audience using Taboola’s audience onboarding endpoint
- Batch processing: Identifiers are sent in batches of up to 100,000 per request
- Mirror mode: For mirror syncs, Zeotap sends ADD operations for current members and REMOVE operations for users no longer in the audience
Supported Identity Types
| Type | Field | Hashing |
|---|---|---|
email | SHA256 (normalized: lowercase, trimmed) | |
| Phone | phone | SHA256 (normalized: digits only with leading +) |
| Device ID | device_id | Passed as-is |
Rate Limits
Taboola does not publish explicit rate limits for the audience onboarding API. Zeotap uses automatic retry with exponential backoff for transient errors (429 and 5xx responses).
Best Practices
- Use descriptive audience names to make audiences easy to identify in the Taboola Backstage dashboard
- Populate audiences with at least 1,000 users for effective targeting scale
- Allow up to 1 hour for newly created audiences to become available in Taboola’s targeting system
- Wait 1-3 days for a new audience to achieve full scale after initial population
- Set appropriate TTL values to automatically expire stale audience members
Troubleshooting
Authentication failed: invalid client credentials
Verify your Client ID and Client Secret are correct. These are provided by your Taboola account manager. If you have recently rotated credentials, update them in Zeotap.
Account not found or insufficient permissions
Ensure the Account ID matches your Taboola advertiser account. Contact your Taboola account manager to confirm your account has API access and audience onboarding permissions enabled.
Audience not appearing in Taboola
Newly created audiences can take up to 1 hour to appear in the Taboola Backstage dashboard. Wait and check again. If the audience still does not appear, verify that your account has audience onboarding enabled for your region.
Low match rates
Taboola audience onboarding match rates vary by country. If you see low match rates, ensure you are targeting supported countries and that email addresses are valid and correctly formatted.
Token endpoint returned 403
Ensure the token endpoint URL does not contain a trailing slash. Zeotap handles this automatically, but if you experience issues, verify your network allows outbound HTTPS connections to backstage.taboola.com.
Batch upload timeouts
For very large audiences, uploads are automatically chunked into batches of 100,000 identifiers. If you experience timeouts, check your network connectivity. Zeotap retries failed requests with exponential backoff.