Track User Event

Track a user event to build comprehensive user profiles and trigger automated workflows. Events represent user actions, behaviors, and interactions with your product that you want to track and analyze.

POST /v1/events

Try it

cURL

user_signup

curl --request POST \
  --url https://api.flywheel.cx/v1/events \
  --header 'Auth-Type: <api-key>' \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "event": {
    "event": "user_signup",
    "user_id": "user123",
    "properties": {
      "source": "website",
      "plan": "premium",
      "utm_source": "google_ads",
      "utm_campaign": "summer2024"
    }
  }
}
'

200

{
  "success": true,
  "message": "Event tracked successfully"
}

Authorizations

Authorization · string · header · required

Enter your API key obtained from the Flywheel dashboard (without 'Bearer ' prefix)

Auth-Type · string · header · default: api · required

Authentication type header. Must be set to 'api' for all API requests.

Body

application/json

event · object · required

Show child attributes

event. event · string · required

The name/type of the event. Use descriptive, consistent naming (e.g., 'user_signup', 'product_purchased', 'page_viewed')

Example:

"user_signup"

event. user_id · string

Unique identifier for the user who performed the action. If not provided, the event will be tracked as anonymous

Example:

"user123"

event. timestamp · string<date-time>

When the event occurred in ISO 8601 format with timezone offset. If not provided, the current server time will be used

Example:

"2024-01-15T10:30:00Z"

event. event_id · string

Optional unique identifier for this specific event occurrence. If not provided, a UUID will be generated automatically

Example:

"evt_123456789"

event. properties · object

Additional data associated with the event. Can include any business-specific information relevant to the event

Show child attributes

event.properties. {key}

Example:

{
  "source": "website",
  "plan": "premium",
  "price": 99.99,
  "is_trial": false,
  "signup_date": "2024-01-15T10:30:00Z"
}

event. anonymous_id · string

Anonymous identifier for users who haven't been identified yet. Useful for tracking anonymous visitors before they sign up or log in

Example:

"anon_789012345"

event. identify · boolean · default: false

When set to true, triggers user identification and profile creation/update before the event is processed. This extracts user properties from the event data and creates or updates the user profile with identifiable information like email, phone, name, etc. If false or omitted, the event is processed without explicit user identification.

Example:

true

Response

200

application/json

Event tracked successfully

success · boolean

Whether the event was tracked successfully

Example:

true

message · string

Success message

Example:

"Event tracked successfully"