Track Event

POST /v1/user-journeys/events

Records a single user event. The event is added to the user’s timeline, and their profile’s lastSeenAt is updated. If the user doesn’t have a profile yet, a minimal one is created automatically.

Authentication

Header	Required	Value
X-API-Key	Yes	Your public key
Content-Type	Yes	application/json

Request Body

Field	Type	Required	Description
externalId	string	Yes	Your unique user identifier
category	string	Yes	Event category (see categories)
eventType	string	Yes	Specific event type (e.g., page_view, purchase, level_up)
sourceId	string	No	Reference ID (e.g., campaign ID, game mechanic ID)
points	integer	No	Points associated with this event (default: 0)
reference	string	No	Idempotency key to prevent duplicate events
metadata	object	No	Arbitrary event data
occurredAt	string	No	ISO 8601 timestamp (defaults to now)

Request Examples

cURL

curl -X POST https://api.gamifyhost.com/v1/user-journeys/events \
  -H "X-API-Key: pk_live_your_public_key" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "user_12345",
    "category": "CUSTOM",
    "eventType": "product_viewed",
    "metadata": {
      "productId": "prod_abc",
      "productName": "Premium Plan",
      "price": 29.99
    }
  }'

JavaScript

const response = await fetch('https://api.gamifyhost.com/v1/user-journeys/events', {
  method: 'POST',
  headers: {
    'X-API-Key': 'pk_live_your_public_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    externalId: 'user_12345',
    category: 'CUSTOM',
    eventType: 'product_viewed',
    metadata: {
      productId: 'prod_abc',
      productName: 'Premium Plan',
      price: 29.99,
    },
  }),
});

const data = await response.json();
console.log('Event tracked:', data.data.id);

Python

import requests

response = requests.post(
    "https://api.gamifyhost.com/v1/user-journeys/events",
    headers={
        "X-API-Key": "pk_live_your_public_key",
        "Content-Type": "application/json",
    },
    json={
        "externalId": "user_12345",
        "category": "CUSTOM",
        "eventType": "product_viewed",
        "metadata": {
            "productId": "prod_abc",
            "productName": "Premium Plan",
            "price": 29.99,
        },
    },
)

data = response.json()
print(f"Event tracked: {data['data']['id']}")

Go

payload := strings.NewReader(`{
    "externalId": "user_12345",
    "category": "CUSTOM",
    "eventType": "product_viewed",
    "metadata": {
        "productId": "prod_abc",
        "productName": "Premium Plan",
        "price": 29.99
    }
}`)

req, _ := http.NewRequest("POST", "https://api.gamifyhost.com/v1/user-journeys/events", payload)
req.Header.Set("X-API-Key", "pk_live_your_public_key")
req.Header.Set("Content-Type", "application/json")

resp, err := http.DefaultClient.Do(req)
if err != nil {
    log.Fatal(err)
}
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result["data"])

Response

Status: 200 OK

{
  "status": "success",
  "data": {
    "id": "e1f2a3b4-c5d6-7890-abcd-ef1234567890",
    "partnerId": "partner-uuid",
    "externalId": "user_12345",
    "environment": "LIVE",
    "category": "CUSTOM",
    "eventType": "product_viewed",
    "sourceId": "",
    "points": 0,
    "reference": "",
    "metadata": {
      "productId": "prod_abc",
      "productName": "Premium Plan",
      "price": 29.99
    },
    "occurredAt": "2025-03-05T14:22:00Z"
  }
}

Errors

Code	Message
400	Invalid request body (missing externalId, category, or eventType)
500	Failed to track event