Userflow

Sync user profiles, groups, and product events to Userflow for personalized onboarding flows, checklists, and in-app experiences. Zeotap keeps your Userflow user data in sync with your warehouse so you can target the right users with the right onboarding content.

Prerequisites

• A Userflow account with API access
• A Userflow API key from Settings > Integrations > API
• User IDs in Userflow must match the IDs used with userflow.js identify() to avoid duplicate records

Authentication

Userflow uses API key authentication with a Bearer token.

1. Log in to your Userflow dashboard
2. Navigate to Settings > Integrations > API
3. Copy your API key (starts with uf_at_)
4. Paste the API key into the API Key field in Zeotap

Configuration

This destination has no additional configuration fields beyond the target settings.

Target Settings

Supported Operations

Sync Modes

The Userflow API uses upsert semantics for users and groups. A POST to /users/{user_id} creates the user if new, or updates attributes if the user already exists. Insert mode is used for appending events. Events are always appended and cannot be updated or deleted.

Audience Sync Modes

Userflow does not have a list or segment membership API. Audience syncs are not supported.

Features

• Field Mapping: Yes (map source columns to user/group attributes or event fields)
• Schema Introspection: No

Required Mapping Fields

Default Destination Fields

Users

Groups

Events

How It Works

User Syncs

1. Zeotap maps your source columns to Userflow user attributes
2. Each user is sent individually via POST /users/{user_id} to the Userflow REST API
3. The request body contains an attributes object with all mapped fields (except user_id)
4. Userflow creates the user if it does not exist, or updates the specified attributes if it does (upsert semantics)
5. Omitted attributes are preserved — use null to explicitly clear an attribute value

Group Syncs

1. Zeotap maps your source columns to Userflow group attributes
2. Each group is sent individually via POST /groups/{group_id} to the Userflow REST API
3. The request body contains an attributes object with all mapped fields (except group_id)
4. Userflow creates the group if it does not exist, or updates the specified attributes if it does

Event Syncs

1. Zeotap maps your source columns to Userflow event fields
2. Each event is sent individually via POST /events to the Userflow REST API
3. The request body includes user_id, name (event name), and attributes (additional event data)
4. Events trigger flows and checklists configured in the Userflow dashboard that match the event name

Rate Limits

Userflow enforces rate limits per API key. Exact limits vary by plan and are not publicly documented. Zeotap automatically handles rate limiting:

• HTTP 429 responses trigger automatic retries with exponential backoff
• Each user, group, or event is sent as an individual API request (no bulk endpoint)
• Large syncs may take longer due to per-request rate limiting

Best Practices

• Ensure user_id values match the IDs used in userflow.js identify() calls to avoid creating duplicate user records
• Use Upsert mode for initial data loads and ongoing syncs to create new users and update existing ones
• Use Insert mode for event syncs to append product events to Userflow
• Map signed_up_at for users so Userflow can properly calculate time-based targeting conditions
• Set the locale attribute to enable localized onboarding flows
• Use descriptive, consistent event names that match your Userflow flow triggers (event names are case-sensitive)
• Keep the attributes field for events as a flat JSON object for best compatibility with Userflow conditions

Troubleshooting

Authentication failed: invalid API key

Verify your API key is correct and starts with uf_at_. API keys are found in Settings > Integrations > API in the Userflow dashboard. Ensure you are using a full API key, not a restricted key.

Users not appearing in Userflow

User IDs must match those used with userflow.js identify(). If the IDs do not match, Userflow creates separate user records. Check that the user_id field in your source data matches the identifiers your application passes to the Userflow JavaScript SDK.

Duplicate user records

Duplicate records occur when different user_id values are used for the same person across Zeotap and userflow.js. Standardize on a single user identifier format across all systems.

Events not triggering flows

Event names in Userflow are case-sensitive. Verify the event_name value exactly matches the event name configured in your Userflow flow trigger. Also confirm the flow is published and active.

Rate limit errors (429)

Zeotap retries automatically with exponential backoff on 429 responses. If rate limit errors persist, reduce sync frequency or contact Userflow support to discuss your plan’s API rate limits.

Attributes not updating

The Userflow API preserves omitted attributes — it does not delete them. To clear an attribute, explicitly map it to null. If attributes appear stale, verify the source data contains the expected values and the field mapping is correct.

Group membership not syncing

The Userflow REST API for groups manages group attributes only. To associate users with groups, include group_id and group_attributes when syncing users, or manage memberships through the userflow.js SDK. Zeotap’s group object type syncs group-level attributes, not user-group membership.