Track Call

The track call records that a user performed a specific action. These events form the foundation of engagement scoring and feature adoption analysis in Accoil.

Event name only -- no properties

Accoil accepts only the event name in a track call. Event properties (metadata, dimensions, custom fields) are not accepted and will be ignored. If you need to associate contextual data with a user or account, use identify or group traits instead.

When to fire a track call

Fire a track call whenever a user performs a meaningful action in your product:

Creating, editing, or deleting core objects (reports, projects, tasks)
Completing key workflows (onboarding, setup, export)
Account-level actions (inviting a team member, upgrading a plan)
Feature engagement (using a specific tool or integration)

Do not track low-value interactions like page views, hovers, or scroll events. Focus on actions that signal real product engagement.

Required fields

Field	Type	Description
`userId`	string	The unique identifier of the user who performed the action.
`event`	string	The name of the event. Use `Object_Verb` format in `Title_Case`.
`timestamp`	string (ISO 8601)	When the event occurred. Defaults to current UTC time if omitted.

Naming convention: Object_Verb in Title_Case

Consistent event naming is critical. Accoil recommends the Object_Verb format with Title_Case and underscore separators.

The pattern is: what was acted on + what happened to it.

Pattern	Example	Description
`Object_Verb`	`Report_Created`	A report was created
`Object_Verb`	`Team_Member_Invited`	A team member was invited
`Object_Verb`	`Account_Upgraded`	An account was upgraded

Rules

Title_Case with underscores: Report_Created, not report_created or reportCreated
Past tense verbs: Created, Deleted, Updated, not Create, Delete, Update
No dynamic values: Report_Created, not Report_Created_2025 or Report_Created_Weekly
No properties in the name: Report_Exported, not Report_Exported_PDF

Common events

Event	Description
`Account_Created`	A new account was created
`User_Signed_Up`	A new user registered
`User_Logged_In`	A user started a session
`Report_Created`	A user created a report
`Report_Exported`	A user exported a report
`Team_Member_Invited`	A user invited someone to the account
`Account_Upgraded`	An account upgraded its plan
`Account_Downgraded`	An account downgraded its plan
`Account_Canceled`	An account was canceled
`Integration_Connected`	A user connected an external integration
`Project_Created`	A user created a new project
`Dashboard_Viewed`	A user viewed a dashboard

Example payload

{
  "userId": "user_12345",
  "event": "Report_Created",
  "timestamp": "2025-01-28T12:00:00Z"
}

cURL example (v2)

curl -X POST https://in.accoil.com/v2/track \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic YOUR_API_KEY" \
  -d '{
    "userId": "user_12345",
    "event": "Report_Created",
    "timestamp": "2025-01-28T12:00:00Z"
  }'

The API returns 202 Accepted. Processing happens asynchronously.

Best practices

Send identify and group first. Ensure the user and account exist in Accoil before recording events. Events against unknown users are still accepted but cannot be fully attributed until an identify call arrives.
Be selective. Track 10-30 meaningful events, not hundreds. Focus on actions that correlate with product value and engagement.
Use consistent naming. Agree on naming conventions with your team before instrumenting. Inconsistent names (e.g., Report_Created vs Created_Report vs report.created) fragment your data.
Avoid encoding data in event names. Since properties are not supported, it may be tempting to create events like Report_Created_PDF or Report_Created_CSV. Resist this -- it creates event sprawl. Use a single Report_Exported event instead.
Document your events. Maintain a shared event dictionary that lists every event name, what triggers it, and who owns the instrumentation.

How Accoil Works -- the three-call model overview
Identify Call -- creating user profiles
Group Call -- linking users to accounts
Snapshot Metrics -- tracking counts and state, not just actions

Track Call

On this page