Set up account-level reporting

NOTE: Amplitude has a limit of five group types per project.

SDKs

You can set up account-level reporting in Amplitude's SDKs by following these specific instructions, depending on which SDK you are using:

• Android SDK
• iOS SDK
• JavaScript SDK

Identify API

If you are sending data to Amplitude server-side, use the groups key in your identification object. This will associate a particular user in a certain group. Please see the Identify API documentation for more information on how to instrument groups via Amplitude's Identify API.

HTTP API

If you are sending data to Amplitude server-side, use the groups key in your event object. This will add event-level groups (groups that only persist on that specific event). Please see the HTTP API documentation for more information on how to instrument groups via Amplitude's HTTP API.

Segment

NOTE: The Segment <> Amplitude cloud (any of Segment's server-side sources or the unbundled client-side integration) and device mode integration (bundled Segment-Amplitude integration) now support setting both group types and group properties through Segment's group call. See the Segment documentation here for more details

To set group types in Amplitude via Segment, you must enable the following Amplitude destination settings and provide them with the appropriate values:

• Group Type Trait: This specifies what trait in your Segment group calls will contain the desired group type.
• Group Value Trait: This specifies what trait in your Segment group calls will contain the desired group value.

For example, if you have the following code:

analytics.group("placeholder", {
    groupType: "org name", // Segment trait "groupType"
    groupValue: "Amplitude", // Segment trait "groupValue"
    employees: "120" // group property
});

And this in Segment's Amplitude destination settings:

Then the integration will create org name as a group type in Amplitude and associate the current user with org name = Amplitude.

NOTE: What you pass in as the groupID (in the above code, "placeholder") in the group call will not matter, as this value is not mapped to anything on Amplitude's side.

To set group properties via instrumentation code, you will need at least one source in Segment using the Segment <> Amplitude cloud mode integration (any of Segment's server libraries as well as the unbundled client-side integration). Data in Amplitude having the user property [Amplitude] Library = segment will be sent via a cloud mode integration. You can use this user property to verify the type of integration you have installed in Amplitude for each of your Segment sources. Alternatively, you can also call the Amplitude SDK's functions to set group properties:

analytics.ready(function() {
    var groupIdentify = new amplitude.Identify().set('employees', 100);
    amplitude.getInstance().groupIdentify('orgId', '1234', groupIdentify);
});

Any additional traits that are passed into the group call will appear in Amplitude as group properties. For example, from the above code, employees will be set as an group property in Amplitude:

You can set groups and group properties using Segment's group method. Note that via this method, every user event will include the group. That means this call is more appropriate to set user-level groups (such as CompanyID) than for event-level grouping.

If you set groups within Segment's track call, you can assign events to a group but you cannot set and update group properties within the call. To send group properties, call the Amplitude Group Identify API directly, outside of the Segment integration.

To assign groups via Segment's track call, navigate to the Mappings tab within your Segment destination settings, and assign them there.

Create groups using the Group Identify API

Using the Group Identify API, you can create a new group tied with all expected group properties or update group properties for an existing group. In the example requests, the parameters and keys are italicized. The underlined values are what you need to replace with the parameters you are specifically interested in.

In addition, group property operations ($set, $setOnce, $add, $append, $unset) are supported in this Group Identify API.

Request Format 

Send a POST or GET request to https://api.amplitude.com/groupidentify with two request parameters:

Example Request (single)

curl --data 'api_key=040062a5d38552315b98302ba4f2f'
--data 'identification={"group_properties":{"org csm":"Lucas","org plan":"Enterprise","org owner":"Luis"},"group_value":"1234","group_type":"org id"}' https://api.amplitude.com/groupidentify

Example Request (batch)

curl --data 'api_key=040062a5d38552315b98302ba4f2f'
--data 'identification=[{"group_properties":{"org csm":"Lucas","org plan":"Enterprise","org owner":"Luis"},"group_value":"success","group_type":"org id"},{"group_properties":{"org csm":"Sarah","org plan":"Growth","org owner":"Sandy"},"group_value":"1234","group_type":"org id"}]' https://api.amplitude.com/groupidentify

NOTE: The upload limits listed here will apply to these requests.

Keys for the identification Parameter

The following keys can be sent within the JSON identification object. Note that both group_type and group_value are required.