HubSpot API Version 3 Walkthrough

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 Endpoints in Hubspot CRM Objects V3 API

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.

Search Endpoints in Hubspot CRM Engagements Objects V3 API

Search Communications

Communications are used to view and manage all types of engagements in one place. The Search Communications endpoint will allow you to retrieve engagement details, type, date, participants, and associated objects
The required scope for this endpoint is crm.objects.engagements.read.

Search Emails

Emails are used to send and track email communications with contacts, leads, and companies. The Search Emails endpoint will allow you to retrieve email content, sender, recipients, subject, send date, and associated objects.
The required scope for this endpoint is crm.objects.emails.read

Search Notes

Notes are used to capture and share information within HubSpot. The Search Notes endpoint will allow you to retrieve note content, creation date, author, and associated objects.
The required scope for this endpoint is crm.objects.notes.read.

Search Postal Mail

Postal Mail is used to send physical letters and documents. The Search Postal Mail endpoint will allow you to track mail status and retrieve details like recipient address, mail type, send date, and associated notes.
The required scope for this endpoint is crm.objects.engagements.read.

Search Tasks

Tasks are used to create and assign actionable items to users or teams. The Search Tasks endpoint will allow you to retrieve task details like name, description, due date, priority, status, assignees, and associated objects.
The required scope for this endpoint is crm.objects.tasks.read.

Search Calls

Calls are used to schedule and manage phone conversations. The Search Calls endpoint will allow you to retrieve details like call date, time, duration, participants, and associated notes.
The required scope for this endpoint is crm.objects.calls.read.

Search Meetings

Meetings are used to schedule and manage in-person or virtual gatherings. The Search Meetings endpoint will allow you to retrieve details like meeting date, time, location, agenda, attendees, and associated notes.
The required scope for this endpoint is crm.objects.meetings.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.