HubSpot | Documentation

The HubSpot component is an application component that allows users to use HubSpot application to do various tasks. It can carry out the following tasks:

Get Contact
Create Contact
Get Deal
Create Deal
Update Deal
Get Company
Create Company
Get Ticket
Create Ticket
Update Ticket
Get Thread
Insert Message
Retrieve Association
Get Owner
Get All

#Release Stage

Alpha

#Configuration

The component definition and tasks are defined in the definition.yaml and tasks.yaml files respectively.

#Setup

In order to communicate with HubSpot, the following connection details need to be provided. You may specify them directly in a pipeline recipe as key-value pairs within the component's setup block, or you can create a Connection from the Integration Settings page and reference the whole setup as setup: ${connection.<my-connection-id>}.

Field	Field ID	Type	Note
Token (required)	`token`	string	Fill in your HubSpot private app access token. Go here for more information.

#Supported Tasks

#Get Contact

Get contact information using contact ID or Email

Input	Field ID	Type	Description
Task ID (required)	`task`	string	`TASK_GET_CONTACT`
Contact ID or Email (required)	`contact-id-or-email`	string	Input contact ID or email. If the input has @, it will search the contact using email.

Output	Field ID	Type	Description
Owner ID (optional)	`owner-id`	string	The user who is assigned to the object.
Email Address (optional)	`email`	string	Email address.
First Name (optional)	`first-name`	string	First name.
Last Name (optional)	`last-name`	string	Last name.
Phone Number (optional)	`phone-number`	string	Phone number. If you plan to use the number formatting feature in HubSpot, use country code + phone number. Example: +886xxxxxxxxx.
Company (optional)	`company`	string	Company.
Job Title (optional)	`job-title`	string	Job title.
Lifecycle Stage (optional)	`lifecycle-stage`	string	Lifecycle stages are used to track how contacts or companies move forward in your process. Default format is in small letters, all words are combined. Example: salesqualifiedlead. However, remember to check internal value for custom fields.
Lead Status (optional)	`lead-status`	string	The contact's sales, prospecting or outreach status. Default format is in capital letters, with _ as space. Example: IN_PROGRESS. However, remember to check internal value for custom fields.
Contact ID	`contact-id`	string	Contact ID.

#Create Contact

Create new contact

Input	Field ID	Type	Description
Task ID (required)	`task`	string	`TASK_CREATE_CONTACT`
Owner ID	`owner-id`	string	The user who is assigned to the object.
Email Address (required)	`email`	string	Email address.
First Name	`first-name`	string	First name.
Last Name	`last-name`	string	Last name.
Phone Number	`phone-number`	string	Phone number. If you plan to use the number formatting feature in HubSpot, use country code + phone number. Example: +886xxxxxxxxx.
Company	`company`	string	Company.
Job Title	`job-title`	string	Job title.
Lifecycle Stage	`lifecycle-stage`	string	Lifecycle stages are used to track how contacts or companies move forward in your process. Default format is in small letters, all words are combined. Example: salesqualifiedlead. However, remember to check internal value for custom fields.
Lead Status	`lead-status`	string	The contact's sales, prospecting or outreach status. Default format is in capital letters, with _ as space. Example: IN_PROGRESS. However, remember to check internal value for custom fields.
Create Object -> Deal Association Using Deal IDs	`create-deals-association`	array[string]	Existing deal IDs to be associated with the object.
Create Object -> Company Association Using Company IDs	`create-companies-association`	array[string]	Existing company IDs to be associated with the object.
Create Object -> Ticket Association Using Ticket IDs	`create-tickets-association`	array[string]	Existing ticket IDs to be associated with the object.

Output	Field ID	Type	Description
Contact ID	`contact-id`	string	Contact ID.

#Get Deal

Get deal information using deal ID

Input	Field ID	Type	Description
Task ID (required)	`task`	string	`TASK_GET_DEAL`
Deal ID (required)	`deal-id`	string	Input deal ID.

Output	Field ID	Type	Description
Owner ID (optional)	`owner-id`	string	The user who is assigned to the object.
Deal Name	`deal-name`	string	Deal name.
Pipeline	`pipeline`	string	A pipeline is the place where you document and manage how your prospects move through the steps of your sales process. HubSpot uses interval value rather than the name displayed in the view.
Deal Stage	`deal-stage`	string	Deal stages allow you to categorize and track the progress of the deals that you are working on. Default format is in small letters, all words are combined. Example: qualifiedtobuy. However, remember to check internal value for custom fields.
Amount (optional)	`amount`	number	The total amount of the deal.
Deal Type (optional)	`deal-type`	string	The type of deal. Default format is in small letters, all words are combined. Example: newbusiness. However, remember to check internal value for custom fields.
Close Date (optional)	`close-date`	string	Date the deal was closed. Set automatically by HubSpot. Format is in ISO 8601. Example: 2024-07-01T11:47:40.388Z.
Create Date (optional)	`create-date`	string	Create date. Format is in ISO 8601. Example: 2024-07-01T11:47:40.388Z.
Associated Contact IDs (optional)	`associated-contact-ids`	array[string]	Contact IDs associated with the object.

#Create Deal

Create new deal

Input	Field ID	Type	Description
Task ID (required)	`task`	string	`TASK_CREATE_DEAL`
Owner ID	`owner-id`	string	The user who is assigned to the object.
Deal Name (required)	`deal-name`	string	Deal name.
Pipeline (required)	`pipeline`	string	A pipeline is the place where you document and manage how your prospects move through the steps of your sales process. HubSpot uses interval value rather than the name displayed in the view.
Deal Stage (required)	`deal-stage`	string	Deal stages allow you to categorize and track the progress of the deals that you are working on. Default format is in small letters, all words are combined. Example: qualifiedtobuy. However, remember to check internal value for custom fields.
Amount	`amount`	number	The total amount of the deal.
Deal Type	`deal-type`	string	The type of deal. Default format is in small letters, all words are combined. Example: newbusiness. However, remember to check internal value for custom fields.
Close Date	`close-date`	string	Date the deal was closed. Set automatically by HubSpot. Format is in ISO 8601. Example: 2024-07-01T11:47:40.388Z.
Create Object -> Contact Association Using Contact IDs	`create-contacts-association`	array[string]	Existing contact IDs to be associated with the object.

Output	Field ID	Type	Description
Deal ID	`deal-id`	string	Deal ID.

#Update Deal

Update existing deal

Input	Field ID	Type	Description
Task ID (required)	`task`	string	`TASK_UPDATE_DEAL`
Deal ID (required)	`deal-id`	string	Input deal ID.
Owner ID	`owner-id`	string	The user who is assigned to the object.
Deal Name	`deal-name`	string	Deal name.
Pipeline	`pipeline`	string	A pipeline is the place where you document and manage how your prospects move through the steps of your sales process. HubSpot uses interval value rather than the name displayed in the view.
Deal Stage	`deal-stage`	string	Deal stages allow you to categorize and track the progress of the deals that you are working on. Default format is in small letters, all words are combined. Example: qualifiedtobuy. However, remember to check internal value for custom fields.
Amount	`amount`	number	The total amount of the deal.
Deal Type	`deal-type`	string	The type of deal. Default format is in small letters, all words are combined. Example: newbusiness. However, remember to check internal value for custom fields.
Close Date	`close-date`	string	Date the deal was closed. Set automatically by HubSpot. Format is in ISO 8601. Example: 2024-07-01T11:47:40.388Z.
Create Object -> Contact Association Using Contact IDs	`create-contacts-association`	array[string]	Existing contact IDs to be associated with the object.

Output	Field ID	Type	Description
Updated by User ID	`updated-by-user-id`	string	User ID that updated the deal.
Updated At	`updated-at`	string	The time when the deal was updated.

#Get Company

Get company information using company ID

Input	Field ID	Type	Description
Task ID (required)	`task`	string	`TASK_GET_COMPANY`
Company ID (required)	`company-id`	string	Input company ID.

Output	Field ID	Type	Description
Owner ID (optional)	`owner-id`	string	The user who is assigned to the object.
Company Name (optional)	`company-name`	string	Company name.
Company Domain (optional)	`company-domain`	string	The domain name of the company.
Description (optional)	`description`	string	Description of the company.
Phone Number (optional)	`phone-number`	string	Phone number of the company. If you plan to use the number formatting feature in HubSpot, use country code + phone number. Example: +886xxxxxxxxx.
Industry (optional)	`industry`	string	The industry the company belongs to. Default format is in capital letters, with _ as space. Example: BROADCAST_MEDIA.
Company Type (optional)	`company-type`	string	Type of company. Default format is capital letter. Example: RESELLER.
City (optional)	`city`	string	City.
State (optional)	`state`	string	State.
Country (optional)	`country`	string	Country.
Postal Code (optional)	`postal-code,`	string	Postal code.
Time Zone (optional)	`time-zone`	string	Time zone.
Annual Revenue (optional)	`annual-revenue`	number	Annual revenue.
Total Revenue (optional)	`total-revenue`	number	Total revenue. Calculated automatically by HubSpot.
Linkedin Page (optional)	`linkedin-page`	string	Linkedin page of the company.
Associated Contact IDs (optional)	`associated-contact-ids`	array[string]	Contact IDs associated with the object.

#Create Company

Create new company

Input	Field ID	Type	Description
Task ID (required)	`task`	string	`TASK_CREATE_COMPANY`
Owner ID	`owner-id`	string	The user who is assigned to the object.
Company Name	`company-name`	string	Company name.
Company Domain (required)	`company-domain`	string	The domain name of the company.
Description	`description`	string	Description of the company.
Phone Number	`phone-number`	string	Phone number of the company. If you plan to use the number formatting feature in HubSpot, use country code + phone number. Example: +886xxxxxxxxx.
Industry	`industry`	string	The industry the company belongs to. Default format is in capital letters, with _ as space. Example: BROADCAST_MEDIA.
Company Type	`company-type`	string	Type of company. Default format is capital letter. Example: RESELLER.
City	`city`	string	City.
State	`state`	string	State.
Country	`country`	string	Country.
Postal Code	`postal-code,`	string	Postal code.
Time Zone	`time-zone`	string	Time zone.
Annual Revenue	`annual-revenue`	number	Annual revenue.
Linkedin Page	`linkedin-page`	string	Linkedin page of the company.
Create Object -> Contact Association Using Contact IDs	`create-contacts-association`	array[string]	Existing contact IDs to be associated with the object.

Output	Field ID	Type	Description
Company ID	`company-id`	string	Company ID.

#Get Ticket

Get ticket information using ticket ID

Input	Field ID	Type	Description
Task ID (required)	`task`	string	`TASK_GET_TICKET`
Ticket ID (required)	`ticket-id`	string	Input ticket ID.

Output	Field ID	Type	Description
Owner ID (optional)	`owner-id`	string	The user who is assigned to the object.
Ticket Name	`ticket-name`	string	Ticket name.
Ticket Status	`ticket-status`	string	The pipeline stage that contains this ticket. Default format is number. Example: 1. However, remember to check internal value for custom fields. Note: In Instill AI, ticket-status is displayed as string because of the possible custom internal value.
Pipeline	`pipeline`	string	A pipeline organizes and tracks the progression of tickets through various stages of resolution within your support process. HubSpot uses interval value rather than the name displayed in the view.
Categories (optional)	`categories`	array[string]	The main reason customer reached out for help. Default format is in capital letters. Example: BILLING_ISSUE. However, remember to check internal value for custom fields.
Priority (optional)	`priority`	string	The level of attention needed on the ticket. Default format is in capital letters. Example: MEDIUM. However, remember to check internal value for custom fields.
Source (optional)	`source`	string	Channel where ticket was originally submitted. Default format is in capital letters. Example: EMAIL.
Record Source (optional)	`record-source`	string	How this record was created.
Create Date (optional)	`create-date`	string	Create date. Format is in ISO 8601. Example: 2024-07-01T11:47:40.388Z.
Last Modified Date (optional)	`last-modified-date`	string	Last modified date. Format is in ISO 8601. Example: 2024-07-01T11:47:40.388Z.
Associated Contact IDs (optional)	`associated-contact-ids`	array[string]	Contact IDs associated with the object.

#Create Ticket

Create new ticket

Input	Field ID	Type	Description
Task ID (required)	`task`	string	`TASK_CREATE_TICKET`
Owner ID	`owner-id`	string	The user who is assigned to the object.
Ticket Name (required)	`ticket-name`	string	Ticket name.
Ticket Status (required)	`ticket-status`	string	The pipeline stage that contains this ticket. Default format is number. Example: 1. However, remember to check internal value for custom fields. Note: In Instill AI, ticket-status is displayed as string because of the possible custom internal value.
Pipeline (required)	`pipeline`	string	A pipeline organizes and tracks the progression of tickets through various stages of resolution within your support process. HubSpot uses interval value rather than the name displayed in the view.
Categories	`categories`	array[string]	The main reason customer reached out for help. Default format is in capital letters. Example: BILLING_ISSUE. However, remember to check internal value for custom fields.
Priority	`priority`	string	The level of attention needed on the ticket. Default format is in capital letters. Example: MEDIUM. However, remember to check internal value for custom fields.
Source	`source`	string	Channel where ticket was originally submitted. Default format is in capital letters. Example: EMAIL.
Create Object -> Contact Association Using Contact IDs	`create-contacts-association`	array[string]	Existing contact IDs to be associated with the object.

Output	Field ID	Type	Description
Ticket ID	`ticket-id`	string	Ticket ID.

#Update Ticket

Update existing ticket

Input	Field ID	Type	Description
Task ID (required)	`task`	string	`TASK_UPDATE_TICKET`
Owner ID	`owner-id`	string	The user who is assigned to the object.
Ticket ID (required)	`ticket-id`	string	Input ticket ID.
Ticket Name	`ticket-name`	string	Ticket name.
Ticket Status	`ticket-status`	string	The pipeline stage that contains this ticket. Default format is number. Example: 1. However, remember to check internal value for custom fields. Note: In Instill AI, ticket-status is displayed as string because of the possible custom internal value.
Pipeline	`pipeline`	string	A pipeline organizes and tracks the progression of tickets through various stages of resolution within your support process. HubSpot uses interval value rather than the name displayed in the view.
Categories	`categories`	array[string]	The main reason customer reached out for help. Default format is in capital letters. Example: BILLING_ISSUE. However, remember to check internal value for custom fields.
Priority	`priority`	string	The level of attention needed on the ticket. Default format is in capital letters. Example: MEDIUM. However, remember to check internal value for custom fields.
Source	`source`	string	Channel where ticket was originally submitted. Default format is in capital letters. Example: EMAIL.
Create Object -> Contact Association Using Contact IDs	`create-contacts-association`	array[string]	Existing contact IDs to be associated with the object.

Output	Field ID	Type	Description
Updated At	`updated-at`	string	The time when the ticket was updated.

#Get Thread

Retrieve all the messages inside a thread (conversation inbox). The messages will be sorted from most recent to least recent. Note: This task uses Conversation API from HubSpot, which is still in BETA.

Input	Field ID	Type	Description
Task ID (required)	`task`	string	`TASK_GET_THREAD`
Thread ID (required)	`thread-id`	string	Input thread ID.

Output	Field ID	Type	Description
Messages	`results`	array[object]	An array of messages.
Number of Messages	`no-of-messages`	integer	The number of messages in a thread.

Output Objects in Get Thread

Messages

Field	Field ID	Type	Note
Channel Account ID	`channel-account-id`	string	The ID of an account that is part of the channel-id channel.
Channel ID	`channel-id`	string	The ID of a generic channel returned from the channels endpoint, like 1000 for live chat, 1001 for Facebook Messenger, 1002 for email, etc.
Start Conversation Message	`created-at`	string	message to start a conversation.
Recipients	`recipients`	array	Recipients' information.
Sender	`sender`	object	Sender's information.
Subject	`subject`	string	The subject of the message.
Text	`text`	string	The content of the message.

Sender

Field	Field ID	Type	Note
Actor ID	`sender-actor-id`	string	The actor ID of the sender.
Name	`sender-name`	string	The name of the sender.
Type	`sender-type`	string	Specify the category of sender information.
Value	`sender-value`	string	Contains the actual sender information (e.g.: email address).

Recipients

Field	Field ID	Type	Note
Name	`name`	string	The name of the recipient.
Type	`type`	string	Specify the category of recipient information.
Value	`value`	string	Contains the actual recipient information (e.g.: email address).

#Insert Message

Insert message into a thread (only support email thread)

Input	Field ID	Type	Description
Task ID (required)	`task`	string	`TASK_INSERT_MESSAGE`
Thread ID (required)	`thread-id`	string	Input thread ID.
Sender Actor ID (required)	`sender-actor-id`	string	Input sender actor id. Example: A-12345678. To obtain this, it is recommended to use and copy the 'Get Thread task' sender output. For more information about actor id.
Recipients (required)	`recipients`	array[string]	Recipients of the message.
Channel Account ID (required)	`channel-account-id`	string	The ID of an account that is part of the channel-id channel. On an existing thread, it is recommended to copy channel-account-id of the most recent message on the thread.
Subject (required)	`subject`	string	The subject of the message.
Text (required)	`text`	string	The body of the message.

Output	Field ID	Type	Description
Status	`status`	string	The message status.

#Retrieve Association

Get the object IDs associated with contact ID (contact->objects). If you are trying to do the opposite (object->contacts), it is possible using the other tasks. Example: Go to get deal task to obtain deal->contacts. Remember to check that the contact ID you input exists, because there won't be an error message if the contact ID doesn't exist.

Input	Field ID	Type	Description
Task ID (required)	`task`	string	`TASK_RETRIEVE_ASSOCIATION`
Contact ID (required)	`contact-id`	string	Input contact ID.
Object Type (required)	`object-type`	string	Input object type (CRM objects or 'Threads'). Note: CRM objects include 'Deals', 'Companies', 'Tickets', etc. Enum values `Deals` `Companies` `Tickets` `Threads`

Output	Field ID	Type	Description
Object ID Array	`object-ids`	array[string]	An array of object ID associated with the contact.
Object IDs Length	`object-ids-length`	integer	The number of object IDs.

#Get Owner

Get information about HubSpot owner using either owner ID or user ID. For more information about owner, please go to here

Input	Field ID	Type	Description
Task ID (required)	`task`	string	`TASK_GET_OWNER`
ID Type (required)	`id-type`	string	Specify the type of ID you will use to get owner's information. Enum values `Owner ID` `User ID`
ID (required)	`id`	string	Can either be owner ID or user ID; according to the ID type you selected.

Output	Field ID	Type	Description
First Name	`first-name`	string	First name.
Last Name	`last-name`	string	Last name.
Email	`email`	string	Email.
Owner ID	`owner-id`	string	Owner ID. Usually used to associate the owner with other objects.
User ID	`user-id`	string	User ID. Usually used to indicate the owner who performed the action. User ID can be seen in Update Deal task output.
Teams (optional)	`teams`	array[object]	The owner's teams information.
Created At	`created-at`	string	Created at.
Updated At	`updated-at`	string	Updated at.
Archived	`archived`	boolean	Archived.

Output Objects in Get Owner

Teams

Field	Field ID	Type	Note
Team ID	`team-id`	string	The ID of the team.
Team Name	`team-name`	string	The name of the team.
Team Primary	`team-primary`	boolean	Indicate whether this team is the primary team of the owner.

#Get All

Get all the IDs for a specific object (e.g. all contact IDs)

Input	Field ID	Type	Description
Task ID (required)	`task`	string	`TASK_GET_ALL`
Object Type (required)	`object-type`	string	The object which you want to get all IDs for. Enum values `Contacts` `Deals` `Companies` `Tickets` `Threads` `Owners`

Output	Field ID	Type	Description
Object ID Array	`object-ids`	array[string]	An array of object ID.
Object IDs Length	`object-ids-length`	integer	The number of object IDs.