Group

Updated

 See our API documentation for code samples

This page can help you better understand when and how to use this API method. But, if you already know how it works and are ready to get started, you can go straight to our Data Pipelines API documentation and start writing code.

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.

 In Journeys, we typically refer to groups as objects

If you use Customer.io as a destination, you’ll see your groups under Custom Objects by default, though you can rename your object type.

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
}
    • active boolean

      Whether a user is active.

      This is usually used when you send an .identify() call to update the traits independently of when you’ve “last seen” a user.

    • channel string
      The channel the event originated from.

      Accepted values:browser,server,mobile

    • ip string
      The user’s IP address. This isn’t captured by our libraries, but by our servers when we receive client-side events (like from our JavaScript source).
    • locale string
      The locale string for the current user, e.g. en-US.
    • userAgent string
      The user agent of the device making the request
      • content string
      • medium string
        The type of traffic a person/event originates from, like email, or referral.
      • name string
        The campaign name.
      • source string
        The source of traffic—like the name of your email list, Facebook, Google, etc.
      • term string
        The keyword term(s) a user came from.
      • Additional UTM Parameters* string
      • keywords array of [ strings ]
        A list/array of keywords describing the page’s content. The keywords are likely the same as, or similar to, the keywords you would find in an HTML meta tag for SEO purposes. This property is mainly used by content publishers that rely heavily on pageview tracking. This isn’t automatically collected.
      • name string
        The name of the page. Reserved for future use.
      • path string
        The path portion of the page’s URL. Equivalent to the canonical path which defaults to location.pathname from the DOM API.
      • referrer string
        The previous page’s full URL. Equivalent to document.referrer from the DOM API.
      • search string
        The query string portion of the page’s URL. Equivalent to location.search from the DOM API.
      • title string
        The page’s title. Equivalent to document.title from the DOM API.
      • url string
        A page’s full URL. We first look for the canonical URL. If the canonical URL is not provided, we’ll use location.href from the DOM API.
  • groupId string
    Required ID of the group
    • Enabled/Disabled integrations* boolean
  • messageId string
    A unique identifier for a Data Pipelines event, ensuring that each individual event is unique.
  • objectTypeId string

    If you use Customer.io Journeys as a destination, this value is the type of group/object your group belongs to; object type IDs are stringified integers. If you don’t include this value, we assume the object type ID is 1. See objects in Customer.io Journeys for more information.

    You can include this value as objectTypeId at the top level of your payload or as object_type_id in the traits object.

  • receivedAt string  (date-time)
    The ISO-8601 timestamp when Data Pipelines receives an event.
  • sentAt string  (date-time)
    The ISO-8601 timestamp when a library sends an event to Data Pipelines.
  • timestamp string  (date-time)
    The ISO-8601 timestamp when the event originally took place. This is mostly useful when you backfill data past events. If you’re not backfilling data, you can leave this field empty and we’ll use the current time or server time.
    • object_type_id string

      If you use Customer.io Journeys as a destination, this value is the type of group/object your group belongs to; object type IDs are stringified integers. If you don’t include this value, we assume the object type ID is 1. See objects in Customer.io Journeys for more information.

      You can include this value as objectTypeId at the top level of your payload or as object_type_id in the traits object.

    • Group Traits* any type
      Additional traits you want to associate with this group.
  • type string
    Required The event type. This is set automatically by the request method/endpoint.

    Accepted values:group

  • userId string
    The unique identifier for a person. This value should be unique across systems, so you recognize the same person in your sources and destinations.
  • version number
    The version of the API that received the event, automatically set by Customer.io.

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.

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
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 the group a person belongs to
nameStringName of a group
phoneStringPhone number of a group
websiteStringWebsite of a group
planStringPlan that a group is in
relationshipAttributesObjectAttributes that describe the relationship between a person and an object in Customer.io Journeys. See Relationship Attributes for more information.
objectTypeIdIntegerThe type of object that the group represents. This is a required trait for objects in Customer.io Journeys. If you don’t include this value, we’ll assume it’s 1 (the first kind of object you create). See Object Type for more information.
objectIdStringThe ID of a custom objectNot to be confused with a JSON object, an object in Customer.io is a non-person entity that you can associate with one or more people—like a company, account, or online course. You can use objects to message people based on changes to their company, account, or course itinerary. in Customer.io Journeys.

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.

Groups are called objects in Customer.io

In Customer.io Journeys, we refer to groups as objectsNot to be confused with a JSON object, an object in Customer.io is a non-person entity that you can associate with one or more people—like a company, account, or online course. You can use objects to message people based on changes to their company, account, or course itinerary.. The principle is the same: objects are non-people entities that people are related 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 person and the object. Items under traits are for the object, while items under traits.relationshipAttributes are for the relationship between the person 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 person 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 person 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 person’s role in the company, the dateJoined, and the isPrimaryContact in the traits.relationshipAttributes object.

{
  "userId": "wileecoyote",
  "groupId": "0e8c78ea",
  "traits": {
    "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 Journeys. 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
  }
}
Copied to clipboard!
  Contents
Is this page helpful?