Group

How it works

The group method is how you’ll associate a profile 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 profile.

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 profile 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 typical group call contains a groupId, userId, and traits.objectTypeId.

• The groupId is the identifier for the group. Often times this is a UUID or ULID, but it could be any string.
• Thetraits.objectTypeId represents the type of object in Customer.io. Customer.io supports different kinds of groups, called objects, with a type ID beginning at 1. For example, if you create two different kinds of objects called Companies and Accounts, they’d likely have objectTypeId values of 1 and 2. If you don’t provide an objectTypeId, we’ll assume that the object type is 1.
• The userId represents the profile you want to associate with the group.
• The traits object contains information about the group.

If you use our client-side JavaScript library, you’ll typically only provide an objectTypeId, groupId, and traits. The library will automatically take care of the userId (or anonymousId, if you haven’t identified a profile yet) for you, associating the current user with the group.

cioanalytics.group("0e8c78ea9d97a7b8185e8632", {
  objectTypeId: 2,
  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 profile to a group, you’ll have to provide the userId or anonymousId yourself. Here’s an example from our NodeJS server-side library:

cioanalytics.group({
  userId: '019mr8mf4r',
  groupId: '0e8c78ea9d97a7b8185e8632',
  traits: {
    objectTypeId: 2,
    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 profile 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": {
    "objectTypeId": 2,
    "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 profiles 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 data-out integrations. You should only use reserved traits for their intended meanings.

Some data-out integrations 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 these 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.

Groups are called objects in Customer.io

In Customer.io, we refer to groups as objects. The principle is the same: objects are things that your audience can belong to, like accounts, companies, and online classes. But there are a few differences:

1. You can have different kinds of objects! In Customer.io, we differentiate between objects using the traits.objectTypeId key.
2. You can set traits for the object itself, and for the relationship between the profile and the object. Items under traits are for the object, while items under traits.relationshipAttributes are for the relationship between the profile and the object.

Object type

You can have different kinds of objects in Customer.io. For example, you might have objects for online classes, schools, client companies, and so on. When you create a new object type, we’ll assign it an objectTypeId. This ID is a number that represents the kind of object you’re creating.

Your first object is objectTypeId 1, your second object is objectTypeId 2, and so on. In calls representing objects, you’ll send the object type to tell us what kind of object you want to create, update, or delete.

• For group calls, object type is represented by traits.objectTypeId.
• For track calls, object type is represented by properties.objectTypeId.

If you don’t provide traits.objectTypeId in a group call, we’ll assume that the object type is 1.

Object and relationship attributes

When you send a group call, you can set traits for the object itself, and for the relationship between the profile and the object. Items in the traits object are for the object, while items in the traits.relationshipAttributes object are for the relationship between the profile and the object.

For example, if you have a group representing a company, you might set the company’s name, industry, and employees in the traits object. You might also set the profile’s role in the company, the dateJoined, and the isPrimaryContact in the traits.relationshipAttributes object.

{
  "userId": "wileecoyote",
  "groupId": "0e8c78ea",
  "traits": {
    // determines the kind of object you're affecting
    "objectTypeId": 2,
    // these traits apply to the object
    "name": "Acme",
    "industry": "Technology",
    "employees": 329,
    // everything under relationshipAttributes applies to the
    // relationship between the person and the object
    "relationshipAttributes": {
      "role": "sponsor",
      "dateJoined": "2021-01-01",
      "isPrimaryContact": true
    }
  }
}

Deleting objects and relationships

You’ll use group calls to create and update objects and relationships. But what if you want to delete an object or a relationship?

We use special events to delete objects and relationships in Customer.io. These events are called semantic events. They let you send track calls with a specific event name to perform actions in Customer.io. For objects, that means you’ll send Delete Object and Delete Relationship to remove objects and relationships from Customer.io respectively.

Track calls are formatted differently from group calls. In this case, you’ll provide the userId at the top of the call, and your objectId (the groupId from your group calls!) in the properties object.

{
  "userId": "wileecoyote",
  "event": "Delete Object",
  "properties": {
    "objectId": "0e8c78ea",
    "objectTypeId": 2
  }
}