> ## Documentation Index
> Fetch the complete documentation index at: https://flywheel.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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. Custom properties must be placed within a `$set` object:

```javascript theme={null}
{
  "event": {
    "event": "profile_updated",
    "user_id": "user123",
    "identify": true,
    "properties": {
      "email": "john.doe@company.com",
      "first_name": "John", 
      "last_name": "Doe",
      "phone": "+1-555-0123",
      "$set": {
        "company": "Tech Corp",
        "job_title": "Engineering Manager"
      }
    }
  }
}
```

<Note>
  Standard user properties (email, first\_name, last\_name, phone, etc.) are extracted from the root level of `properties`. Custom properties are only extracted from the `$set` object. Properties outside `$set` that aren't standard user properties will not be added as custom properties.
</Note>

#### 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**

```javascript theme={null}
{
  "event": {
    "event": "user_registered",
    "user_id": "new_user_123",
    "identify": true,
    "properties": {
      "email": "jane@startup.com",
      "first_name": "Jane",
      "last_name": "Smith",
      "$set": {
        "company": "Startup Inc",
        "plan": "premium",
        "source": "website"
      }
    }
  }
}
```

**Profile Update Event**

```javascript theme={null}
{
  "event": {
    "event": "profile_updated",
    "user_id": "existing_user_456",
    "identify": true,
    "properties": {
      "phone": "+1-555-9876",
      "$set": {
        "job_title": "Senior Developer",
        "company_size": "50-100"
      }
    }
  }
}
```

**Anonymous to Identified User**

```javascript theme={null}
{
  "event": {
    "event": "user_converted",
    "anonymous_id": "anon_789",
    "identify": true,
    "properties": {
      "email": "convert@example.com",
      "first_name": "Alex",
      "$set": {
        "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

```javascript theme={null}
{
  "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:

```javascript theme={null}
{
  "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:

<CardGroup cols={1}>
  <Card title="Track User Event" icon="chart-line" href="/api-reference/events/track-user-event">
    Track user events to build comprehensive profiles and trigger automated workflows
  </Card>
</CardGroup>

## 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.