Overview: Query Builder for HubSpot Marketing (Lists)

IN THIS ARTICLE

How to access the Query Builder for HubSpot Marketing (Lists)

Navigate to Metrics > Query Builder to access the Query Builder for HubSpot Marketing. Click the green + Create Custom Metric button and select your connected HubSpot Marketing Account from the Data Source drop-down list. Select the Lists button. 

New Lists that were created in your HubSpot account will not be recognized in Databox until the next day after larger data sync to identify new Lists in the HubSpot account is performed in the middle of the night. 

    Query Builder is available on the Professional and Performer plans. Request a trial of Query Builder by following these steps.  

How to use the Query Builder for HubSpot Marketing (Lists)

A
  Data Source: This is the Data Source that the Custom Metric is syncing data from
B
   Metric: Select a List from your connected HubSpot Marketing Data Source
C
  Data Choice: There are two Data Choice options: Total List Contacts and Net New List Contacts. 
Total List Contacts: This Data Choice will return the total number of Contacts in the List at the end of the selected Date Range. If it is an open Date Range, like "Year to Date," the current total number of Contacts in the List will be displayed. 
Net New List Contacts: This Data Choice will return the difference between the number of Contacts in the List on the last day of the selected Date Range and the number of Contacts in the List on the first day of the selected Date Range. The exact calculation performed on the backend is as follows: 
(Total # of Contacts in the List on the Last Day of the Date Range) - (Total # of Contacts in the List on the First Day of the Date Range) = Net New List Contacts
Selecting Net New List Contacts as the Data Choice will reveal a checkbox to Skip Contacts Already in The List. By selecting this checkbox, the number of Contacts in the List on the day the List is created will be subtracted from the total # of Contacts in the List. This makes it so a backfill of Contacts will not skew List data in Databox.
D
    Favourable Trend: By default, Trending up is positive is pre-selected, which will display the percentage change value on Datablocks as green when the Metric value has increased. If the Custom Metric you created has opposite trends, select Trending down is positive radio button. Learn more  here.
E
   Custom Metric Name: Enter a name for your Custom Metric. This Custom Metric Name will be available in the Designer after saving. 
F
   Preview data: After clicking Preview data, a Data Preview of the Custom Metric will be displayed. Daily Metric values are displayed in this section from the List Create Date until the current day. 
G
   Save: Save your Custom Metric.

Best Practices when setting up your Lists to track Net New List Contacts

Daily data tracking of the number of Contacts in the List is accessible from HubSpot's API. Specific Contact Properties associated with the Contacts in the List are not accessible from HubSpot's API. Therefore, data is not accessible prior to the List's Create Date, even if a Contact would have qualified for the List at an earlier date. 

Because of this, you may want to consider creating Lists that only have Contacts added to them, and setting a start date for when Contacts qualify for the List. 

IN THIS SECTION

How to create Lists to track New Contacts that meet specified List Filters

Net New List Contacts are calculated by performing the following backend calculation: 

(# of Contacts in the List on the Last Day of the Date Range) - (# of Contacts in the List on the First Day of the Date Range) = Net New List Contacts in the Date Range

Because of this, if you want to track  New Contacts that are added to the List rather than Net New Contacts that are added or removed from the List, you'll want to ensure that your List Filters do not remove Contacts from the List. This will ensure that Contacts only enter the List and Net New List Contact Values are not skewed.  

How to create Lists with an open Start Date to qualify for the List [Example]

Let's say you create an List to track CTA Clicks to a specific CTA on May 7th and 150 Contacts were added to the List. HubSpot is only sending Databox the number of Contacts in the List, not any specific Contact Properties associated with the Contacts in the List. So, all 150 Contacts that entered the List on May 7th are considered New List Contacts (or CTA Clicks) on May 7th. 

In Databox, you create a Custom Metric on May 8th and select Net New List Contacts as the Data Choice. 

On May 31st, there are 1000 Contacts in the List. 

  • If the Skip contacts already in the list checkbox is not selected, the following equation will be performed on the backend for Month to Date: 

    1000 (# of Contacts in the List on May 31st) - 0 (# of Contacts in the List on May 1st)= 1000 (Net New List Contacts in May)
  • If the Skip contacts already in the list checkbox is selected, the following equation will be performed on the backend for Month to Date: 

    850 (# of Contacts in the List on May 31st [1000] - # of Contacts in the List on the day the List was created [150]) - 0 (# of Contacts in the List on May 1st)= 850 (Net New List Contacts in May)

Since this is a rolling list, moving forward, no changes need to be made. In June, the number of Net New Contacts in the List (or Contacts who clicked the CTA) will not be skewed, because there weren't any old Contacts that were added to the List during this time. However, the "Year to Date" Value for CTA Clicks will not be accurate until the following year, because the List is not set to include Contacts who clicked the CTA throughout the full year. 

How to create Lists with a set Start Date to qualify for the List [Example]

Let's say you create an List to track CTA Clicks to a specific CTA on May 7th and you are primarily interested in Monthly reporting. Therefore, you add a condition to the List so only Contacts who clicked on the CTA on May 1st and on are added to the List. Because of this criteria, 25 Contacts are added to the List on May 7th to account for all CTA Clicks in May. 

In Databox, you create a Custom Metric on May 8th and select  Net New List Contacts as the Data Choice

On May 31st, there are 1000 Contacts in the List. You will not want to select the  Skip contacts already in the list checkbox, because all Contacts added to the List were intentionally added. The number of Net New List Contacts will be accurately calculated in Databox for May and all future Date Ranges. However, the "Year to Date" Value for CTA Clicks will not be accurate until the following year, because the List is not set to include Contacts who clicked the CTA throughout the full year. 

How to verify a Custom List Metric in HubSpot vs Databox [Example]

Let's walk through an example to verify Net New List Members for an List that is tracking Contacts who sign up for our AM Demo. We're interested in viewing data for This Month. 

1
 Within Databox, the Custom Metric is set up as follows: 
2
 To verify this Custom Metric in HubSpot, first log into your HubSpot portal and navigate to Contacts > Lists.

3
 Find the List you're pulling into Databox, and click More > View list performance. This will open the corresponding List Performance data. 
4
 You'll now see a graph called List size over time. First, check the selected Date Range to ensure it matches what you're viewing in Databox. 
5
 When you hover over the graph, you can see the daily # of Contacts in the List. This is what we're accessing and pulling into Databox from HubSpot's API. 

To verify this Custom Metric in HubSpot, first, log into your HubSpot portal and navigate to Contacts > Lists. 

6
 To calculate Net New List Members, simply subtract the # of Contacts in the List on the 1st day of the Month from the # of Contacts in the List on the last day of the month. 
For our example, we would do 4,824 - 4,787 = 37 Net New List Members for Last Month. This matches what we see in Databox for This Month, so we were successfully able to verify the number of Net New List Contacts in HubSpot and Databox. 

How to add a Custom List Metric to a Databoard

1
 Open the selected Databoard in the Databox Designer, or create a new Databoard.  
2
 Drag and drop a blank Datablock onto the Databoard from the Visualization Library. 
3
 Select the appropriate HubSpot Marketing Data Source from the righthand  Datablock Settings panel. This must be the same HubSpot Marketing Account that was selected when creating the Custom Metric.   
4
 Select the Custom tab at the top of the Metric drop-down list. 
5
 Select the Custom Metric name to populate the Datablock.

Additional Information

  • No data is accessible from before the Contact List Creation Date.
  • New Lists that were created in your HubSpot account will not be recognized in Databox until the next day after a larger data sync to identify new Lists in the HubSpot account is performed in the middle of the night. 
  • List data is synced with Databox once per day. This is consistent with how List data is updated in the List Performance report within HubSpot. Databox is syncing List data from the List Performance report. 

    HubSpot performs a daily update on the List Performance report around midnight every day. Learn more about validating data using the List Performance report here

    If contacts are added to Lists after the daily List Performance report update, you can see different values on the List Performance report page in HubSpot and the List library in HubSpot. 

    When validating List data in Databox, you should compare Databox's data with data from the List Performance report in your HubSpot account.

    Databox is continuously updating List data as soon as data is available from the HubSpot API.
  • For Custom Metrics created by this Query Builder up to 1090 days of historical data can be synced with Databox.
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.