The Group Spec
- Yuri (Unlicensed)
These specs are 100% compatible with http://segment.com specs.
The group API call is how you associate an individual user with a group, such as a company, organization, account, project, or team.
The group call enables you to identify what account or organization your users are part of. There are two IDs that are relevant in a group call: the userId, which belongs and refers to the user, and the groupId, which belongs and refers to the specific group. A user can be in more than one group which would mean different groupIds, but the user will only have one userId that is associated to each of the different groups. Keep in mind that not all platforms support multiple groups for a single user
journy.io recommends that you make a Group call:
After a user first registers, entering its company details.
After a user logs in. Make a group call for each account the user is part of.
When a user updates their info, make a group call for each account the user is part of.
In addition to the groupId, which is how you’d identify the specific group or company, the group method receives traits that are specific to the group, like industry or number of employees for example, that belong to that specific account. Like the traits of an identify call, you can update these when you call the same trait with a different value.
When using the group call, it’s helpful if you have accounts with multiple users.
Here’s the payload of a typical group call, with most common fields:
{ "type": "group",
"groupId": "xyz789",
"traits": {
"name": "Tesla Inc",
"industry": "Automotive",
"employees": 3294,
"plan": "enterprise",
"status": "churned",
"stripe customer id": "Swssj8234sSwcvBPO234" }
}And here’s the corresponding JavaScript event that would generate the above payload:
analytics.group("xyz789", {
name: "Tesla Inc",
industry: "Automotive",
employees: 3294,
plan: "enterprise",
status: "churned",
stripe_customer_id: "Swssj8234sSwcvBPO234"
});Based on the library you use, the syntax in the examples might be different. You can find library-specific documentation on the page.Sources Overview
Beyond the common fields, the group call takes the following fields:
FIELD | REQUIRED? | TYPE | DESCRIPTION |
| required | String | A unique identifier for the group in your database. See the for more detail.Group ID field docs |
| optional | Object | Free-form dictionary of traits of the group, like |
Example
Here’s a complete example of a group call:
{ "anonymousId": "507f191e810c19729de860ea",
"type": "group",
"userId": "abc123", //Elon Musk
"groupId": "xyz789", //Tesla Inc
"channel": "browser",
"context": {
"ip": "8.8.8.8",
"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" },
"integrations": {
"All": true,
"Mixpanel": false,
"Salesforce": false },
"messageId": "022bb90c-bbac-11e4-8dfc-aa07a5b093db",
"receivedAt": "2015-02-23T22:28:55.387Z",
"sentAt": "2015-02-23T22:28:55.111Z",
"timestamp": "2015-02-23T22:28:55.111Z",
"traits": {
"name": "Tesla Inc",
"industry": "Automotive",
"employees": 3294,
"plan": "enterprise",
"status": "churned",
"stripe customer id": "Swssj8234sSwcvBPO234" },
"version": "1.1"
}Identities
The User ID is a unique identifier for the user performing the actions. Check out the User ID docs for more detail.
The Anonymous ID can be any pseudo-unique identifier, for cases where you don’t know who the user is, but you still want to tie them to an event. Check out the Anonymous ID docs for more detail.
Note: In our browser and mobile libraries a User ID is automatically added from the state stored by a previous identify call, so you do not need to add it yourself. They will also automatically handle Anonymous IDs under the covers.
Group ID
A Group ID is the unique identifier which you recognize a group by in your own database. This is typically the static ID also used in your database.
Traits
Traits are pieces of information you know about a group that are passed along with the group call, like employees or website.
journy.io has reserved some traits that have semantic meanings for groups, and handles them in special ways. You should only use reserved traits for their intended meaning.
The following are the reserved traits journy.io has standardized:
TRAIT | TYPE | DESCRIPTION |
| Object | Street address of a group. This should be a dictionary containing optional |
| String | URL to an avatar image for the group. |
| Date | Date the group’s account was first created. journy.io recommends ISO-8601 date strings. |
| String | Description of the group, like their personal bio. |
| String | Email address of group. |
| String | Number of employees of a group, typically used for companies. |
| String | Unique ID in your database for a group. |
| String | Industry a user works in, or a group is part of. |
| String | Name of a group. |
| String | Phone number of a group. |
| String | Website of a group. |
| String | Plan that a group is in. |
| String | Subscription status, examples: "lead", "trial", "trial_expired", "paying", "churn". |
Note: You might be used to some destinations recognizing special properties differently. For example, Mixpanel has a special track_charges method for accepting revenue. Luckily, you don’t have to worry about those inconsistencies. Just pass along revenue.
journy.io handles all of the destination-specific conversions for you automatically. Same goes for the rest of the reserved properties.
If you pass these values, on null will throw a NullPointerException. You may continue to set values inside the trait. If you do so, this would work the same as the rules do with NoSQL data. If you had set a value previously for a user and on the next request you sent the same value of that property as on null, it will be replaced by null, but if you do not send that property, the original value is persisted.
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.
Tip: Need help integrating journy.io to your web-site and/or App?
Reach out to our support team
or book time to make it together