Analytics API - Track

Track your account or users' product activity with the /track endpoint

Replace {subdomain} in the endpoint below with your Vitally subdomain.

You can find your subdomain in the URL used to log into Vitally (i.e., https://yoursubdomain.vitally.io

Create a product event

POST https://{subdomain}.api.vitally.io/analytics/v1/track

This endpoint will create a product event in Vitally based on the (optional) messageId parameter.

Headers

Name Type Description

Name	Type	Description
Authorization*	string	Set to `Basic [YOUR_API_TOKEN]`
Content-Type*	string	Set to `application/json`

Authorization*

string

Set to Basic [YOUR_API_TOKEN]

Content-Type*

string

Set to application/json

Request Body

Name Type Description

Name	Type	Description
userId	string	Required if `accountId` is not specified. If this is a product event performed by a user, set this to the unique ID of that user. If this is instead an event to just be associated with a specific (business) account, set `accountId` or `organizationId` exclusively.
accountId	string	Required if neither `userId` or `organizationId` are specified. If left blank, Vitally will automatically set this to the ID of the last account the user was associated to. If this is an account-level event (e.g. a payment event) that's not associated with a specific user, set this to the unique ID of the account and leave `userId` empty. If your users belong to multiple accounts, we recommend setting both `userId` and `accountId`. This way, if the event is occurring within a specific account, Vitally will ensure it is associated to the right account.
event*	string	The name of the product event (e.g. "Button Clicked", "Integration Enabled", etc)
properties*	object	A JSON object containing the properties of the event. Required but can be left empty if no properties needed.
timestamp	string	Required if `messageId` is not included. An ISO 8601 UTC date string - i.e. `'2018-01-01T00:00:00Z'` - for the time that the message was sent. If `timestamp`is not included, it will default to the time the API server receives your message.
messageId	string	Required if `timestamp` is not included. A unique ID for this message, used to de-duplicate messages. We recommend sending `messageId`, but if it is not included and `timestamp`is included, it will be set to a hash of the message.
organizationId	string	Required if neither `userId` or `accountId` are specified. Only supported if your account has organizations enabled If this is an organization-level event (e.g. a payment event) that's not associated with a specific user, set this to the unique ID of the organization and leave `userId` and `accountId` empty. If your users belong to multiple organizations, we recommend setting both `userId` and `organizationId`. This way, if the event is occurring within a specific organization, Vitally will ensure it is associated to the right organization.

userId

string

Required if accountId is not specified. If this is a product event performed by a user, set this to the unique ID of that user. If this is instead an event to just be associated with a specific (business) account, set accountId or organizationId exclusively.

accountId

string

Required if neither userId or organizationId are specified. If left blank, Vitally will automatically set this to the ID of the last account the user was associated to. If this is an account-level event (e.g. a payment event) that's not associated with a specific user, set this to the unique ID of the account and leave userId empty. If your users belong to multiple accounts, we recommend setting both userId and accountId. This way, if the event is occurring within a specific account, Vitally will ensure it is associated to the right account.

event*

string

The name of the product event (e.g. "Button Clicked", "Integration Enabled", etc)

properties*

object

A JSON object containing the properties of the event. Required but can be left empty if no properties needed.

timestamp

string

Required if messageId is not included. An ISO 8601 UTC date string - i.e. '2018-01-01T00:00:00Z' - for the time that the message was sent. If timestampis not included, it will default to the time the API server receives your message.

messageId

string

Required if timestamp is not included. A unique ID for this message, used to de-duplicate messages. We recommend sending messageId, but if it is not included and timestampis included, it will be set to a hash of the message.

organizationId

string

Required if neither userId or accountId are specified. Only supported if your account has organizations enabled If this is an organization-level event (e.g. a payment event) that's not associated with a specific user, set this to the unique ID of the organization and leave userId and accountId empty. If your users belong to multiple organizations, we recommend setting both userId and organizationId. This way, if the event is occurring within a specific organization, Vitally will ensure it is associated to the right organization.

{"message":"Success."}

Expand the POST box above for full specs

Example

An example curl request describing a product event would look like:

curl -X POST https://{subdomain}.api.vitally.io/analytics/v1/track \
  -H "Authorization: Basic [your token]" \
  -H "Content-Type: application/json" \
  -d '{
  "userId": "32",
  "event": "view-customer-events",
  "properties": {
    "accountId": "123456",
    "eventId": "43212"
  },
  "messageId": "7ac1c682-a54b-4d0d-9f56-d6d3618f4915",
  "timestamp": "2018-05-15T12:31:12.123Z"
}'

PreviousAnalytics API - User NextAnalytics API - Batch

Last updated 5 months ago