Group Identify API
Regions
The base URL depends on your project's data residency. In all examples on this page, use the default base URL unless your project uses Amplitude's EU data center—in that case use the EU base URL in this table.
This API uses the event ingestion host api2.amplitude.com (default) or api.eu.amplitude.com (EU). Other Amplitude APIs use different hostnames (for example api.amplitude.com, core.amplitude.com, data-api.amplitude.com, or experiment.amplitude.com). The https://analytics.amplitude.com hostname is the Analytics web app (browser UI), not an ingestion endpoint.
| Data residency | Base URL |
|---|---|
| Default | https://api2.amplitude.com |
| EU | https://api.eu.amplitude.com |
Considerations
- Updates affect only future events, and don't update historical events.
- You can track up to 5 unique group types and 10 total groups per event.
- The maximum number of group identifies per request is 1024.
- The maximum number of group properties per request is 1024.
- The maximum byte size/per request is 1 mb.
Request
Set or update group properties.
POST https://api2.amplitude.com/groupidentify
curl
curl --location --request POST '<https://api2.amplitude.com/groupidentify>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'api_key=<API_KEY>' \
--data-urlencode 'identification=[{"group_properties":{"org csm":"Lucas","org plan":"Enterprise","org owner":"Luis"},"group_type":"Seller","group_value":"12345678"}]'
Required parameters
| Name | Description |
|---|---|
api_key | Your project API key. |
identification | Either a single JSON identification object or an array of JSON objects, each of which represents one identification. |
Identification parameter keys
| Key | Type | Description | Example |
|---|---|---|---|
group_type | String | The group type. | "org name", "org id" |
group_value | String | One specific value of the group_type. | "group_type":"org id","group_value":"12345678" or "group_type":"account name","group_value":"Acme Corp" |
group_properties | Object | A dictionary of key-value pairs that represent data tied to the group. Each distinct value appears as a group segment on the Amplitude dashboard. You can store property values in an array. Amplitude transforms date values into string values. Refer to the operations table that follows. | {"arr": "10000", "cs": ["Justin", "Ben"], "renewal_date": "01/01/2018"} |
group_properties supports these 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. |
Status codes
| Code | Message |
|---|---|
| 200 | Success |
| 400 | Bad request. See the error message for specifics. |
Was this helpful?