This API allows you to attach custom properties at the user level, such as user-level info from your database or demographic info.

Note that these properties are stateless, and only the most recent value is stored. Heap will create a new property if it doesn’t already exist, and will overwrite the previous property value if one already exists with the same name.

The client-side API allows you to add these custom user properties on identified and anonymous users. For best practices and use cases for managing identity, see our developer guide on Using Identify. For a list of questions to consider when deciding what users to track, see the Custom User Properties section of the Setting Up Heap guide.

Our Looker Actions integration allows you to quickly import property data into Heap. See the Looker Actions Integration guide to learn more.

The addUserProperties API lets you attach custom properties to user profiles, such as account-level info from your database, or demographic info.

To better understand the client-side identify and addUserProperties APIs, take a look at our comprehensive guide.

heap.addUserProperties({ Name: 'Alice Smith', Profession: 'Data Scientist' });
heap.addUserProperties({ Name: 'Alice Smith', Profession: 'Data Scientist' });
[Heap addUserProperties:@{@"Name": @"Alice Smith", @"Profession": @"Data Scientist"}];
Heap.addUserProperties(["Name": "Alice Smith", "Profession": "Data Scientist"])
Map<String, String> props = new HashMap<>();
props.put("Name", "Alice Smith");
props.put("Profession", "Data Scientist");
    "Name" to "Alice Smith",
    "Profession" to "Data Scientist"
  1. user properties: a JSON object, NSDictionary, or Map containing key-value pairs to be associated with a user. Keys and values must be a number or string, with the value being 255 characters or fewer.

Also, the string user_id can't be used as a key in the user properties object.

For Android, the property map keys and values must be converted to strings, but they can be analyzed as numbers in Heap.

User properties are associated with all of the user's past activity, in addition to their future activity. Custom user properties can be analyzed in the same fashion as any other user property.



If you want to write your user's email into the builtin Email property, you must send the key lowercase i.e. heap.addUserProperties({"email": "[email protected]"});

Sending an email value with a non-lowercase key will create a new property to store this data.


Requests are limited to 30 requests per 30 seconds per identity per app_id

Did you find what you were looking for?
Thumb up Thumb down