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.

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
});

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

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 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:

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.