Flagsmith

Sync identities and traits to Flagsmith for segment-based feature flag targeting. Zeotap pushes identity traits into Flagsmith, enabling you to target feature flags and experiments based on your warehouse data.

Prerequisites

A Flagsmith account (Cloud or self-hosted) with API access
A server-side environment key for the target environment
At least one environment set up in your Flagsmith project

Authentication

Flagsmith uses Server-Side Environment Key authentication.

In Flagsmith, navigate to your project and select the target environment
Go to Environment Settings > Keys
Copy the Server-side Environment Key (starts with ser.)
Paste it into the Server-Side Environment Key field in Zeotap

Important: Use the server-side key, not the client-side key. Client-side keys do not have write access to the Identities API.

Configuration

Field	Type	Required	Description
API Instance	Text	Yes	The Flagsmith API base URL. Defaults to `https://edge.api.flagsmith.com/api/v1` for Flagsmith Cloud. For self-hosted Flagsmith, enter your instance URL including the `/api/v1` path (e.g. `https://flagsmith.example.com/api/v1`). Use `https://api.flagsmith.com/api/v1` for legacy Flagsmith Cloud setups.

Target Settings

Field	Type	Required	Description
Trait Key Prefix	Text	No	Optional prefix for trait keys synced by Zeotap (e.g. `ss_` results in traits like `ss_plan_type`)
Delete Traits on Remove	Toggle	No	When enabled, traits are deleted from identities during remove operations. When disabled, traits are set to `false` instead. Default: off

Supported Operations

Sync Modes

Mode	Supported
Upsert	Yes
Insert	—
Update	—
Mirror	—

Audience Sync Modes

Mode	Supported
Add	Yes
Remove	Yes
Mirror	Yes

Features

Field Mapping: Yes (mapped fields become traits on the identity)
Schema Introspection: No

Required Mapping Fields

Field	Description
identifier	The unique identity identifier in Flagsmith. This maps to the Flagsmith identity key.

Default Destination Fields

identifier, trait_key, trait_value

How It Works

Record Syncs (Upsert)

Zeotap reads rows from your model or query
Each row is sent to the Flagsmith Identities API
The identifier field becomes the Flagsmith identity key
All other mapped fields become individual traits on the identity
Existing traits with the same key are updated; new traits are created

Audience Syncs

Zeotap extracts identifiers from your audience
For Add mode, an in_audience trait is set to true on each identity
For Remove mode, the in_audience trait is set to false (or deleted if Delete Traits on Remove is enabled)
For Mirror mode, added identities get in_audience: true and removed identities get in_audience: false (or deleted)
Create a Flagsmith segment with a rule matching in_audience = true to automatically target these identities

If a Trait Key Prefix is configured, all trait keys are prefixed accordingly (e.g., ss_in_audience instead of in_audience).

Segment Targeting Pattern

Flagsmith segments are rule-based, not list-based. To target identities synced by Zeotap:

Sync your audience to Flagsmith using Add or Mirror mode
In Flagsmith, create a segment with the rule: in_audience is equal to true
Assign the segment to a feature flag to control targeting

This pattern allows you to manage targeting from your warehouse data while keeping segment rules flexible in Flagsmith.

Rate Limits

Flagsmith Cloud enforces rate limits per environment key. The Edge API typically allows higher throughput than the Legacy API. Zeotap automatically handles rate limiting with exponential backoff and respects Retry-After headers.

For self-hosted Flagsmith, rate limits depend on your infrastructure configuration.

Best Practices

Use Mirror mode to keep audience membership fully in sync with your warehouse data
Configure a Trait Key Prefix (e.g. ss_) to distinguish Zeotap-synced traits from traits set by your application
Use the Edge API endpoint for Flagsmith Cloud accounts — it provides lower latency and higher throughput
Start with a non-production environment to verify sync behavior before targeting production
Enable Delete Traits on Remove if you want clean removal of traits rather than setting them to false

Troubleshooting

Authentication failed

Verify your environment key is a server-side key (starts with ser.). Client-side keys do not have write access. Environment keys can be found in Environment Settings > Keys in the Flagsmith dashboard.

Traits not appearing on identities

Check that the API instance URL is correct. Cloud accounts should use the Edge API (edge.api.flagsmith.com). Self-hosted instances should use the full API path including /api/v1.

Segment not matching synced identities

Ensure the segment rule matches the exact trait key used by Zeotap. If a Trait Key Prefix is configured, the trait key will be prefixed (e.g. ss_in_audience instead of in_audience). Verify the rule in Flagsmith matches the prefixed key.

Rate limit errors

If you see rate limit errors, consider reducing the sync frequency or contacting Flagsmith to increase your rate limit quota. For self-hosted deployments, review your API server configuration.

Wrong API instance

Flagsmith Cloud accounts should use edge.api.flagsmith.com. If you see connection errors, verify you selected the correct API instance. Self-hosted Flagsmith instances require the full URL including the /api/v1 path segment.

Mirror mode removing unexpected identities

Mirror mode synchronizes the audience trait to exactly match your audience. Identities not in the current audience will have their in_audience trait set to false (or deleted). If you only want to add identities without affecting existing ones, use Add mode instead.