HubSpot API Version 3 Walkthrough
  • 4 Minutes to read
  • Dark
  • PDF

HubSpot API Version 3 Walkthrough

  • Dark
  • PDF

Article Summary


HubSpot API v3 has a powerful set of tools that allows developers to build custom integration that interacts with HubSpot's CRM, Marketing, Sales, and Service platforms. Users can automate Rivers, streamline processes, manage data, and create Custom Reports.

Rivery supports the Hubspot API v3 for integrating data from the following Search endpoints:
Contacts, Deals, Companies, Line Items, Products, Tickets and Quotes.
This document provides a detailed description of each endpoint, including the required scopes and guidelines for flattening report array values.

Custom Reports

Select a specific report to pull data from the Hubspot API v3 after you've established a connection.
The following image provides an overview of the various custom reports:


Here is a list of all version 3 reports:

Search Contacts

To locate contacts that interact with your business, you can use the Search Contacts endpoint, which retrieves contact data and related properties. To access this endpoint, you need the scope.

Search Deals

Deals represent potential sales opportunities or deals in progress. Deals are tracked through your sales process in pipeline stages until won or lost. The Search Deals endpoint allows you to retrieve deals’ data and associated properties. The required scope for this endpoint is

Search Companies

Companies represent organizations or businesses that interact with your business. The Search Companies endpoint allows you to retrieve companies' data and associated properties. The required scope for this endpoint is

Search Line Items

Line Items represent the products or services that you sell to your customers. The Search Line Items endpoint allows you to retrieve line items’ data and associated properties. The required scopes for this endpoint are e-commerce(standard), (granular).

Search Products

Products represent the individual products or services that your business offers. The Search Products endpoint allows you to retrieve products’ data and associated properties. The required scope for this endpoint is e-commerce(standard).

Search Tickets

Tickets represent customer inquiries or issues that require support or resolution. The Search Tickets endpoint allows you to retrieve tickets’ data and associated properties. The required scope for this endpoint is tickets(standard).

Search Quotes

HubSpot employs quotes as a means to communicate pricing details to prospective customers. The endpoints for Quotes enable users to generate, access, and synchronize quotes across HubSpot. The required scopes for this endpoint are e-commerce(standard),, and

After selecting the required report, you can specify the properties to be included in your schema mapping:


Please Note:
By default, the schema mapping will include the following properties - hs_createdate, hs_lastmodifieddate, and hs_object_id.

Flatten Arrays

Rivery provides the ability to flatten your Hubspot CRM report array values. Flattening an array means transforming a multidimensional array into a one-dimensional array by concatenating all its elements.

If you would like to flatten report array values, follow the steps below:

  1. Check the “Flatten Arrays” checkbox.
  2. After checking the checkbox, each of the report's array values will be an individual column. Each array will be given an "array_name" alias in the schema mapping.
    For example, the report's Properties array will have an alias of "properties_" for all values.

For more information about the v3 reports consult Hubspot's documentation.

Add Associated Object(s)

HubSpot provides a field that allows users to demonstrate the relationships between different objects by associating records of various objects using the "Add Associated Objects" field. For instance, you can link multiple contacts to a company and then connect the company and relevant contacts to a deal. This helps in organizing and tracking the flow of information between different objects in a structured manner.


To add object associations in any of your v3 Search endpoints, users can use the "Associated Objects" dropdown list in the user interface. This enables you to select the type of object you wish to associate, such as Contacts or Companies, and specify the records to be linked. By doing so, a network of interconnected objects can be established, which can be readily accessed and analyzed within the HubSpot platform. In addition, this can be viewed within Rivery by navigating to the Schema tab and locating the "associations" array.

Here's an example:


This is where you can locate it:


Extract Method

When using the Extract Method, you have the option to retrieve all data, without any time restrictions, by selecting 'All' or or 'Incremental' to have greater control over data retrieval based on dates.

Here's an example:

  • Start Date is mandatory.
  • Data can be retrieved for the date range specified between the start and end dates.
  • If you leave the end date blank, the data will be pulled at the current time of the river's run.
  • Dates timezone: UTC time.
  • The Start Date won't be advanced if a River run is unsuccessful.
    If you don't want this default setting, click More Options and check the box to advance the start date even if the River run is unsuccessful (Not recommended).
  • Use the Last Days Back For Each Run option to gather data from a specified number of days prior to the selected start date.

When the data you're fetching is large, especially if you're reaching size or timeout constraints, "Split your chunks by" is an option that may be used to split the data by chunks.

Was this article helpful?