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}