Batch Track Events

POST /v1/user-journeys/track

Records multiple events in a single request. Ideal for SDK auto-tracking (page views, session events) or batch imports. Accepts up to 100 events per request.

Authentication

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

Request Body

Field	Type	Required	Description
events	array	Yes	Array of event objects (1–100 items)

Each event object has the same fields as Track Event:

Field	Type	Required	Description
externalId	string	Yes	Your unique user identifier
category	string	Yes	Event category
eventType	string	Yes	Specific event type
sourceId	string	No	Reference ID
points	integer	No	Points associated (default: 0)
reference	string	No	Idempotency key
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/track \
  -H "X-API-Key: pk_live_your_public_key" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "externalId": "user_12345",
        "category": "PAGE_VIEW",
        "eventType": "page_view",
        "metadata": { "url": "/products", "referrer": "/home" }
      },
      {
        "externalId": "user_12345",
        "category": "SESSION",
        "eventType": "session_start",
        "metadata": { "userAgent": "Mozilla/5.0..." }
      },
      {
        "externalId": "user_67890",
        "category": "CUSTOM",
        "eventType": "button_click",
        "metadata": { "buttonId": "cta_signup" }
      }
    ]
  }'

JavaScript

const response = await fetch('https://api.gamifyhost.com/v1/user-journeys/track', {
  method: 'POST',
  headers: {
    'X-API-Key': 'pk_live_your_public_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    events: [
      {
        externalId: 'user_12345',
        category: 'PAGE_VIEW',
        eventType: 'page_view',
        metadata: { url: '/products', referrer: '/home' },
      },
      {
        externalId: 'user_12345',
        category: 'SESSION',
        eventType: 'session_start',
        metadata: { userAgent: navigator.userAgent },
      },
    ],
  }),
});

const data = await response.json();
console.log(`Tracked ${data.tracked} events`);

Python

import requests

response = requests.post(
    "https://api.gamifyhost.com/v1/user-journeys/track",
    headers={
        "X-API-Key": "pk_live_your_public_key",
        "Content-Type": "application/json",
    },
    json={
        "events": [
            {
                "externalId": "user_12345",
                "category": "PAGE_VIEW",
                "eventType": "page_view",
                "metadata": {"url": "/products"},
            },
            {
                "externalId": "user_12345",
                "category": "SESSION",
                "eventType": "session_start",
            },
        ]
    },
)

data = response.json()
print(f"Tracked {data['tracked']} events")

Response

Status: 200 OK

{
  "status": "success",
  "tracked": 3
}

Response Fields

Field	Type	Description
status	string	"success"
tracked	integer	Number of events successfully tracked

Errors

Code	Message
400	Invalid request body (missing events array or exceeds 100 items)
500	Failed to batch track events