API Documentation

Welcome to the Brazebee API documentation. Use our REST API to track customer events, monitor customer health, and drive proactive customer success workflows.

What is Brazebee?

Brazebee is a customer health monitoring platform that helps you track and analyze customer behavior through events. By integrating the Brazebee API into your application, you can:

Track customer events - Monitor user actions, page views, and system events
Calculate health scores - Automatically assess customer health based on event thresholds
Trigger workflows - Set up automated responses when customers enter at-risk states
Gain insights - Understand customer behavior patterns and adoption metrics

Getting Started

All API requests are made to:


https://api.brazebee.com/v1

API Key Required - All API requests require authentication using an API key. You can generate and manage your API keys in the Brazebee dashboard under Settings → Developers.

Authentication

Brazebee uses API keys for authentication. Include your API key in the x-api-key header of every request:


x-api-key: YOUR_API_KEY

Getting Your API Key

Log in to your Brazebee dashboard
Navigate to Settings → Developers
Click Create API Key to generate a new key
Copy and securely store your API key (it won’t be shown again)

Keep Your API Keys Secret - Never commit API keys to version control or expose them in client-side code. Store them securely as environment variables.

Event Tracking

Track Event

Send customer event data to Brazebee to track user behavior and calculate health scores.


POST /v1/track

Headers:


x-api-key: YOUR_API_KEY
Content-Type: application/json

Request Body:


{
  "event_key": "onboarding_complete",
  "company": {
    "id": "company_123",
    "name": "Acme Corporation",
    "payment_provider": "stripe",
    "payment_provider_id": "cus_abc123",
    "crm_provider": "salesforce",
    "crm_provider_id": "001500000ABCDEFGH",
    "industry": "Technology",
    "size": "50-100",
    "plan": "Enterprise"
  },
  "user": {
    "id": "user_456",
    "email": "john@acme.com",
    "name": "John Doe",
    "role": "Admin",
    "signup_date": "2024-01-15"
  },
  "data": {
    "step": 5,
    "completion_time_seconds": 120,
    "source": "web"
  },
  "timestamp": "2024-01-20T10:30:00Z"
}

Parameters:

Field	Type	Required	Description
`event_key`	string	Yes	The event identifier (must match an event configured in your Brazebee Event Settings)
`company`	object	Yes	Company/account information
`company.id`	string	Yes	Your unique identifier for this company
`company.name`	string	Yes	Company name
`company.payment_provider`	string	No	Payment provider (e.g., `stripe`, `paddle`, `chargebee`, `custom`)
`company.payment_provider_id`	string	No	Customer ID in the payment provider system
`company.crm_provider`	string	No	CRM platform name (e.g., `salesforce`, `hubspot`)
`company.crm_provider_id`	string	No	Account/Company ID in the CRM
`user`	object	No	User information (optional for system events)
`user.id`	string	Yes*	Your unique identifier for this user (*required if user object provided)
`user.email`	string	No	User’s email address
`user.name`	string	No	User’s full name
`data`	object	No	Custom event-specific data
`timestamp`	string	No	ISO 8601 timestamp (defaults to current time if omitted)

Event Keys - Before tracking events, you must configure them in your Brazebee dashboard under Events. The event_key must match a configured event, or the API will return a 404 error.

Response:


{
  "success": true,
  "event_key": "onboarding_complete",
  "accepted_at": "2024-01-20T10:30:05Z"
}

Custom Company and User Data

Brazebee allows you to send any additional custom fields in the company and user objects. This flexibility lets you track data specific to your business without predefined schemas.

Examples of Custom Data:


{
  "company": {
    "id": "company_123",
    "name": "Acme Corp",
    // Core fields above, custom fields below:
    "industry": "SaaS",
    "employee_count": 150,
    "plan": "Enterprise",
    "mrr": 5000,
    "contract_end_date": "2024-12-31",
    "csm_name": "Jane Smith",
    "region": "North America"
  },
  "user": {
    "id": "user_456",
    "email": "john@acme.com",
    "name": "John Doe",
    // Core fields above, custom fields below:
    "role": "Product Manager",
    "department": "Engineering",
    "signup_date": "2024-01-15",
    "last_login": "2024-01-20",
    "feature_flags": ["beta_access", "premium_features"],
    "onboarding_completed": true,
    "license_type": "professional"
  }
}

Schema-less Design - Add any custom fields you need without updating schemas. Brazebee automatically stores and indexes all custom data for filtering and analysis.

System Events (Without User)

For system-level events that aren’t tied to a specific user, omit the user object:


{
  "event_key": "api_limit_reached",
  "company": {
    "id": "company_123",
    "name": "Acme Corp",
    "payment_provider": "stripe",
    "payment_provider_id": "cus_abc123"
  },
  "data": {
    "limit_type": "api_calls",
    "current_usage": 10000,
    "limit": 10000,
    "timeframe": "monthly"
  }
}

Common System Event Types:

API rate limits reached
Storage limits exceeded
License capacity reached
Payment failures
Subscription changes
Security alerts

Example Requests

cURL


curl -X POST https://api.brazebee.com/v1/track \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_key": "value_action_complete",
    "company": {
      "id": "company_123",
      "name": "Acme Corp",
      "plan": "Enterprise"
    },
    "user": {
      "id": "user_456",
      "email": "john@acme.com",
      "name": "John Doe"
    },
    "data": {
      "action": "created_report",
      "duration_seconds": 45
    }
  }'

JavaScript / Node.js


const response = await fetch('https://api.brazebee.com/v1/track', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.BRAZEBEE_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    event_key: 'value_action_complete',
    company: {
      id: 'company_123',
      name: 'Acme Corp',
      plan: 'Enterprise'
    },
    user: {
      id: 'user_456',
      email: 'john@acme.com',
      name: 'John Doe'
    },
    data: {
      action: 'created_report',
      duration_seconds: 45
    }
  })
});
 
const result = await response.json();
console.log(result);

Python


import requests
import os
 
response = requests.post(
    'https://api.brazebee.com/v1/track',
    headers={
        'x-api-key': os.environ['BRAZEBEE_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'event_key': 'value_action_complete',
        'company': {
            'id': 'company_123',
            'name': 'Acme Corp',
            'plan': 'Enterprise'
        },
        'user': {
            'id': 'user_456',
            'email': 'john@acme.com',
            'name': 'John Doe'
        },
        'data': {
            'action': 'created_report',
            'duration_seconds': 45
        }
    }
)
 
print(response.json())

Ruby


require 'net/http'
require 'json'
 
uri = URI('https://api.brazebee.com/v1/track')
req = Net::HTTP::Post.new(uri)
req['x-api-key'] = ENV['BRAZEBEE_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  event_key: 'value_action_complete',
  company: {
    id: 'company_123',
    name: 'Acme Corp',
    plan: 'Enterprise'
  },
  user: {
    id: 'user_456',
    email: 'john@acme.com',
    name: 'John Doe'
  },
  data: {
    action: 'created_report',
    duration_seconds: 45
  }
}.to_json
 
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(req)
end
 
puts res.body

Rate Limiting

API requests are limited to 10,000 requests per hour per organization. The following headers are included in every response:

X-RateLimit-Limit - Maximum requests per hour
X-RateLimit-Remaining - Remaining requests in current window
X-RateLimit-Reset - Time when the rate limit resets (Unix timestamp)

Exceeding the rate limit will result in a 429 Too Many Requests error. Implement exponential backoff retry logic to handle rate limits gracefully.

Error Handling

The API uses standard HTTP status codes to indicate success or failure:

Status Code	Description
200	Success - Event tracked successfully
400	Bad Request - Invalid data or disabled event
401	Unauthorized - Missing or invalid API key
404	Not Found - Event key not configured in your settings
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Something went wrong on our end

Error Response Format


{
  "error": "Event setting not found for key: invalid_event",
  "details": [
    {
      "field": "event_key",
      "message": "Event must be configured in Event Settings before tracking"
    }
  ]
}

Common Errors

401 Unauthorized - Missing API Key


{
  "error": "API key required"
}

Solution: Include your API key in the x-api-key header.

401 Unauthorized - Invalid API Key


{
  "error": "Invalid API key"
}

Solution: Verify your API key is correct and active in Settings → Developers.

404 Not Found - Event Not Configured


{
  "error": "Event setting not found for key: onboarding_start"
}

Solution: Configure the event in your Brazebee dashboard under Events before tracking it.

400 Bad Request - Event Disabled


{
  "error": "Event setting is disabled for key: deprecated_event"
}

Solution: Enable the event in your Event Settings or use a different event key.

400 Bad Request - Invalid Data


{
  "error": "Invalid data",
  "details": [
    {
      "path": ["company", "id"],
      "message": "Required"
    },
    {
      "path": ["user", "email"],
      "message": "Invalid email"
    }
  ]
}

Solution: Check the validation errors and ensure required fields are provided with correct data types.

Best Practices

1. Use Environment Variables

Never hardcode API keys. Use environment variables:


// ✅ Good
const apiKey = process.env.BRAZEBEE_API_KEY;
 
// ❌ Bad
const apiKey = 'bzb_1234567890abcdef';

2. Batch Events When Possible

If tracking multiple events, consider batching them with a small delay to avoid rate limits:


// Use a queue system for high-volume tracking
const eventQueue = [];
 
function trackEvent(event) {
  eventQueue.push(event);
  
  // Flush queue every 100ms
  if (!flushTimer) {
    flushTimer = setTimeout(flushEvents, 100);
  }
}

3. Handle Errors Gracefully

Don’t let tracking errors break your application:


try {
  await trackEvent({ event_key: 'user_action', ... });
} catch (error) {
  console.error('Event tracking failed:', error);
  // Continue application flow
}

4. Include Rich Context

Send as much relevant context as possible:


{
  event_key: 'feature_used',
  company: { 
    id: 'company_123',
    name: 'Acme Corp',
    plan: 'Enterprise',      // Plan information
    mrr: 5000,               // Revenue data
    csm: 'Jane Smith'        // Account owner
  },
  user: {
    id: 'user_456',
    email: 'john@acme.com',
    role: 'Admin',           // User role
    department: 'Engineering' // Team context
  },
  data: {
    feature: 'advanced_analytics',
    session_duration: 1200,
    actions_taken: 15
  }
}

5. Use Consistent IDs

Always use the same ID format for companies and users across all events:


// ✅ Good - consistent IDs
company: { id: 'company_123' }  // Always use the same ID
 
// ❌ Bad - mixing ID formats
company: { id: 'company_123' }  // First event
company: { id: '123' }          // Second event (different ID!)

Webhook Integration

When customer health scores change or thresholds are crossed, Brazebee can send webhook notifications to your application. Configure webhooks in Settings → Developers → Webhooks.

Webhook payloads include:


{
  "event": "health_score_changed",
  "company": {
    "id": "company_123",
    "name": "Acme Corp",
    "health_status": "At Risk",
    "previous_status": "Healthy"
  },
  "timestamp": "2024-01-20T10:30:00Z",
  "triggers": [
    {
      "flag": "Complete Value Action",
      "status": "At Risk",
      "threshold": "Less than 5 times in 7 days"
    }
  ]
}

Support

Need help integrating Brazebee?

Documentation: docs.brazebee.com
Email: support@brazebee.com
Discord: Join our community
GitHub: Report an issue

Changelog

v1 (Current)

Initial release
Event tracking endpoint
Custom company and user data support
Health score calculation
Webhook integrations