Optimizely
Sync audience segments, user attributes, and custom events to Optimizely for experiment targeting and feature flag management. Zeotap pushes data from your warehouse into Optimizely via their REST API, enabling you to target experiments and feature flags based on your unified customer data.
Prerequisites
- An Optimizely account with Feature Experimentation or Web Experimentation enabled
- A personal access token with project-level write permissions
- The numeric project ID for the Optimizely project you want to sync to
Authentication
Optimizely uses Personal Access Token authentication.
- Log in to your Optimizely account
- Navigate to Profile > API Access
- Click Generate New Token
- Give the token a descriptive name (e.g., “Zeotap Integration”)
- Copy the token immediately — it will not be shown again
- Paste it into the Personal Access Token field in Zeotap
Personal access tokens provide full API access to the projects in your account. Administrators can generate and revoke tokens for all users from the API Access page.
Configuration
| Field | Type | Required | Description |
|---|---|---|---|
| Project ID | Text | Yes | The numeric Optimizely project ID. Find this in Settings > Project in Optimizely. |
| Object Type | Select | Yes | The type of resource to sync: Audiences, List Attributes, Custom Events, or Attributes. |
Target Settings
Target settings vary based on the selected object type.
When Object Type is “Audiences”
| Field | Type | Required | Description |
|---|---|---|---|
| Audience Name | Text | Yes | The name of the audience to create or update in Optimizely |
When Object Type is “List Attributes”
| Field | Type | Required | Description |
|---|---|---|---|
| List Attribute ID | Text | Yes | The ID of the list attribute in Optimizely to sync users to |
Supported Operations
Sync Modes
| Mode | Supported |
|---|---|
| Upsert | Yes |
| Insert | Yes |
| Update | — |
| Mirror | — |
Audience Sync Modes
| Mode | Supported |
|---|---|
| Add | Yes |
| Remove | Yes |
| Mirror | Yes |
Features
- Field Mapping: Yes
- Schema Introspection: No
Required Mapping Fields
| Field | Description |
|---|---|
| user_id | The unique user identifier for Optimizely targeting |
Default Destination Fields
| Field | Type |
|---|---|
user_id | string |
name | string |
key | string |
description | string |
How It Works
Audience Syncs (List Attributes)
- Zeotap extracts user IDs from your model or audience
- User IDs are sent to the Optimizely List Attributes API in batches of 50
- For Add mode, user IDs are added to the list attribute
- For Remove mode, user IDs are removed from the list attribute
- For Mirror mode, added/changed users are included and removed users are excluded — keeping the list in sync with your warehouse
Data Syncs
- Audiences: Creates audience definitions in Optimizely with targeting conditions
- Custom Events: Creates custom event definitions for experiment tracking
- Attributes: Creates attribute definitions for audience targeting rules
Rate Limits
Optimizely enforces the following rate limits:
- Feature Experimentation API: 2 requests per second, 120 requests per minute
- Web Experimentation API: 100 requests per minute
Zeotap automatically handles rate limiting with exponential backoff and respects Retry-After headers. Batches are kept small (50 items) to stay within rate limits.
Best Practices
- Use List Attributes with audience sync modes for the most reliable audience targeting
- Create a dedicated personal access token for Zeotap to simplify access management
- Use Mirror mode to keep list attributes fully in sync with your warehouse data
- Start with a test project to verify sync behavior before targeting production experiments
- Keep audience names descriptive and consistent between Zeotap and Optimizely
- Revoke and rotate personal access tokens periodically for security
Troubleshooting
Authentication failed
Verify your personal access token is valid and has not been revoked. Tokens can be managed in Profile > API Access. Note that SDK keys and datafile access tokens cannot be used for REST API authentication.
Project not found
Ensure the project ID is the numeric ID, not the project name. You can find it in Settings > Project in Optimizely, or in the URL when viewing the project (e.g., https://app.optimizely.com/v2/projects/12345678901).
Rate limit errors
Optimizely enforces strict rate limits (2 requests/second for Feature Experimentation). If you see rate limit errors, Zeotap retries automatically with backoff. For persistent issues, consider reducing the frequency of syncs or splitting large audiences across multiple sync schedules.
List attribute not found
Verify the list attribute ID is correct. List attributes must be created in Optimizely before syncing. Navigate to Audiences > Attributes in Optimizely to find the list attribute ID.
Audience conditions invalid
When syncing audiences, the conditions field must be valid Optimizely audience condition JSON. If not provided, Zeotap defaults to ["everyone"]. See the Optimizely documentation for the audience conditions format.
Custom events not appearing
Custom events may take a few minutes to appear in the Optimizely UI after creation. Ensure the event key is unique within the project — duplicate keys will cause creation to fail.
Mirror mode removing unexpected users
Mirror mode synchronizes the list attribute to exactly match your audience. Users not in the current audience will be removed. If you only want to add users without removing existing ones, use Add mode instead.