HubSpot Lookup variable

The HubSpot Lookup variable by Stape allows you to retrieve and enrich contact information in your server Google Tag Manager (sGTM) container using the HubSpot CRM API. It lets you look up contacts and use their CRM properties to enrich server-side event data.

• The variable connects directly to the HubSpot CRM Contact API, allowing you to retrieve up-to-date contact information based on an email address, Contact ID, or custom identifier.
• It includes built-in response caching through server-side GTM's templateDataStorage, helping reduce repeated API requests for the same contact and preserve your HubSpot API quota.
• It offers flexible output options, allowing you to return the complete HubSpot contact object or select specific properties, such as firstname, email, lastname, or phone, for use in your server-side tracking setup.

Please ensure that you already have Google Tag Manager web and server containers, as well as a configured server container and custom domain in Stape. Please follow these guides if you don’t have any of those:

• How to create a server container in Google Tag Manager 
• How to create a server container in Stape 
• How to add a custom domain in Stape 

1. Configure sending data to the server GTM container. The most popular options for sending data to sGTM are Google Analytics 4 and Data Tag/Data Client. For more information, read the Send data to server container article.

2. Add the HubSpot Lookup variable template in the server GTM container by importing it from the Template gallery:

• Search for the HubSpot Lookup variable by Stape in the Google Tag Manager Template gallery.
• Click Add to workspace.

3. Create the HubSpot Lookup variable:

• Go to the Variables menu → click New.

• Click Variable Configuration → select HubSpot Lookup.

4. Configure the HubSpot Lookup variable: 

• Access Token - your HubSpot Private App Access Token or Service Key. Ensure it has the crm.objects.contacts.read permission. For more information on how to get your token, check the Private App Access Token documentation or Service Key documentation.
• Lookup Parameters - allows you to choose the key used to look up the user in HubSpot: Email, Contact ID, or Other unique identifier (allows you to enter a custom key in the Unique identifier name field).
• Identifier value - specify a dynamic value (usually an Event Data variable) to search for.

• Properties to Retrieve (Optional) - specific contact properties to be retrieved from HubSpot, such as firstname, lastname, phone, city. If left blank, it will retrieve all properties.
• Output Format - select what the variable should return:

  • Return entire object - will return the complete response object provided by HubSpot.
  • Return custom properties - allows you to define a list of properties (such as email, phone, city, etc.) The variable will return a clean object containing only those specific properties. If only one property is defined, it will return its string value directly (key/value pair).
• Store response in cache - store the response in Template Storage (to cache results). If all parameters of the request are the same, the response will be taken from the cache if it exists. Enabled by default. If enabled, define the Cache Expiration Time (Hours).

• Format Value - allows you to edit the value that this variable outputs. Learn more in the documentation on format values in user-defined web variables.

  • Change Case to… - transforms all data to lowercase or uppercase.
  • Convert to number - converts all data to numeric values. Allows you to choose the Decimal separator format.
  • Convert null to… - choose a variable to convert null values to.
  • Convert undefined to… - choose a variable to convert undefined values to.
  • Convert to true/false - changes the value to the true/false type.
  • Convert true to… - choose a variable to convert true values to.
  • Convert false to… - choose a variable to convert false values to.

5. Give your variable a descriptive name and click Save.

You can test the configurations in Google Tag Manager. Click on Preview, trigger the event where you use the variable. Then navigate to the Variables tab and check the variable you have created and its value.

Find out more about debugging and monitoring server-side tracking configuration in our guide.