Documentation

Basic Usage

// JavaScript/TypeScript
// This is a standard HTTP API - you can convert it to any language (Python, etc.)
const response = await fetch('https://api.channelstack.dev/v1/track', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    api_key: 'YOUR_API_KEY_HERE', // Replace with 'key_...'
    event: 'signed_up',
    email: 'user@example.com', // Raw email - we handle hashing
    // See https://channelstack.dev/docs/events#fields for all fields
    // Tip: Add Click IDs to significantly improve ad performance
  }),
})

Field Reference

Include additional fields to improve match rates and attribution accuracy across ad platforms. All fields except api_key and event are optional.

Complete Example

Here's a complete example with all recommended fields:

const response = await fetch('https://api.channelstack.dev/v1/track', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    // Required
    api_key: 'key_...',
    event: 'purchase_completed',
    
    // User identification
    email: 'john.doe@example.com',
    phone: '+15551234567',
    distinct_id: 'user_123',
    first_name: 'John',
    last_name: 'Doe',
    city: 'San Francisco',
    state: 'CA',
    zip: '94102',
    country: 'US',
    
    // Purchase data
    value: 149.99,
    currency: 'USD',
    order_id: 'ord_abc123',
    
    // Click IDs (if available)
    gclid: 'CjwKCAjw...',  // From URL parameter
    fbc: '_fbc.1.1554...',  // From cookie
    fbp: '_fbp.1.1554...',  // From cookie
    
    // Event metadata
    event_id: 'evt_unique123',
    source_url: 'https://example.com/checkout',
    
    // Privacy
    consent: true,
    
    // Any custom properties
    product_category: 'electronics',
    coupon_used: 'SAVE20'
  }),
})

Privacy & Security

• All PII (email, phone, name, address) is automatically hashed with SHA-256 before sending to ad platforms
• Server automatically captures and anonymizes IP addresses from request headers for privacy compliance
• User agent and referrer are automatically captured from request headers (not sent in request body)
• Set consent: false to prevent data from being sent to ad platforms (GDPR compliance)
• We never store raw PII - only hashed values
• All data transmission uses HTTPS encryption

Response Format

// Success response
{
  "success": true,
  "eventId": "evt_unique123",
  "message": "Event recorded successfully"
}

// Error response
{
  "error": "Invalid API key",
  "code": 401
}