Spec: Group

The group API call is how you associate an individual user with a group—be it a company, organization, account, project, team or whatever other crazy name you came up with for the same concept!

A user can be in more than one group; however, not all platforms support multiple groups. It also lets you record custom traits about the group, like industry or number of employees. Calling group is a slightly more advanced feature, but 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:

FieldTypeDescription
groupId requiredStringA unique identifier for the group in your database.

See the Group ID field docs for more detail

traits optionalObjectFree-form dictionary of traits of the group, like email or name

See the Traits field docs for a list of reserved trait names

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"
}

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 ID’s 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.

We’ve reserved some traits that have semantic meanings for groups, and we handle them in special ways. You should only use reserved traits for their intended meaning.

The following are the reserved traits we have standardized:

TraitTypeDescription
addressObjectStreet address of a group

This should be a dictionary containing optional city, country, postalCode, state or street.

avatarStringURL to an avatar image for the group
createdAtDateDate the group’s account was first created

We recommend ISO-8601 date strings, but also accept Unix timestamps for convenience.

descriptionStringDescription of the group, like their personal bio
emailStringEmail address of group
employeesStringNumber of employees of a group, typically used for companies
idStringUnique ID in your database for a group
industryStringIndustry a user works in, or a group is part of
nameStringName of a group
phoneStringPhone number of a group
websiteStringWebsite of a group
planStringPlan 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 us revenue. We’ll handle all of the destination-specific conversions for you automatically. Same goes for the rest of the reserved properties.

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.


If you have any questions or see anywhere we can improve our documentation, please let us know or kick off a conversation in the Segment Community!