HubSpot API Version 3

Introduction

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 crm.objects.contacts.read 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 crm.objects.deals.read.

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 crm.objects.companies.read.

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), crm.objects.line_items.read (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), crm.objects.quotes.read, and crm.schemas.quotes.read.

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:

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.