You're in the right place! Segment documentation is now part of Twilio Docs. The content you are used to is still here—just in a new home with a refreshed look.

Spec: B2B SaaS

This guide explains how B2B SaaS companies should send core user and account lifecycle data to Segment.

Overview

Most B2B SaaS companies have a few common, core lifecycle events for users and accounts. We understand that account hierarchies can be unique and complex, but by following this spec you can take advantage of account-based tools on Segment platform, and B2B SaaS data products by Segment.

Events

The B2B SaaS category has the following semantic events:

Account Created

This event should be sent when a new account is created.

Properties

This event supports the following semantic properties:

Property	Type	Description
`account_name`	String	The name of the account being created.
`context.groupId`	String	The id of the account being created.

Example

1{
2  "userId": "019mr8mf4r",
3  "type": "track",
4  "event": "Account Created",
5  "properties": {
6    "account_name": "Initech"
7  },
8  "context": {
9    "groupId": "acct_123"
10  }
11}

Account Deleted

This event should be sent when an account is deleted.

Properties

This event supports the following semantic properties:

Property	Type	Description
`account_name`	String	The name of the account being deleted.
`context.groupId`	String	The id of the account being deleted.

Example

1{
2  "userId": "019mr8mf4r",
3  "type": "track",
4  "event": "Account Deleted",
5  "properties": {
6    "account_name": "Initech"
7  },
8  "context": {
9    "groupId": "acct_123"
10  }
11}

Signed Up

This event should be sent when a user signs up for your service.

(success)

Best practice

Segment's best practice is to use an "Object-Action" naming convention, which in this case would be "User Signed Up". However, because in the B2B case this may not be a specific user, we omit that noun in our example. You may include or omit it as needed for your implementation.

Properties

This event supports the following semantic properties:

Property	Type	Description
`type`	String	The type of signup, e.g. invited, organic.
`first_name`	String	The first name of the user.
`last_name`	String	The last name of the user.
`email`	String	The email of the user.
`phone`	String	The phone number of the user.
`username`	String	The username of the user.
`title`	String	The title of the user.
`context.groupId`	String	The id of the account the user is joining.

Example

1{
2  "userId": "019mr8mf4r",
3  "type": "track",
4  "event": "Signed Up",
5  "properties": {
6    "type": "organic",
7    "first_name": "Peter",
8    "last_name": "Gibbons",
9    "email": "pgibbons@example.com",
10    "phone": "410-555-9412",
11    "username": "pgibbons",
12    "title": "Mr"
13  },
14  "context": {
15    "groupId": "acct_123"
16  }
17}

Signed In

This event should be sent when a user signs in to your service.

(success)

Best practice

Segment's best practice is to use an "Object-Action" naming convention, which in this case would be "User Signed In". However, because in the B2B case this may not be a specific user, we omit that noun in our example. You may include or omit it as needed for your implementation.

Properties

This event supports the following semantic properties:

Property	Type	Description
`username`	String	The username of the user signing in.
`context.groupId`	String	The id of the account associated with the user signing in.

Example

1{
2  "userId": "019mr8mf4r",
3  "type": "track",
4  "event": "Signed In",
5  "properties": {
6    "username": "pgibbons"
7  },
8  "context": {
9    "groupId": "acct_123"
10  }
11}

Signed Out

This event should be sent when a user signs out for your service. You should also call analytics.reset() to refresh the cookie when a Signed Out event occurs.

(success)

Best practice

Segment's best practice is to use an "Object-Action" naming convention, which in this case would be "User Signed Out". However, because in the B2B case this may not be a specific user, we omit that noun in our example. You may include or omit it as needed for your implementation.

Properties

This event supports the following semantic properties:

Property	Type	Description
`username`	String	The username of the user signing out.
`context.groupId`	String	The id of the account associated with the user signing out.

Example

1{
2  "userId": "019mr8mf4r",
3  "type": "track",
4  "event": "Signed Out",
5  "properties": {
6    "username": "pgibbons"
7  },
8  "context": {
9    "groupId": "acct_123"
10  }
11}

Invite Sent

This event should be sent when a user invites another user.

Properties

This event supports the following semantic properties:

Property	Type	Description
`invitee_email`	String	The email address of the person receiving the invite.
`invitee_first_name`	String	The first name of the person receiving the invite.
`invitee_last_name`	String	The last name of the person receiving the invite.
`invitee_role`	String	The permission group for the person receiving the invite.
`context.groupId`	String	The id of the account the person is being invited to.

Example

1{
2  "userId": "019mr8mf4r",
3  "type": "track",
4  "event": "Invite Sent",
5  "properties": {
6    "invitee_email": "pgibbons@example.com",
7    "invitee_first_name": "Peter",
8    "invitee_last_name": "Gibbons",
9    "invitee_role": "Owner"
10  },
11  "context": {
12    "groupId": "acct_123"
13  }
14}

Account Added User

This event should be sent when a user is added to a group.

Properties

This event supports the following semantic properties:

Property	Type	Description
`role`	String	The permission group for this user in this account.
`context.groupId`	String	The id of the account the user is being added to.

Example

1{
2  "userId": "019mr8mf4r",
3  "type": "track",
4  "event": "Account Added User",
5  "properties": {
6    "role": "Owner"
7  },
8  "context": {
9    "groupId": "acct_123"
10  }
11}

Account Removed User

This event should be sent when a user is removed from a group or account.

Properties

This event supports the following semantic properties:

Property	Type	Description
`context.groupId`	String	The id of the account the user is being removed from.

Example

1{
2  "userId": "019mr8mf4r",
3  "type": "track",
4  "event": "Account Removed User",
5  "properties": {},
6  "context": {
7    "groupId": "acct_123"
8  }
9}

Trial Started

This event should be sent when a trial is started.

Properties

This event supports the following semantic properties:

Property	Type	Description
`trial_start_date`	Date	The date when the trial starts. It is an ISO-8601 date string.
`trial_end_date`	Date	The date when the trial ends. It is an ISO-8601 date string.
`trial_plan_name`	String	The name of the plan being trialed.
`context.groupId`	String	The id of the account the trial is associated with.

Example

1{
2  "userId": "019mr8mf4r",
3  "type": "track",
4  "event": "Trial Started",
5  "properties": {
6    "trial_start_date": "2018-08-28T04:09:47Z",
7    "trial_end_date": "2018-09-20T04:09:47Z",
8    "trial_plan_name": "Business"
9  },
10  "context": {
11    "groupId": "acct_123"
12  }
13}

Trial Ended

This event should be sent when a trial ends.

Properties

This event supports the following semantic properties:

Property	Type	Description
`trial_start_date`	Date	The date when the trial starts. It is an ISO-8601 date string.
`trial_end_date`	Date	The date when the trial ends. It is an ISO-8601 date string.
`trial_plan_name`	String	The name of the plan being trialed.
`context.groupId`	String	The id of the account the trial is associated with.

Example

1{
2  "userId": "019mr8mf4r",
3  "type": "track",
4  "event": "Trial Ended",
5  "properties": {
6    "trial_start_date": "2018-08-28T04:09:47Z",
7    "trial_end_date": "2018-09-20T04:09:47Z",
8    "trial_plan_name": "Business"
9  },
10  "context": {
11    "groupId": "acct_123"
12  }
13}