Contents x
    HubSpot Walkthrough
    • 6 Minutes to read
    • Print
    • Dark
      Light
    • PDF
    Contents

    HubSpot Walkthrough

    • 6 Minutes to read
    • Print
    • Dark
      Light
    • PDF
    Article summary

    Currently Supported: 

    HubSpot API version 1, 2, and 3.


    Introduction

    HubSpot is a customer relationship management (CRM) platform that provides software for sales, marketing, and customer service. It is designed to help businesses grow by attracting, engaging, and delighting customers.

    Connection

    To connect toHubSpot API v1, follow our step-by-step tutorial.

    Choose a Source Connection after you've created a connection, as seen here:


    Predefined Reports

    Rivery provides a convenient entry point and recommended approach for accessing a range of predefined reports for your use. Each report includes a concise data description, a list of customizable fields (if applicable), and the schema mapping.

    Since these reports follow a standardized format, specific fields are restricted and can only be accessed through Custom Reports.



    Custom Reports

    Select a specific report to pull data from the HubSpot.

    The following image provides an overview of the various custom reports:




    Pull Data From HubSpot

    Available reports for Hubspot data integration:

    • Deals (including modified deals)
    • Companies (Only this report is compatible with Version 2) 
    • Contacts
    • Pipelines
    • Email Events
    • Owners
    • Engagements
    • Recent Engagements
    • Forms
    • Workflows
    • Campaign Data
    • Tickets
    • Marketing Emails
    • Products  
    • Line Items.


    Please note:

    If you are experiencing difficulties when trying to pull a report and you have already established a connection, you may need to reconnect and re-authenticate your connection to update the scopes. This is because HubSpot periodically releases updates that may include new scopes. By re-authenticating your connection, you can ensure that you have the most up-to-date scopes available for your connection.

    Scopes refer to the permissions that Rivery needs to use specific resources or carry out operations on the HubSpot platform. Scopes are used to limit the data and actions that an application can access. 

    Some examples of scopes that are available in HubSpot include:

    • business-intelligence
    • forms
    • oauth
    • timeline
    • content
    • e-commerce
    • crm.lists.read
    • crm.objects.contacts.read
    • crm.schemas.contacts.read
    • crm.objects.companies.read
    • crm.objects.deals.read
    • crm.schemas.companies.read
    • crm.schemas.deals.read
    • crm.objects.owners.read
    • crm.objects.line_items.read
    • crm.schemas.line_items.read.



    HubSpot Reports:

    Deals

    The deals report returns all the deals that were ever created in your HubSpot account.

    image.png

    Modified Deals: the modified deals option returns deals that were modified in the past 30 days or the 10k most recently modified deals.

    We recommend running the report with 'Modified Deals' unchecked first to get all deals, and then checking the modified deals option moving forward.

    Properties Data Structure

    For the Deals and Companies report, you can select the desired Properties data structure with the following checkbox:

    In the following example, we consider that the lead 6789 has 3 properties: property1, property2, property3 which are RECORD field types. That is why the lead 6789is broken down to each property, so we will get 3 rows of data.
    image.png

    For example, with this option enabled, the data of DealType property will be returned as follows (enabling this option is recommended when there are a lot of properties in the report):

    portaliddealidproperty_nameproperty_valueproperty_timestampproperty_sourceproperty_versions
    123456789property1None1635320359889CRM[{"name":"property1","value":"None","timestamp":1635320359889,"source":"CRM","sourcevid":[],"updatedbyuserid":123}]
    123456789property21231635322741557CALCULATED[{"name":"property2","value":"123","timestamp":1635322741557,"source":"CALCULATED","sourcevid":[]}]
    123456789property3blabla1635320379969PLATFORM[{"name":"property3","value":"blabla","timestamp":1635320379969,"source":"PLATFORM","sourcevid":[]}]

    Special note: In this report we try to catch all the property keys inside the first 2500 records. If we still wasn't able to catch everything for mapping you can still take them from property_versions column and parse JSON this field.

    When this option is disabled, each property will be returned in its own different columns:
    image.png


    Email Events

    The email events reports have two extract modes: Standard and Contact List.

    The Standard mode enables filtering on the combinations of app, campaign, recipient email, and event type. You can choose only one option for each of these four filters and combine them as you wish, or leave them empty to get all the data unfiltered.

    HubSpot Walkthrough-standard

    The Contact Lists mode allows you to filter on specific contact lists and email properties.

    For example, you can create a list for all the clients under a certain country and use only that list to get their relevant email events.
    When using this report, make sure to set the email property value to the same property that defines the recipient email address.

    image.png

    Both modes require a date range for the extraction:

    HubSpot Walkthrough-image12


    Select the type of time period of the report. This can be a custom date range or a defined time period.

    Instructions if selecting ‘Date Range’:
    • Select the start date and end date.
    • Leave the end date empty in order to pull data until the moment the river runs.
    • After each run of the river, the start date will be updated automatically with the end date, and the end date will be updated with the empty value. This enables the next run to pull data from the end of the previous run.
    • Select the time zone offset. It will be relevant only if the end date is empty in order to find the moment of the river’s run according to the time zone.
    • Days back - use this input to tell Rivery to pull data from a given number of days back before the given start date.
    • Please Note:

      The Start Date will not be updated if a River run fails. To change this default behavior, navigate to More Options and select the checkbox to advance the Start Date even if the River run is unsuccessful (Not recommended).


    Contacts

    image.png

    With Contacts Report you can get data on your contacts.
    There are 2 different ways to pull data:

    1. Get all contacts that have been created in the account.
    2. Incremental loading using a range of dates.

    1.1. For all contacts, choose 'Extractmode' : All.
    2.1. For incremental loading, choose 'Extractmode' : Incremental
    and select ‘Date Range’ (See the description above)

    Choose Increment Field:


    • "Recently updated":
      The river will return data in the Date Range, referring to when the contacts were last updated.
      For contacts that were updated or created in the last 30 days.
      Limit : Available data is only 30 days back.
    • "Recently created":
      The river will return data in the Date Range, referring to when the contacts were created.


    Recent Engagements

    To create a Recent Engagements report, complete these steps:

    1. Select Custom Report.

    2. Click Report, then scroll down to Recent Engagements in the drop-down box.

    3. Choose a Time Period.


    If you select Date Range the following options will be available:


    Note:
    You can only get records that have been updated during the last 30 days, with a limit of 10k rows.


    Marketing Emails

    To create a Marketing Emails report, complete these steps:

    1. Select Custom Report.

    2. Click Report, then scroll down to Marketing Emails in the drop-down box.


    3. Check Add Additional Data To include fields like "Widgets" and "Flex Areas" as JSON formatted strings (optional).

    4. Choose a Sub-Category to filter the results (optional).

    5. Pick an Extractmode.


        a. if All extractionmode was chosen, It won't be divided into specific fields and dates.

        b. if an Incremental extractionmode was chosen, Select an Incremental Field.  

        1. Choose a Time Period.

       If you select Date Range the following options will be available:

    Please Note:

    When transitioning from an All to an Incremental extract mode, it is important to clear the fields in your schema and redo the Auto-Mapping process. This is because the mapping process uses a sample of data to determine the columns. If the sample data is restricted to specific dates, then the resulting columns will be limited to those dates as well. 

    Redoing the mapping process ensures that the columns accurately reflect the complete set of data.


    API Usage Limits

    HubSpot has a default API usage limit of 250,000 calls per day https://developers.hubspot.com/apps/api_guidelines .
    This should be more than enough for the average user. If you frequently encounter the API usage limit error from your HubSpot rivers, check out their product-and-services-catalog.

    HubSpot Kits

    Kits are pre-built data models to help data teams immediately create the right data pipelines to tackle common challenges and scenarios. 

    These ready-made pieces of code can be changed or customized to fit your company’s data needs, but they are the best starting point to leverage existing data models that are proven to be effective in their specific use cases.

    Here is the list of available HubSpot Kits:

    Was this article helpful?
    What's Next