Permutive
Sync audience segments to Permutive for publisher-side targeting and cohort management. Zeotap connects to Permutive’s Taxonomy API to create, update, and remove segments within your audience imports.
Prerequisites
- A Permutive account with API access
- A private API key (not a public key) — generate one from your Permutive dashboard under Settings > Keys
- An existing audience import configured in Permutive (you will need the import UUID)
Permissions
Your private API key must have write access to the Taxonomy API. Default access is read-only — contact Permutive Technical Services to request custom access levels if needed.
Authentication
Permutive uses Private API Key authentication.
- Log in to your Permutive dashboard
- Navigate to Settings > Keys
- Click Add Key and select Private as the key type
- Copy the generated UUID-format API key
- Enter the API key in Zeotap when configuring the destination
Configuration
| Field | Type | Required | Description |
|---|---|---|---|
| Import ID | Text | Yes | The UUID of the audience import in Permutive to sync segments into. Find this in your Permutive dashboard under Audience Platform > Imports. Example: 32f8e031-c532-41bb-b25e-65bdb677a96f |
Target Settings
| Field | Type | Required | Description |
|---|---|---|---|
| Segment Name | Text | Yes | Human-readable name for the segment in Permutive |
| Segment Code | Text | No | Unique code identifier for the segment. Leave blank to auto-generate from the segment name |
Supported Operations
Sync Modes
This destination is audience-only and does not support standard data sync modes.
Audience Sync Modes
| Mode | Supported |
|---|---|
| Add | Yes |
| Remove | Yes |
| Mirror | Yes |
| Upsert | Yes |
Features
- Field Mapping: No
- Schema Introspection: No
Required Mapping Fields
| Field | Description |
|---|---|
segment_code | Segment code that identifies users in the audience |
Default Destination Fields
This destination does not define default destination fields. Map your source fields to segment_code, segment_name, and optionally description in your sync configuration.
How It Works
- Segment mapping: Each row in your sync is mapped to a segment operation (Create, Update, or Delete) within the configured Permutive import
- Batch processing: Operations are batched into groups of up to 5,000 and sent to the Permutive Taxonomy API’s batch update endpoint (
PATCH /imports/{importId}/segments) - Sync modes: In Add and Upsert modes, rows are sent as Create operations. In Remove mode, rows are sent as Delete operations. In Mirror mode, added/changed rows become Create operations and removed rows become Delete operations
- Error handling: If a batch fails, individual row errors are recorded and the sync continues with remaining batches
Rate Limits
Permutive does not publish explicit rate limits for the Taxonomy API. Zeotap processes batches sequentially and respects 429 Too Many Requests responses with automatic exponential backoff and retry. If you experience throttling, consider reducing sync frequency or batch sizes.
Best Practices
- Use meaningful segment codes: Segment codes should be stable identifiers that don’t change between syncs. Avoid using auto-generated codes for production workflows
- Keep imports organized: Group related segments under the same import for easier management in the Permutive dashboard
- Test with a dedicated import: Create a separate import for testing before syncing to your production imports
- Monitor segment counts: After syncing, verify segment counts in the Permutive dashboard to ensure data arrived correctly
Troubleshooting
Authentication failed: invalid API key
Ensure you are using a private API key, not a public key. Public keys cannot access the Taxonomy API. Generate a new private key from Settings > Keys in the Permutive dashboard.
Import not found (404)
Verify your import ID is correct. The import ID is a UUID found in the Permutive dashboard under Audience Platform > Imports. Copy the full UUID including dashes.
Insufficient permissions (403)
Your API key may have read-only access. Contact Permutive Technical Services to request write access to the Taxonomy API for your key.
Duplicate segment code error
Segment codes must be unique within an import. If you receive a 409 Conflict error, check that you are not creating a segment with a code that already exists. Use Upsert mode to update existing segments.
Batch operation partially failed
The Permutive batch API does not guarantee execution order for operations within a batch. If some operations fail, check the error details in the sync log. Common causes include invalid segment codes or missing required fields.
Segments not appearing in cohorts
After segments are created via the API, they must be used in a cohort query to be activated. Navigate to Audience Platform > Cohorts in Permutive and create a cohort that references your imported segments.