30

Group

How it works

The group method is how you’ll associate a person with a group, like the company they work for or the school they attend. It’s a bit like an identify call, but for an organization instead of a person.

When you send a group call, you’ll include a groupId with an optional userId. Sending a userId associates the user with the group. A user can belong to multiple groups, so you can send group calls associating the same person with different groups.

When you send a group call, you can also include traits about the group. For example, if you use groups to represent companies, you might include the company’s industry, the number of employees, or the company’s billing date. You can send a group call without a userId if you simply want to update the traits for the group.

A typical call

A group call contains a groupId representing the group. You can also send an optional userId of the person you want to associate with the group and a traits object, which contains information about the group.

In the example below, you’ll notice that the group call looks a lot like an identify call! That’s because our JavaScript library automatically takes care of the userId (or anonymousId, if you haven’t identified a person yet) for you, associating the current user with the group.

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

If you use one of our server-side libraries, and you want to relate a person to a group, you’ll have to provide the userId or anonymousId yourself. Here’s an example from our NodeJS server-side library:

analytics.group({
  userId: '019mr8mf4r',
  groupId: '0e8c78ea9d97a7b8185e8632',
  traits: {
    name: "Acme",
    industry: "Technology",
    wile_e_coyote_accidents: 329,
    plan: "enterprise",
    total_billed: 830
  }
});

While this is the general shape of your call, our libraries actually capture much more information. See the full payload below.

The full payload

While your requests are typically short, our libraries capture much more information. This helps us provide context, not only for the group and the person you associate with the group, but the service you send the call from.

Customer.io and our libraries typically populate integrations and timestamp values as shown in the payload below. If you use our JavaScript or mobile libraries, they’ll also populate context for you. If you use our server-side libraries, you’ll need to populate context yourself.

See common fields for more information about context, integrations, and timestamps in source payloads.

{
  "userId": "97980cfea0067",
  "groupId": "0e8c78ea9d97a7b8185e8632,",
  "traits": {
    "name": "Acme",
    "industry": "Technology",
    "wile_e_coyote_accidents": 329,
    "plan": "enterprise,",
    "total_billed": 830
  },
  "integrations": {
    "All": true
  },
  "messageId": "022bb90c-bbac-11e4-8dfc-aa07a5b093db,",
  "timestamp": "2015-02-23T22:28:55.111Z,",
  "context": {
    "active": true,
    "ip": "8.8.8.8",
    "locale": "string",
    "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",
    "channel": "browser",
    "campaign": {
      "name": "string",
      "source": "string",
      "medium": "string",
      "term": "string",
      "content": "string"
    },
    "page": {
      "name": "string",
      "path": "string",
      "referrer": "string",
      "search": "string",
      "title": "string",
      "url": "string",
      "keywords": [
        "string"
      ]
    }
  },
  "anonymousId": "507f191e810c19729de860ea,",
  "channel": "browser,",
  "receivedAt": "2015-02-23T22:28:55.387Z,",
  "sentAt": "2015-02-23T22:28:55.111Z,",
  "type": "group",
  "version": 1.1
}

Group ID

A Group ID is a unique identifier, like a UUID or ULID, that represents the group in your database or backend.

Traits

Like people in Customer.io, groups can have traits. Group traits are things you know about a group that you pass along in any group call, like industry, employees, or website.

We’ve reserved the following traits. We handle these traits in special ways across destinations. You should only use reserved traits for their intended meanings.

Some destinations might represent these traits with slightly different names. For example, Mixpanel recognizes a $created trait when a user is first created, while Intercom recognizes the same trait as created_at. We attempt to handle all the destination-specific conversions for you automatically.

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.

You can pass reserved traits using camelCase or snake_case. For example, in JavaScript you can match the rest of your camel-case code by sending createdAt, while in Python you can match your snake-case code by sending created_at. That way the API never seems alien to your code base.