Group Identify API
(Enterprise only) This feature is only available to Growth and Enterprise customers who have purchased the Accounts add-on.
Use the Group Identify API to set or update properties of particular groups. However, these updates will only affect events going forward.
Endpoint
Region | Endpoint |
---|---|
Standard Server | |
EU Residency Server |
Request Format - GroupIdentify
Send a POST or GET request to https://api2.amplitude.com/groupidentify
with two request parameters:
Required Argument | Description |
---|---|
api_key | API Key from your project's Settings page. 040062a5d38552315b98302ba4f2f |
identification | Either a single JSON identification object (see below for fields) or an array of JSON objects, each of which represents one identification. See below for examples. |
Keys for the Group Identification Argument
The following keys can be sent within the JSON identification object.
Example Request
Key | Type | Description | Example |
---|---|---|---|
group_type | string | The type of group being identified | "plan" |
group_value | string | The name of the group being identified | "enterprise" |
group_properties | dictionary | A dictionary of key-value pairs that represent data tied to the groups.1, 2 | {"company_size": "500-1000"} |
1This field supports the following group property operations:
Operation | Description |
---|---|
$set | set the value of a property |
$setOnce | set the value of a property, prevent overriding the property value |
$add | add a numeric value to a numeric property |
$append and $prepend | append and prepend the value to a group property array |
$unset | remove a property |
curl --data 'api_key=040062a5d38552315b98302ba4f2f'\
--data 'identification=[{ \
"group_type":"account_name", "group_value":"Amplitunes", "group_properties": \
{"company_size":"500-1000"}}]' https://api.amplitude.com/groupidentify
Add example request:
curl --data 'api_key= Api key' --data 'identification=[{"group_type":"account_name", "group_value":"Amplitunes", "group_properties": {"company_size":"500-1000"}}]' https://api.amplitude.com/groupidentify
These should be keys in the dictionary where the values are the corresponding properties that you want to operate on.
Note: You should not mix group property operations with actual top-level user properties; instead, include them inside the "$set" operation.
{"$set": {"company_size": "500-1000"}, "$setOnce": {"startDate": "2015-10-01"}, "$unset": {"account_status": "-"}}
2You can store property values in an array and date values are transformed into string values.
Updated 8 months ago