Group Identities allows you to associate multiple users who are related by a single, shared identifier, or group ID. Common examples include users who live in the same household or who share the same account.

When creating a group identity, you first select a user attribute to serve as the group identifier. You then select user attributes which will become shared, group attributes that are be assigned to all members of the group. Every 24 hours, mParticle searches through your user profiles. Any profiles who share the same value of a group identifier are added to a group before inheriting all of the group attributes that have been assigned to that group identity.

For example, imagine an online streaming service where each account may contain multiple users who log in using the same account ID, and you want to record on each user’s profile if they are a “premium subscriber”.

First, we need to ensure that any user who subscribes to the premium service receives a new user attribute called premium_subscriber with the value true.

Next, we create a new group identity, and we designate the attribute premium_subscriber as a group attribute. After a nightly grouping job, the group attribute account_id:premium_subscriber is added to all profiles in a group where at least one other member profile has the user attribute premium_subscriber: true.

Group identifiers

A group identifier is a user attribute that identifies a user group.

For example, if you create a group identity with account_id as the group identifier, and three users all have the attribute account_id with a value of 1234, then all three users are added to a group that is identified by the group ID account_ID:1234.

Group identifiers must be unique hexadecimal or numerical user attributes within the following constraints:

  • Minimum 1 character
  • Maximum 32 characters
  • Includes only the alphanumeric characters a-z and 0-9

When you create a group identity, you are defining a set of criteria that is used to create multiple groups, one for each value of the group ID. Using the example above, if mParticle ingested data for two more users who each had the the attribute account_id with a value of 5678, they would be added to a separate group identified by account_id:5678.

Group attributes

A group attribute is a user attribute that is added to all group with the same group ID. All user profiles in the same group receive the same group attributes.

Group attributes are differentiated from other user attributes with a prefix equaling the group ID name, but not including the group ID value.

For example, all user profiles in a group with the group ID account_id:1234 and the group attribute premium_subscriber will display the new attribute account_id:premium_subscriber.

This prevents conflicts between group attributes and any other similar user attributes. For example, a user profile could list two street addresses: one that is inherited from a group they belong to, and one that is their personal street address.

You can use any user attribute that exists in your data catalog as a group attribute.

There are two types of group attributes: Boolean or attributes and Latest attributes.

Boolean attributes

Boolean or group attributes must be a user attributes with the boolean data type: their value can only be true or false. Group members will only inherit a Boolean or attribute if at least one other member has the same attribute with a value of true.

Imagine a user group with the Boolean_or group attribute named has_dog. Let’s say this group contains three users, all with the group attribute has_dog set to false, because none of them had a dog when they joined the group.

Next, a new member is added to the group with the attribute has_dog set to true.

Now, all other group members’ values of has_dog are set to true since someone in the group has a dog.

Latest group attributes

Latest group attributes can be a user attribute with any data type. All members of a group containing a Latest group attribute inherit that attribute with the same value when they join the group. The value of a Latest group attribute is determined by the most recently set value of the attribute among all group members.

For example, imagine a household user group with two members: John and Jane. The group has a Latest group attribute called street_address which is set to 1234 Main Street.

Next, a new user, Cindy, joins John and Jane’s household group. Upon completion of the next nightly grouping job, Cindy’s profile profile would then inherit the group attribute street_address:1234 Main Street.

Group Identities API

In addition to the mParticle UI, you can also create and manage group identities programmatically using the Group Identities API. For more information, see the Group Identities API reference.


mParticle may increase the following limitations before making group identities Generally Available.

  • 1 group definition per workspace in your mParticle account.
  • Each group definition can include up to 10 group attributes.
  • Each group instance can contain up to 10 users.
  • Group identifier limits:

    • Minimum 1 character
    • Maximum 32 characters
    • Includes only the alphanumeric characters a-z and 0-9

Was this page helpful?