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:

groupIdrequiredStringA unique identifier for the group in your database.

See the Group ID field docs for more detail

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

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


Here’s a complete example of a group call:

  "anonymousId": "507f191e810c19729de860ea",
  "channel": "browser",
  "context": {
    "ip": "",
    "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"


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

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.

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.

Questions? Need help? Contact us!
Can we improve this doc?
Email us: docs-feedback@segment.com!