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 as a destination, you’ll see your groups under Companies 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."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:{
  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. 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": "",
    "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": [
  "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 to flag an .identify() call to just update the traits but not “last seen.”

    • 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 local 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 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. Segment first looks for the canonical URL. If the canonical URL is not provided, Segment uses 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.
  • 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.
    • Group Traits* any
  • type string
    Required The event type. This is set automatically by the request method/endpoint.

    Accepted values:group

  • userId string
    Required 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

Group ID

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


Like people in, 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.

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

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.

Copied to clipboard!
Is this page helpful?