Spec: Group

The Group API call is how you associate an individual user with a group, such as a company, organization, account, project, or team.

The Group call enables you to identify what account or organization your users are part of. There are two IDs that are relevant in a Group call: the userId, which belongs and refers to the user, and the groupId, which belongs and refers to the specific group. A user can be in more than one group which would mean different groupIds, but the user will only have one userId that is associated to each of the different groups. Keep in mind that not all platforms support multiple groups for a single user.

In addition to the groupId, which is how you’d identify the specific group or company, the group method receives traits that are specific to the group, like industry or number of employees for example, that belong to that specific account. Like the traits of an identify call, you can update these when you call the same trait with a different value.

When using the Group call, it’s helpful if you have accounts with multiple users.

Segment doesn't have an ungroup call

If you’re using a device-mode destination that has a method for ungrouping users, you can invoke it directly on the client side using Segment’s ready() method.

For cloud-mode destinations, you can create a Destination Function to ungroup users.

Here’s the payload of a typical Group call, with most common fields removed:

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

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

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

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

Beyond the common fields, the Group call takes the following fields:

Field Type Description
groupId required String A unique identifier for the group in your database. See the Group ID field docs for more detail.
traits optional Object Free-form dictionary of traits of the group, like email or name See the Traits field docs for a list of reserved trait names.
userId required; optional if anonymousID is set instead String Unique identifier for the user in your database. A userId or an anonymousId is required. See the Identities docs for more details.
anonymousId required; optional if userID is set instead String A pseudo-unique substitute for a User ID, for cases when you don’t have an absolutely unique identifier. A userId or an anonymousId is required. See the Identities docs for more details.

Example

Here’s a complete example of a Group call:

{
  "anonymousId": "507f191e810c19729de860ea",
  "channel": "browser",
  "context": {
    "ip": "8.8.8.8",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/40.0.2214.115 Safari/537.36"
  },
  "integrations": {
    "All": true,
    "Mixpanel": false,
    "Salesforce": false
  },
  "messageId": "022bb90c-bbac-11e4-8dfc-aa07a5b093db",
  "receivedAt": "2015-02-23T22:28:55.387Z",
  "sentAt": "2015-02-23T22:28:55.111Z",
  "timestamp": "2015-02-23T22:28:55.111Z",
  "traits": {
    "name": "Initech",
    "industry": "Technology",
    "employees": 329,
    "plan": "enterprise",
    "total billed": 830
  },
  "type": "group",
  "userId": "97980cfea0067",
  "groupId": "0e8c78ea9d97a7b8185e8632",
  "version": "1.1"
}

Create your own Group call

Use the following interactive code pen to see what your Group calls would look like with user-provided information:

Sample Group call

This field is required. Please enter a valid industry name, using only letters and hyphens. Please enter a valid number of employees. This field is required. Please enter only numbers in the Total Billed field.

Sample Group Call


Sample output goes here!

Identities

The User ID is a unique identifier for the user performing the actions. Check out the User ID docs for more detail.

The Anonymous ID can be any pseudo-unique identifier, for cases where you don’t know who the user is, but you still want to tie them to an event. Check out the Anonymous ID docs for more detail.

Note: In our browser and mobile libraries a User ID is automatically added from the state stored by a previous identify call, so you do not need to add it yourself. They will also automatically handle Anonymous IDs under the covers.

Group ID

A Group ID is the unique identifier which you recognize a group by in your own database. For example, if you’re using MongoDB it might look something like 507f191e810c19729de860ea.

Traits

Traits are pieces of information you know about a group that are passed along with the Group call, like employees or website.

Segment has reserved some traits that have semantic meanings for groups, and handles them in special ways. You should only use reserved traits for their intended meaning.

The following are the reserved traits Segment has standardized:

Trait Type Description
address Object Street address of a group. This should be a dictionary containing optional city, country, postalCode, state, or street.
avatar String URL to an avatar image for the group.
createdAt Date Date the group’s account was first created. Segment recommends ISO-8601 date strings.
description String Description of the group, like their personal bio.
email String Email address of group.
employees String Number of employees of a group, typically used for companies.
id String Unique ID in your database for a group.
industry String Industry a user works in, or a group is part of.
name String Name of a group.
phone String Phone number of a group.
website String Website of a group.
plan String Plan that a group is in.

Note: You might be used to some destinations recognizing special properties differently. For example, Mixpanel has a special track_charges method for accepting revenue. Luckily, you don’t have to worry about those inconsistencies. Just pass along revenue. Segment handles all of the destination-specific conversions for you automatically. Same goes for the rest of the reserved properties.

If you pass these values, on null will throw a NullPointerException. You may continue to set values inside the trait. If you do so, this would work the same as the rules do with NoSQL data. If you had set a value previously for a user and on the next request you sent the same value of that property as on null, it will be replaced by null, but if you do not send that property, the original value is persisted.

Traits are case-insensitive, so in JavaScript you can match the rest of your camel-case code by sending createdAt, and in Ruby you can match your snake-case code by sending created_at. That way the API never seems alien to your code base.

This page was last modified: 23 Jul 2024



Get started with Segment

Segment is the easiest way to integrate your websites & mobile apps data to over 300 analytics and growth tools.
or
Create free account