Track

When to call

Call track whenever a meaningful user action occurs. Every event has a name and optional properties that describe what happened.

• Lifecycle eventsSignup, account creation, subscription changes, cancellations.
• Feature engagementEach time a user interacts with a core or secondary product feature.
• Onboarding stepsCompletion of profile setup, first actions, guided tour steps.
• Viral actionsInvitations sent, referrals, team member additions.

Event naming conventions

Use a consistent object + past-tense verb format for all event names. This keeps your event taxonomy readable across teams and tools.

Endpoint

POST /api/track

Authentication

Pass your API key in the x-api-key header on every request. You can find your key in the ThriveStack dashboard under Settings → API Keys.

accept: */*
content-type: application/json
x-api-key: YOUR_API_KEY

Request body

Send an array containing one or more track objects.

Reserved properties

ThriveStack recognises the following property names and gives them special handling in revenue and growth analytics.

Standard events

These are the ThriveStack lifecycle events that power the bow-tie revenue model and growth dashboards. Instrument them to unlock the full platform.

Examples

Signup

curl --location 'https://api.app.thrivestack.ai/api/track' \
--header 'accept: */*' \
--header 'content-type: application/json' \
--header 'x-api-key: YOUR_API_KEY' \
--data '[
  {
    "event_name": "signed_up",
    "properties": {
      "user_email": "john.doe@acme.com",
      "user_name": "John Doe",
      "utm_campaign": "customer_success",
      "utm_medium": "referral",
      "utm_source": "twitter",
      "utm_term": "free_trial"
    },
    "user_id": "18f716ac-37a4-464f-adb7-3cc30032308c",
    "timestamp": "2024-01-15T10:30:00Z"
  }
]'

Account created

curl --location 'https://api.app.thrivestack.ai/api/track' \
--header 'accept: */*' \
--header 'content-type: application/json' \
--header 'x-api-key: YOUR_API_KEY' \
--data '[
  {
    "event_name": "account_created",
    "properties": {
      "account_domain": "acme.com",
      "account_id": "ac8db7ba-5139-4911-ba6e-523fd9c4704b",
      "account_name": "Acme Corporation"
    },
    "user_id": "18f716ac-37a4-464f-adb7-3cc30032308c",
    "timestamp": "2024-01-15T10:30:00Z",
    "context": {
      "group_id": "ac8db7ba-5139-4911-ba6e-523fd9c4704b"
    }
  }
]'

Feature engagement

curl --location 'https://api.app.thrivestack.ai/api/track' \
--header 'accept: */*' \
--header 'content-type: application/json' \
--header 'x-api-key: YOUR_API_KEY' \
--data '[
  {
    "event_name": "feature_used",
    "properties": {
      "feature_name": "export_report",
      "feature_type": "core",
      "user_role": "admin"
    },
    "user_id": "18f716ac-37a4-464f-adb7-3cc30032308c",
    "timestamp": "2024-01-15T10:30:00Z",
    "context": {
      "group_id": "ac8db7ba-5139-4911-ba6e-523fd9c4704b"
    }
  }
]'

Invite sent

curl --location 'https://api.app.thrivestack.ai/api/track' \
--header 'accept: */*' \
--header 'content-type: application/json' \
--header 'x-api-key: YOUR_API_KEY' \
--data '[
  {
    "event_name": "invite_sent",
    "properties": {
      "feature_name": "report",
      "invitee_email": "jane.doe@acme.com",
      "invitee_role": "Admin",
      "invitee_user_id": "ed1adb3a-9772-48ef-b620-e5e6d438fb82",
      "sub_feature_name": "export_report",
      "source_url": "https://acme.com/dashboard"
    },
    "user_id": "18f716ac-37a4-464f-adb7-3cc30032308c",
    "timestamp": "2024-01-15T10:30:00Z",
    "context": {
      "group_id": "ac8db7ba-5139-4911-ba6e-523fd9c4704b"
    }
  }
]'

Page visit

curl --location 'https://api.app.thrivestack.ai/api/track' \
--header 'accept: */*' \
--header 'content-type: application/json' \
--header 'x-api-key: YOUR_API_KEY' \
--data '[
  {
    "event_name": "page_visit",
    "properties": {
      "page_title": "what is acme",
      "page_url": "https://acme.com/what_is_acme",
      "page_path": "/what_is_acme",
      "page_referrer": "https://google.com",
      "utm_campaign": "summer_promotion",
      "utm_medium": "email",
      "utm_source": "newsletter"
    },
    "user_id": "18f716ac-37a4-464f-adb7-3cc30032308c",
    "timestamp": "2024-01-15T10:30:00Z",
    "context": {
      "group_id": "ac8db7ba-5139-4911-ba6e-523fd9c4704b",
      "device_id": "7d08298f",
      "session_id": "session_e2iukz3vduo",
      "source": "product"
    }
  }
]'

JavaScript (generic)

const myHeaders = new Headers();
myHeaders.append("accept", "*/*");
myHeaders.append("content-type", "application/json");
myHeaders.append("x-api-key", "YOUR_API_KEY");

const raw = JSON.stringify([
  {
    event_name: "feature_used",
    properties: {
      feature_name: "export_report",
      feature_type: "core",
      user_role: "admin"
    },
    user_id: "18f716ac-37a4-464f-adb7-3cc30032308c",
    timestamp: "2024-01-15T10:30:00Z",
    context: {
      group_id: "ac8db7ba-5139-4911-ba6e-523fd9c4704b"
    }
  }
]);

fetch("https://api.app.thrivestack.ai/api/track", {
  method: "POST",
  headers: myHeaders,
  body: raw,
  redirect: "follow"
})
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

Python (generic)

import requests
import json

url = "https://api.app.thrivestack.ai/api/track"

payload = json.dumps([
  {
    "event_name": "feature_used",
    "properties": {
      "feature_name": "export_report",
      "feature_type": "core",
      "user_role": "admin"
    },
    "user_id": "18f716ac-37a4-464f-adb7-3cc30032308c",
    "timestamp": "2024-01-15T10:30:00Z",
    "context": {
      "group_id": "ac8db7ba-5139-4911-ba6e-523fd9c4704b"
    }
  }
])
headers = {
  'accept': '*/*',
  'content-type': 'application/json',
  'x-api-key': 'YOUR_API_KEY'
}

response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)

Response

200 OK

{
  "success": true,
  "eventId": "evt_abc123xyz"
}

Error codes