Events API

Track conversion events for referral attribution.

Events are actions taken by referred users that can trigger rewards. Common events include signups, purchases, and custom actions.

POST/v1/events

Track a conversion event. If the event matches a campaign's reward trigger, rewards will be processed.

Parameters

Name	Type	Required	Description
type	string	Required	Event type: signup, purchase, or custom event name
userId	string	Required	The referred user's ID
referralCode	string	Optional	The referral code used (if known)
metadata	object	Optional	Event-specific data (amount, orderId, etc.)
idempotencyKey	string	Optional	Unique key to prevent duplicate processing

Request Body

{
  "type": "purchase",
  "userId": "user_456",
  "referralCode": "abc123",
  "metadata": {
    "amount": 99.99,
    "currency": "USD",
    "orderId": "order_789"
  },
  "idempotencyKey": "purchase_order_789"
}

Response

{
  "id": "evt_xxxxx",
  "type": "purchase",
  "userId": "user_456",
  "referralCode": "abc123",
  "attributed": true,
  "referrerId": "user_123",
  "campaignId": "camp_xxxxx",
  "rewardTriggered": true,
  "createdAt": "2024-01-15T10:30:00Z"
}

Use server-side tracking for purchases

For purchase and other high-value events, always track from your server using your Secret API Key. This prevents users from spoofing events.

GET/v1/events

List events with optional filtering.

Parameters

Name	Type	Required	Description
userId	string	Optional	Filter by user ID
referralCode	string	Optional	Filter by referral code
type	string	Optional	Filter by event type
limit	number	Optional	Max results (default 20, max 100)
cursor	string	Optional	Pagination cursor

Response

{
  "data": [
    {
      "id": "evt_xxxxx",
      "type": "purchase",
      "userId": "user_456",
      "referralCode": "abc123",
      "attributed": true,
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "nextCursor": "evt_yyyyy",
  "total": 42
}