Events API

Track user events to build comprehensive user profiles and trigger automated workflows

Overview

The Flywheel Events API allows you to track user actions, behaviors, and interactions with your product. Events are the foundation for building comprehensive user profiles and triggering automated workflows in Flywheel.

Events represent any meaningful user action you want to track and analyze, such as:

• User signups and registrations
• Product purchases and transactions
• Page views and navigation
• Feature usage and engagement
• Profile updates and changes

Authentication

All events endpoints require authentication using an API key and authentication type header. Include both headers in your requests:

Authorization: YOUR_API_KEY
Auth-Type: api

Both headers are required for all API requests.

User Identification

The identify Parameter

The identify parameter is a powerful boolean flag that controls whether user identification and profile updates occur before the event is processed. When set to true, Flywheel will:

1. Extract User Data: Pull identifiable information from the event properties
2. Find or Create User: Locate existing users or create new profiles
3. Update Profile: Merge new information with existing user data
4. Link Event: Associate the event with the identified user

When to Use identify: true

Use the identify parameter when your event contains user profile information that should update the user’s record:

{
  "event": {
    "event": "profile_updated",
    "user_id": "user123",
    "identify": true,
    "properties": {
      "email": "[e-mail]",
      "first_name": "John", 
      "last_name": "Doe",
      "phone": "[phone]",
      "company": "Tech Corp",
      "job_title": "Engineering Manager"
    }
  }
}

Identifiable Properties

When identify: true is set, Flywheel extracts these properties from the event data to update user profiles:

• email: User’s email address
• first_name: User’s first name
• last_name: User’s last name
• full_name: Full name (automatically split into first/last)
• phone: Phone number
• primary_email: Primary email address
• primary_phone: Primary phone number
• stripe_customer_id: Stripe customer identifier

User Lookup Priority

Flywheel uses this priority order to find existing users:

1. Direct user ID (user_id parameter)
2. Organization assigned user ID (org_assigned_user_id)
3. Identifiable properties in order:
   • stripe_customer_id
   • email
   • anonymous_id
   • primary_email
   • primary_phone
   • phone

Examples with identify

User Registration with Profile Data

{
  "event": {
    "event": "user_registered",
    "user_id": "new_user_123",
    "identify": true,
    "properties": {
      "email": "[e-mail]",
      "first_name": "Jane",
      "last_name": "Smith",
      "company": "Startup Inc",
      "plan": "premium",
      "source": "website"
    }
  }
}

Profile Update Event

{
  "event": {
    "event": "profile_updated",
    "user_id": "existing_user_456",
    "identify": true,
    "properties": {
      "phone": "[phone]",
      "job_title": "Senior Developer",
      "company_size": "50-100"
    }
  }
}

Anonymous to Identified User

{
  "event": {
    "event": "user_converted",
    "anonymous_id": "anon_789",
    "identify": true,
    "properties": {
      "email": "[e-mail]",
      "first_name": "Alex",
      "conversion_source": "trial_signup"
    }
  }
}

Performance Considerations

• Use sparingly: Only set identify: true when you need to update user profiles
• Batch updates: Consider batching profile updates rather than identifying on every event
• Profile-specific events: Best used for events that inherently involve profile changes

Event Properties

Event properties can include any additional data relevant to the event:

Supported Property Types

• String: Text values, names, IDs
• Number: Prices, quantities, scores, durations
• Boolean: True/false flags
• DateTime: ISO 8601 formatted timestamps

Property Examples

{
  "properties": {
    // String properties
    "product_name": "Premium Plan",
    "user_type": "enterprise",
    "source": "organic_search",
    
    // Number properties
    "price": 99.99,
    "quantity": 3,
    "session_duration": 1800,
    
    // Boolean properties
    "is_trial_user": true,
    "email_verified": false,
    "has_mobile_app": true,
    
    // DateTime properties
    "trial_end_date": "2024-02-15T00:00:00Z",
    "last_login": "2024-01-15T10:30:00Z"
  }
}

Anonymous Events

You can track events for users who haven’t been identified yet using the anonymous_id parameter:

{
  "event": {
    "event": "page_viewed",
    "anonymous_id": "anon_789",
    "properties": {
      "page": "/pricing",
      "referrer": "https://google.com",
      "device_type": "mobile"
    }
  }
}

Anonymous events can later be linked to identified users when they sign up or log in.

Endpoints

The following endpoint is available with interactive API playground for testing:

Track User Event

Track user events to build comprehensive profiles and trigger automated workflows

Event Processing

All events are processed through Flywheel’s event pipeline which:

1. Validates the event data against your schema (if configured)
2. Identifies the user (if identify: true is set)
3. Stores the event in your organization’s database
4. Triggers any configured workflows and automations
5. Updates user profiles and segments in real-time

Best Practices

Event Naming

• Use descriptive, consistent names: user_signup, product_purchased, trial_started
• Use snake_case for event names
• Be specific but not overly verbose
• Group related events with common prefixes: checkout_started, checkout_completed

Properties

• Include relevant context in properties
• Use consistent property names across events
• Avoid nested objects when possible
• Include timestamps for time-sensitive data

Performance

• Batch events when possible for high-volume applications
• Use identify: true sparingly to avoid unnecessary processing
• Consider using anonymous tracking for non-critical events

Rate Limits

Events endpoints are subject to rate limiting to ensure fair usage and service reliability. Contact support if you need higher limits for your use case.