# Group

The `group` call lets you link an identified user with a group like a company, organization, or an account. You can also record any custom traits associated with that group like the company name, number of employees, etc.

{{< info >}}
An identified user can be linked to multiple groups.
{{< /info >}}

## Sample payload

Here is a sample payload for the `group` event after removing the [Common fields]({{< ref "event-spec/standard-events/common-fields.md" >}}):

```json
{
  "type": "group",
  "groupId": "5e8a78ba9d32d3b1898a6247",
  "traits": {
    "name": "Hooli",
    "industry": "Technology",
    "employees": 4500,
    "plan": "basic"
  }
}
```

The corresponding event that generates the above payload via the [JavaScript SDK]({{< ref "sources/event-streams/sdks/rudderstack-javascript-sdk/_index.md" >}}) is:

```javascript
rudderanalytics.group("5e8a78ba9d32d3b1898a6247", {
  name: "Hooli",
  industry: "Technology",
  employees: 4500,
  plan: "basic"
})
```

## Group fields

The `group` call has the following fields in addition to the [Common fields]({{< ref "event-spec/standard-events/common-fields.md" >}}):

| **Field** | **Type** | **Presence** | **Description**                                                                                                                            |
| :-------- | :------- | :----------- | :----------------------------------------------------------------------------------------------------------------------------------------- |
| `groupId` | String   | Required     | Your group's unique identifier which lets you identify the group in your database.                                                         |
| `traits`  | Object   | Optional     | Includes the traits of the group such as `name`, `email`, `employees`, etc. For more more information, check the [Traits]({{< ref "#traits" >}}) section below. |

{{< warning >}}
The field names can change slightly depending on the SDK. However, the functionality remains the same.

See the [SDK-specific documentation]({{< ref "sources/event-streams/sdks/_index.md" >}}) for the implementation specifics and details on the above fields.
{{< /warning >}}

{{< success >}}
Identity data (user traits) will be automatically added to `group` calls from the most recent `identify` call, so you do not need to add it manually. This information will be included in a `traits` object in the `context` fields of the payload. Note that `group` calls also automatically handle `anonymousId` values associated with the user.

See our [Identify]({{< ref "event-spec/standard-events/identify.md" >}}) doc for more details.
{{< /success >}}

## Traits

Traits are additional information included in a `group` call that adds more context to the group. Some example of traits include the number of employees, name of the industry, or the website of the group.

RudderStack has some reserved traits that it handles in special ways. These are listed in the table below:

<table>
  <thead>
    <tr>
      <th style="text-align:left">
        <b>Trait</b>
      </th>
      <th style="text-align:left">
        <b>Type</b>
      </th>
      <th style="text-align:left">
        <b>Description</b>
      </th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="text-align:left">
        <code class="inline-code">id</code>
      </td>
      <td style="text-align:left">String</td>
      <td style="text-align:left">Fallback parameter used only for mapping data <b>if</b> <code class="inline-code">groupId</code> is not available in the event payload.</td>
    </tr>
    <tr>
      <td style="text-align:left">
        <code class="inline-code">name</code>
      </td>
      <td style="text-align:left">String</td>
      <td style="text-align:left">The group name</td>
    </tr>
    <tr>
      <td style="text-align:left">
        <code class="inline-code">email</code>
      </td>
      <td style="text-align:left">String</td>
      <td style="text-align:left">The group's email address</td>
    </tr>
    <tr>
      <td style="text-align:left">
        <code class="inline-code">phone</code>
      </td>
      <td style="text-align:left">String</td>
      <td style="text-align:left">Phone number associated with the group</td>
    </tr>
    <tr>
      <td style="text-align:left">
        <code class="inline-code">address</code>
      </td>
      <td style="text-align:left">Object</td>
      <td style="text-align:left">
        <p>The group's street address. This can optionally contain any or all of the following fields:</p>
        <ul>
          <li>
            <code class="inline-code">city</code>
          </li>
          <li>
            <code class="inline-code">country</code>
          </li>
          <li>
            <code class="inline-code">postalCode</code>
          </li>
          <li>
            <code class="inline-code">state</code>
          </li>
          <li>
            <code class="inline-code">street</code>
          </li>
        </ul>
      </td>
    </tr>
    <tr>
      <td style="text-align:left">
        <code class="inline-code">industry</code>
      </td>
      <td style="text-align:left">String</td>
      <td style="text-align:left">
        <p>The name of the industry that the group is a part of</p>
      </td>
    </tr>
    <tr>
      <td style="text-align:left">
        <code class="inline-code">createdAt</code>
      </td>
      <td style="text-align:left">Date</td>
      <td style="text-align:left">
        <p>Date of the group's account creation. We recommend using the <b>ISO-8601</b> date string format.</p>
      </td>
    </tr>
    <tr>
      <td style="text-align:left">
        <code class="inline-code">description</code>
      </td>
      <td style="text-align:left">String</td>
      <td style="text-align:left">The group's description</td>
    </tr>
    <tr>
      <td style="text-align:left">
        <code class="inline-code">employees</code>
      </td>
      <td style="text-align:left">String</td>
      <td style="text-align:left">
        <p>Number of the employees in the group. This is typically used for companies.</p>
      </td>
    </tr>
    <tr>
      <td style="text-align:left">
        <code class="inline-code">plan</code>
      </td>
      <td style="text-align:left">String</td>
      <td style="text-align:left">The plan that the group is subscribed to</td>
    </tr>
    <tr>
      <td style="text-align:left">
        <code class="inline-code">website</code>
      </td>
      <td style="text-align:left">String</td>
      <td style="text-align:left">The group's website</td>
    </tr>
    <tr>
      <td style="text-align:left">
        <code class="inline-code">avatar</code>
      </td>
      <td style="text-align:left">String</td>
      <td style="text-align:left">URL of the group's avatar image</td>
    </tr>
  </tbody>
</table>

{{< success >}}
Different destinations recognize some of the above data points differently. 

With RudderStack, you don't have to worry about these inconsistencies across destinations. Our open source destination transformer code handles these destination-specific conversions automatically.
{{< /success >}}