Events API

Track user actions and behaviors via the API.

Track Event

Records an event for a contact.

POST /api/v1/events

Request Body

Field	Type	Required	Description
externalId	string	Yes	The contact's external ID
eventKey	string	Yes	Unique identifier for the event type
properties	object	No	Additional event properties

Example Request

curl -X POST https://app.cueflow.so/api/v1/events \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "user-123",
    "eventKey": "purchase_completed",
    "properties": {
      "amount": 99.99,
      "currency": "USD",
      "plan": "pro",
      "method": "credit_card"
    }
  }'

Response

{
  "success": true,
  "event": {
    "id": "clx456def...",
    "eventKey": "purchase_completed",
    "contactId": "clx123abc...",
    "properties": {
      "amount": 99.99,
      "currency": "USD",
      "plan": "pro",
      "method": "credit_card"
    },
    "createdAt": "2024-12-13T15:30:00.000Z"
  }
}

Status Codes

Code	Description
201	Event created
400	Invalid request body
401	Unauthorized
404	Contact not found

---

Event Keys

Event keys are unique identifiers for event types. Use consistent naming:

Naming Convention

Use snake_case for event keys:

// Good
purchase_completed
feature_used
onboarding_started
report_exported

// Avoid
PurchaseCompleted
feature-used
Feature Used

Common Event Patterns

Category	Example Events
Onboarding	signup_completed, onboarding_started, onboarding_completed
Features	feature_used, report_created, export_completed
Commerce	purchase_completed, plan_upgraded, plan_downgraded
Engagement	page_viewed, button_clicked, form_submitted

---

Event Properties

Properties provide context about the event.

Supported Types

Type	Example
String	"plan": "enterprise"
Number	"amount": 99.99
Boolean	"isFirstPurchase": true

Example Properties

{
  "externalId": "user-123",
  "eventKey": "report_exported",
  "properties": {
    "reportType": "analytics",
    "format": "pdf",
    "rowCount": 1500,
    "includesCharts": true
  }
}

---

Using Events for Targeting

Events enable powerful behavioral targeting in your messages.

Event-Based Rules

After tracking events, you can target users based on:

Condition	Example Use Case
Has done	User completed onboarding
Has not done	User hasn't used feature X
Count greater than	Power users (10+ exports)
First done within	Recently started using feature
Last done within	Active in last 7 days

Example: Feature Adoption Campaign

# Track when users view a feature but don't use it
curl -X POST .../events \
  -d '{ "externalId": "user-123", "eventKey": "advanced_export_viewed" }'

# Later, track when they actually use it
curl -X POST .../events \
  -d '{ "externalId": "user-123", "eventKey": "advanced_export_used" }'

Then create a message targeting:

• advanced_export_viewed has done

• advanced_export_used has not done

---

Code Examples

Node.js

const axios = require('axios');

const cueflow = axios.create({
  baseURL: 'https://app.cueflow.so/api/v1',
  headers: {
    'Authorization': `Bearer ${process.env.CUEFLOW_API_KEY}`,
    'Content-Type': 'application/json'
  }
});

// Track an event
async function trackEvent(userId, eventKey, properties = {}) {
  const response = await cueflow.post('/events', {
    externalId: userId,
    eventKey,
    properties
  });
  return response.data;
}

// Usage examples
await trackEvent('user-123', 'signup_completed');

await trackEvent('user-123', 'purchase_completed', {
  amount: 99.99,
  plan: 'pro'
});

await trackEvent('user-123', 'feature_used', {
  feature: 'advanced_export',
  duration: 45
});

Python

import requests
import os

API_KEY = os.environ.get('CUEFLOW_API_KEY')
BASE_URL = 'https://app.cueflow.so/api/v1'

headers = {
    'Authorization': f'Bearer {API_KEY}',
    'Content-Type': 'application/json'
}

def track_event(user_id, event_key, properties=None):
    response = requests.post(
        f'{BASE_URL}/events',
        headers=headers,
        json={
            'externalId': user_id,
            'eventKey': event_key,
            'properties': properties or {}
        }
    )
    return response.json()

# Usage
track_event('user-123', 'signup_completed')

track_event('user-123', 'purchase_completed', {
    'amount': 99.99,
    'plan': 'pro'
})

PHP

<?php

$apiKey = getenv('CUEFLOW_API_KEY');
$baseUrl = 'https://app.cueflow.so/api/v1';

function trackEvent($userId, $eventKey, $properties = []) {
    global $apiKey, $baseUrl;

    $ch = curl_init("$baseUrl/events");
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        "Authorization: Bearer $apiKey",
        'Content-Type: application/json'
    ]);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
        'externalId' => $userId,
        'eventKey' => $eventKey,
        'properties' => $properties
    ]));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response, true);
}

// Usage
trackEvent('user-123', 'signup_completed');

trackEvent('user-123', 'purchase_completed', [
    'amount' => 99.99,
    'plan' => 'pro'
]);

---

API vs Embed Script

You can track events via the API or the embed script. Here's when to use each:

Use API	Use Embed Script
Server-side events	Client-side interactions
Webhook triggers	Button clicks, page views
Background jobs	User-initiated actions
Batch processing	Real-time tracking

API Example (Server-Side)

// In your webhook handler
app.post('/webhooks/stripe', async (req, res) => {
  const { type, data } = req.body;

  if (type === 'checkout.session.completed') {
    await trackEvent(data.customer_id, 'purchase_completed', {
      amount: data.amount_total / 100,
      plan: data.metadata.plan
    });
  }
});

Embed Script Example (Client-Side)

// In your frontend code
document.getElementById('export-btn').addEventListener('click', () => {
  Cueflow.track('report_exported', {
    format: 'pdf',
    reportType: 'analytics'
  });
});

---

Best Practices

Event Naming

• Use descriptive, action-based names

• Stick to snake_case consistently

• Group related events with prefixes: onboarding_*, billing_*

Properties

• Keep properties flat (avoid nested objects)

• Use consistent property names across events

• Include relevant context without over-tracking

Timing

• Track events as close to the action as possible

• Use server-side tracking for critical events (purchases, signups)

• Use client-side tracking for UI interactions

Privacy

• Don't include PII in event properties

• Review what you're tracking for compliance

• Consider data retention policies