Send Event API - Track User Activities & Trigger Rewards

Track user actions and trigger gamification rewards with our Event Logging API. Send events to award loyalty points, track user engagement, progress challenges, maintain streaks, and power your analytics dashboard.

Perfect for e-commerce purchases, user logins, content interactions, level completions, social actions, and any trackable user behavior. Supports rich metadata for conditional rewards, segmentation, and detailed analytics.

Record user activities in your application that should earn points, contribute to streaks, or be tracked for analytics purposes.

Endpoint

POST /event

Request Body

{
  "eventId": "daily_login",
  "userId": "user123",
  "metadata": {
    "platform": "ios",
    "appVersion": "2.1.4",
    "sessionLength": 183
  }
}

Field Descriptions

Field	Type	Required	Description
`eventId`	string	Yes	Identifier for the event type (e.g., 'daily_login', 'complete_profile')
`userId`	string	Yes	Unique identifier of the user performing the action
`metadata`	object	No	Optional additional event data (max 10 fields)

Working with Metadata

Metadata allows you to include rich contextual information with your events. This data is stored with the event and used for advanced analytics and conditional logic.

Why Use Metadata?

Enhanced Analytics: Track detailed information about how, when, and where events occur
Segmentation: Analyze user behavior based on metadata attributes
Conditional Rules: Create sophisticated event rules based on metadata values
Future-Proofing: Store potentially useful information without changing your core event structure

Metadata Best Practices

Be Consistent: Use the same field names across similar events
Use Appropriate Types:
- Numbers for quantities, durations, and measurable values
- Strings for categories, identifiers, and textual data
- Booleans for flags and status indicators
Keep It Relevant: Only include data that provides meaningful context
Avoid PII: Never include personally identifiable information

Common Metadata Fields

When creating an event in the dashboard, you can add custom metadata fields. Metadata serves three main purposes:

Analytics: Gain deeper insights using metadata.
Conditional Events: Define conditions based on metadata (e.g., minimum purchase value or activity duration).
Value-Based Rewards: Reward users based on their spending (e.g., 2 points for every € spent).

Note: There is a limit of 10 metadata fields per request.

metadata: {
  // Device Context
  platform: 'android',         // Operating system/platform
  deviceType: 'mobile',        // Device category
  appVersion: '3.2.1',         // Application version
 
  // User Context
  usergroup: 'subscriber',       // Usergroup of the user (can be configured in the dashboard)
  accountAge: 63,              // Days since account creation
 
  // Event Details
  value: 29.99,                // For purchase events: monetary value
  itemId: 'premium_skin_12',   // For item interactions: which item
  duration: 145,               // For timed activities: seconds spent
  difficulty: 'hard',          // For challenges: difficulty level
}

How Metadata Is Processed

When you include metadata with your events:

The system automatically categorizes metadata fields by data type
Numeric fields are analyzed for min/max values, averages, and distributions
Categorical fields are analyzed for frequency counts and popular values
This aggregated data becomes available in your analytics dashboard
Trends and patterns in metadata can reveal important insights about usage

Example Request

Basic event

curl -X POST "https://api.lynesapp.de/event" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "eventId": "daily_login",
    "userId": "user123"
  }'

E-commerce Purchase Event

curl -X POST "https://api.lynesapp.de/event" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "eventId": "purchase_completed",
    "userId": "user456",
    "metadata": {
      "platform": "web",
      "transactionId": "tx_78912345",
      "orderValue": 129.99,
      "currency": "USD",
      "itemCount": 3,
      "paymentMethod": "credit_card"
    }
  }'

Game Level Completion

curl -X POST "https://api.lynesapp.de/event" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "eventId": "level_completed",
    "userId": "gamer789",
    "metadata": {
      "levelId": "world_2_level_5",
      "difficulty": "normal",
      "timeToComplete": 347,
      "attempts": 2,
      "starsEarned": 3,
      "scoreAchieved": 12850,
      "powerupsUsed": 2,
      "platform": "ios"
    }
  }'

Response

Success Response (200 OK)

{
  "success": true,
  "data": {
    "eventId": "daily_login",
    "userId": "user123",
    "pointsAwarded": 10,
    "timestamp": 1648232567123,
    "streaks": [
      {
        "streakId": "daily_app_use",
        "currentCount": 3,
        "lastUpdate": "2023-04-07T12:34:56.789Z",
        "milestoneReached": false,
        "pointsAwarded": 0
      }
    ]
  }
}

Status Codes

Status Code	Description
`200`	Event successfully logged
`400`	Bad request - Missing required fields or invalid data
`401`	Unauthorized - Invalid or missing authentication token
`404`	Event ID not found or inactive
`429`	Too many requests - Rate limit exceeded
`500`	Internal server error

Analytics Benefits

The metadata you provide with events enables rich analytics capabilities:

Track event performance across different platforms and app versions
Identify optimal user flows and conversion paths
Discover which game levels need balancing based on completion times
See which product categories drive the most engagement
Understand how feature usage correlates with retention

By consistently including relevant metadata with your events, you'll build a valuable dataset that can drive product improvements and business decisions.

Create your first event Get User History | Lynes Loyalty API