Segment Overview

Vitally's Segment integration can be used to sync the following Segment data into Vitally in real time:

Groups - Segment groups are imported as accounts in Vitally. All Segment group traits are attached to the Vitally account profiles.
Users - Segment users (from identify calls) are imported as users in Vitally. All Segment traits are attached to the Vitally user profiles.
Tracks - Segment track calls are imported as product events in Vitally. All Segment event properties are attached to the product event tracks in Vitally.

Enabling the Segment integration

How-To

How-To Visual

Navigate to Settings (⚙️) by selecting your Account Logo on the top left and under Operations select Integrations
Then select Segment (or via Quick Jump Mac: ⌘ + j Windows: Alt + j) to enable.
Select the Connect a Segment Source button. This will redirect you to Segment, where you'll be able to select the Segment source to connect to Vitally.
Once the Segment source is connected, Segment will redirect you back to Vitally, where you'll see a message like this: "We're waiting to receive a message from Segment."
⚠️ Before you can complete the setup, Vitally must receive at least one message from your connected Segment source.
This can take a few minutes, even if you're already sending messages. This delay is caused by Segment's CDN propagation.
Once we receive a single Segment message, you'll see the below and will be able to configure the rest of the integration: "We've received a message from your Segment account."

Step 3:

Step 4:

Step 6:

Creating Accounts from Segment

As Vitally is geared towards B2B companies, we must be able to associate each user to the account/customer they belong to. Segment provides 2 different APIs to achieve this result.

Default behavior

By default, if you do not use any of the options below (Group API vs Identify API), Vitally will associate the track to the account the user was last associated to. This typically works fine for customers, especially if you send a group call for the user each time they log in to their account or start a session (as a group call establishes the association between the user and the account).

Option #1: Group API (recommended)

The Group API enables you to identify which accounts or organizations your users belong to. We recommend using the Group API to create accounts in Vitally. It gives you direct control over account data, like industry, employee count, and plan. Plus, any new traits added to future group calls will automatically sync to the account—no extra setup needed.

A group call includes two main identifiers:

userId: refers to the user
groupId: refers to the specific account or organization

Here’s a JSON payload of a typical group call, with Segment's most common fields removed:

{ 
  "type": "group", 
  "groupId": "0e8c78ea9d97a7b8185e8632", 
  "traits": { 
     "name": "Initech", 
     "industry": "Technology", 
     "employees": 329, 
     "plan": "enterprise", 
     "total billed": 830 
    } 
}

🔍 The userId is the external ID in Vitally.

And here’s the corresponding JavaScript event that would generate the above payload:

analytics.group("0e8c78ea9d97a7b8185e8632", 
  { 
    name: "Initech", 
    industry: "Technology", 
    employees: 329, 
    plan: "enterprise"
  }
);

🔍 Based on the library you use, the syntax in the examples might be different. You can find library-specific documentation on the Segment's Sources Overview page.

If you use the group API, every call must include a name trait.

Option #2: Identify API

This is a dedicated API Segment provides that directly identifies your users. Since this API is meant to identify individual users of your product, and not necessarily the account the user belongs to, it is not recommended to use this API. The Group API is always a better option, but if you don't use the Group API, your Identify API calls must send along certain traits that specify the account.

Account name trait - A trait that identifies the (readable) name of the account the user belongs to (e.g. "Visa")
Account ID trait - A trait that specifies a unique ID for your accounts. Ideally, this value never changes for the account (e.g. visa.com, ed8fcc72-dbe5-4a9c-9d03-59e456462626). This trait should pretty much always be different than your name trait. If at all possible, the trait you select here should be the unique ID given to your accounts by your database.
Other account traits - Any traits attached to identify calls that actually relate to the account the user belongs to (e.g. the account's plan, subscription cost, industry). These traits will be attached to accounts in Vitally, allowing you to use them when analyzing accounts.

⚠️ The Account ID trait you select here is very important to unifying your Account data in Vitally. If you leverage our other integrations to track other Account data (e.g., Stripe), the ID you select here will also need to exist in those other tools for Vitally to properly unify your data under the right Account.

Preventing Account Associations Using Identify API

By default, Users identified through Segment identify calls will be automatically associated with their parent Accounts in Vitally. This is typically the desired behavior, as it ensures accurate event association and Account relationships.

However, if you don’t want Users linked to Accounts via identify calls, you can disable this by selecting the option not to link users to accounts.

⚠️ Important:

If you disable Account associations via identify calls, Users must still be linked to an Account through another integration.
If a User exists in Vitally without a parent Account (i.e., an "orphan User"), all event tracks associated with that User will be dropped and will not sync to Vitally.

Use this option only if you're managing Account associations through another integration (e.g., Salesforce or HubSpot).

Associating Tracks to Specific Accounts

If your users can belong to multiple accounts, you may have a need to specifically associate that user's tracks to the account they are logged into. To do so, you have a few options:

Use Context

Segment's context option supports setting groupId, and Segment's B2B SaaS spec recommends setting this for specific tracks. If you set the groupId field in your track context, Vitally will automatically associate the track to the account the groupId value references.

Use a Track Property to Reference the Account or Organization

Vitally offers granular control over how track events are linked to accounts or organizations. You can define a specific property from your track properties to indicate which account or organization the event should be associated with.

Here’s the payload of a typical track call (using an accountId property) with Segment's most common fields removed:

{ 
"type": "track", 
"event": "User Registered", 
"properties": { 
   "plan": "Pro Annual", 
   "accountType" : "Facebook",
   "accountId": 'ACCOUNT_EXTERNAL_ID'
  } 
}

And here’s the corresponding JavaScript event that would generate the above payload:

analytics.track("User Registered", { 
  plan: "Pro Annual", 
  accountType: "Facebook",
  accountId: 'ACCOUNT_EXTERNAL_ID'
});

⚠️ The Account or Organization ID property you input in Vitally from your track events must match exactly what's listed in Segment—including capitalization and formatting. For example, AccountId and accountId would be seen as different properties.

If you've input a track property to associate events to an account, Vitally will:

Search for an Account with the external ID value from the mapped track property
If found, associate the event with that Account
If not found, create a new Account with that external ID
By default, also associate the user with that Account

By default, Vitally associates both the track event and the user to the specified Account or Organization. If you want to link the event to the Account without linking the User, select the option to associate only the track to the Account:

Unlinking a User from an Account in Vitally

You can disassociate a User from an Account by passing in a field inside the company trait with remove: true in your identify calls.

analytics.identify({
  userId: '1',
  traits: {
    company: {
      id: 12345,
      remove: true
    }
  }
});

Ignore Events

Segment may send many events to Vitally, some of which may not be relevant. For this reason, you will want to "ignore" any events you don't want to track in Vitally.

There are two benefits to "Ignoring" an event:

Keeps your event list cleaner in the UI as there will be fewer data to sift through.
This enables us to process your data as quickly as possible as we are not processing data that is not relevant to you.

To update an Event Status go to: Settings > Events > Status column

FAQs

Q: Does my historical Segment data sync to Vitally when I enable the Segment integration?

A: Unfortunately not, but simply because Segment offers no APIs for integration partners to extract your historical data from Segment. However, for those on advanced plan tiers for Segment, Segment does offer a feature to "replay" your historical data to a connected destination. If you have access to that feature, you can use it to push your historical data from Segment to Vitally.

Q: When creating Users in Vitally from Segment, should I pass the name in two separate traits as first name and last name or one full name trait?

A: We recommend sending us the User's name from Segment as full name instead of two separate traits.