A join key is a user property used to match users in Heap to another source. When you connect Heap to another source (ex: Salesforce), Heap needs a way to organize which properties or events belong to which users.
The property can be called by different names in Heap and the other source, but the values should be an exact match across your entire user base.
Required join key: email
Some integrations require that you use email address as the join key. This could be:
- The built-in email property
- A custom email property
- Identity
Choose your own join key
Some integrations allow you to pick a join key that is not email addresses.
The following Heap integrations support join keys that are NOT email: Salesforce, Marketo, and Looker.
When choosing a “non-email” join key for these integrations, make sure the key is unique to each user and that it matches a property in the source/destination.
Can I still use email as my join key, even if it isn’t required?
Yes! You can use email as your join key for these integrations.
What user property should I use as a join key?
Common properties used as join keys include:
- Identity
- Unique, internal user ID
- Email address
A good candidate for a join key is a user property that’s:
- Widely assigned across your users
- Unique to each user
- Remains consistent over time
- Matches a property value in the other platforms in your data ecosystem
Environment vs Source-specific join keys
While bringing your data ecosystem together in Heap, you’ll encounter two types of join keys: environment-level and source-specific.
An environment-level join key is a “default” set at the Heap environment level. Commonly used integrations which use an environment-level join key include:
After you set the environment-level join key for the first time, that join key will automatically be used for other integrations that require an environment-level join key. For example, Stripe will use the same join key as Mailchimp.
A source-specific join key is set for each integration. Commonly used integrations which use a source-specific join key include:
How do I collect a property to use as a join key?
A join key property is just like any other custom user property. You can implement an addUserProperties API call or an identify call to bring this data into Heap.
How do I change my join key?
Can I change the join key for my integration?
Changing a join key is technically possible, but requires work by our Services team to implement and may require the removal and deletion of integration data.
We strongly recommend choosing the appropriate join key upon initial connection. If you must change your existing join key, please contact our Support team via the Get support page to review available options.
Common join key issues
User property has no values
The property you selected to use as a join key doesn’t have users who have been assigned a value for it. This error is most common when selecting the built-in Email or Identity user properties as a join key.
To use the selected property, you’ll need to implement an addUserProperties API call to assign values to your users. You can also contact support via the Get support page to manually set the join key for you.
User property contains values that are not emails
Some integrations require that email address is the join key. This error indicates that the property selected as a join key has values which aren’t properly formatted email addresses.
Need help? Please post in Community or contact us via the Get support page in Heap.