HubSpot API version 3 walkthrough
HubSpot API v3 has powerful tools that let developers build custom integrations that interact with HubSpot's CRM, Marketing, Sales, and Service platforms. You can automate Rivers, streamline processes, manage data, and create custom reports.
Data Integration supports the Hubspot API v3 for integrating data from the following Search endpoints: Contacts, Deals, Companies, Line Items, Products, Tickets and Quotes.
Custom reports
Select a specific report to pull data from the Hubspot API v3 after creating a connection.
Here is a list of version three reports:
Search reports 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. You need the crm.objects.contacts.read scope to access this endpoint.
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 lets you 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 lets you 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 lets you 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 lets you 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 need support or resolution. The search tickets endpoint lets you 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 search quotes enable you 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 retrieves 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 retrieves 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 retrieves 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 lets you track mail status and retrieve details such as 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 retrieves task details such as 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 retrieves details such as 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 retrieves details such as 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 include in your schema mapping.
By default, the schema mapping will include the following properties: hs_createdate, hs_lastmodifieddate, and hs_object_id.
Flatten arrays
Data Integration 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.
Procedure
- Select the Flatten Arrays checkbox.
- Each report's array value will be an individual column. In the schema mapping, each array will be provided with an array_name alias. For example, the report's Properties array will have an alias of properties for all values.
To learn more about the v3 reports, refer to Hubspot's documentation.
Add associated object(s)
HubSpot provides a field that lets you 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 organize and track the flow of information between different objects in a structured manner.
To add object associations in any of your v3 Search endpoints, you can use the "Associated Objects" drop-down 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. A network of interconnected objects can be established and readily accessed and analyzed within the HubSpot platform. Additionally, this can be viewed within Data Integration by navigating to the "Schema" tab and locating the "associations" array.
Extract method
When using the Extract Method, you can retrieve all data, without any time restrictions, by selecting All or Incremental to have greater control over data retrieval based on dates.
- Start Date is mandatory.
- Data can be retrieved for the date range 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.
- Date timezone: UTC.
- 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 before the selected start date.
When the data you are fetching is large and you are reaching size or timeout constraints, use the Split your chunks by option to split the data into chunks.
