# Group  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 [API documentation](/integrations/api/cdp) and start writing code. ## How it works[](#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](/journeys/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-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. * The`traits.objectTypeId` represents the type of object in Customer.io. Customer.io supports different kinds of groups, called [objectsAn object is a non-person entity that you can associate with one or more people—like a company, account, or online course.](/journeys/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 person 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 person yet) for you, associating the current user with the group. ```javascript 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 person to a group, you’ll have to provide the `userId` or `anonymousId` yourself. Here’s an example from our NodeJS server-side library: ```javascript 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](#complete-payload). ### The full payload[](#complete-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](/integrations/data-in/source-spec/common-fields) for more information about context, integrations, and timestamps in source payloads. ```json { "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 } ``` * groupId string Required ID of the group * integrations object Contains a list of booleans indicating the integrations that are enabled (true) or disabled (false). By default, all integrations are enabled (returning an empty object). Set `"All": false` to reverse this behavior. * *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. * traits object Additional information about the group. * *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` * version number The version of the API that received the event, automatically set by Customer.io. * groupId string Required ID of the group * integrations object Contains a list of booleans indicating the integrations that are enabled (true) or disabled (false). By default, all integrations are enabled (returning an empty object). Set `"All": false` to reverse this behavior. * *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. * traits object Additional information about the group. * *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` * version number The version of the API that received the event, automatically set by Customer.io. ### Group ID[](#group-id) A Group ID is a unique identifier, like a UUID or ULID, that represents the group in your database or backend. ### Traits[](#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 data-out integrations. You should **only use reserved traits for their intended meanings**. **Trait** **Type** **Description** `address` Object Street address of a group. This should be a dictionary containing optional `city`, `country`, `postalCode`, `state`, or `street` `avatar` String URL to an avatar image for the group `createdAt` Date Date the group’s account was first created `description` String Description of the group, like their personal bio `email` String Email address of group `employees` String Number of employees of a group, typically used for companies `id` String Unique ID in your database for a group `industry` String Industry a user works in, or the group a person belongs to `name` String Name of a group `phone` String Phone number of a group `website` String Website of a group `plan` String Plan that a group is in `relationshipAttributes` Object Attributes that describe the relationship between a person and an object in Customer.io Journeys. See [Relationship Attributes](#object-and-relationship-attributes) for more information. `objectTypeId` Integer The 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](#object-type) for more information. `objectId` String The ID of a [custom objectAn object is a non-person entity that you can associate with one or more people—like a company, account, or online course.](/journeys/objects/) in Customer.io Journeys. 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[](#groups-are-called-objects-in-customerio) In Customer.io Journeys, we refer to groups as [objectsAn object is a non-person entity that you can associate with one or more people—like a company, account, or online course.](/journeys/objects/). 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[](#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[](#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. ```json { "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[](#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](/integrations/data-in/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. ```json { "userId": "wileecoyote", "event": "Delete Object", "properties": { "objectId": "0e8c78ea", "objectTypeId": 2 } } ```