HubSpot Integration with SmythOS
Want to automate your sales, marketing, and service processes? Connect HubSpot to SmythOS and empower your agents to manage contacts, deals, and tickets automatically.
List of HubSpot Components
Quickly compare HubSpot components by what they do and their key I/O. Click any component name to jump directly to its detailed guide.
Component | Action | What it Does | Inputs | Key Outputs | Use Case |
---|---|---|---|---|---|
Create Contact | Write | Creates a new contact record in your CRM. | required email optional firstName , company | id | Automatically adding a new lead from a web form. |
List Contacts | Read | Retrieves a list of all contacts from your HubSpot account. | required trigger optional limit | results , pagingNextAfter | Syncing your contact list to another application. |
Get Contact | Read | Retrieves the details of a single contact by their ID. | required contactId | id , email , firstName | Fetching a customer's details before a call. |
Create Deal | Write | Creates a new deal in a specified pipeline. | required dealname , dealstage , pipeline | id | Creating a new sales opportunity when a lead shows interest. |
List Deals | Read | Retrieves a list of all deals from your HubSpot account. | required trigger optional limit | results , pagingNextAfter | Generating a weekly sales pipeline report. |
Get Deal | Read | Retrieves the details of a single deal by its ID. | required deal_id | id , dealName | Checking the stage and amount of a specific deal. |
Create Ticket | Write | Creates a new customer support ticket. | required subject optional content , pipeline | id | Automatically creating a support ticket from an email. |
List Tickets | Read | Retrieves a list of all support tickets. | required trigger optional limit | results , pagingNextAfter | Auditing open support tickets. |
Get Ticket | Read | Retrieves the details of a single ticket by its ID. | required ticket_id | id , subject , content | Getting context on a support issue before responding. |
Import File | Write | Uploads a file to your HubSpot file manager. | required file_url , folderPath , name | id | Attaching a signed contract to a customer's record. |
Prerequisites
Before you begin, please ensure you have the following:
- An active SmythOS account. (Sign up here).
- A HubSpot account with permissions to create private apps.
- A HubSpot Private App Access Token.
Getting Started With HubSpot
The connection between SmythOS and HubSpot is configured using a secure Access Token from a private app.
Step 1: Get Your HubSpot Access Token
- Log in to your HubSpot account.
- Navigate to Settings (the gear icon in the top navigation).
- In the left menu, go to Integrations > Private Apps.
- Click Create a private app.
- On the Basic Info tab, give your app a name (e.g., "SmythOS Agent") and description.
- Go to the Scopes tab and grant the necessary permissions. For full functionality, you may need scopes like
crm.objects.contacts.write
,crm.objects.deals.read
,tickets
, etc. - Click Create app. A dialog will appear with your Access Token.
- Copy this token immediately. It will not be shown again.
Step 2: Store Your Access Token in SmythOS Vault
Your Access Token is a sensitive credential. Use the SmythOS Vault
to store it securely.
- In your SmythOS dashboard, navigate to the Vault.
- Create a new secret and paste your HubSpot Access Token as the value. Give it a memorable name, like
hubspot_access_token
. - For more details, see the Vault Documentation.
Step 3: Configure a HubSpot Component
- In your SmythOS agent graph, drag and drop any HubSpot component.
- Click the component to open its Settings panel.
- In the
HubSpot Access Token
field, select the secret you saved in the Vault. - Your connection is now configured for that component.
Which HubSpot Component Should I Use?
If you need to… | Target | Use this Component | Why this one? |
---|---|---|---|
Add a new sales lead to your CRM | An email, name, and company | Create Contact | The standard method for creating a new contact record. |
Start a new sales opportunity | A deal name and pipeline stage | Create Deal | The primary way to add a new deal to your sales pipeline. |
Log a new customer issue | A subject and description | Create Ticket | The correct way to create a new ticket in the Service Hub. |
Get a list of all your customers | Your entire contact database | List Contacts | Retrieves all contacts, perfect for syncing or bulk operations. |
Find a specific contact by their email | An email address | Use the Search CRM endpoint via a custom API call. | This allows you to find a contact ID before updating their record. |
Get all deals in your sales pipeline | Your entire deals database | List Deals | Retrieves all deals, which can then be filtered in your agent. |
Component Details
This section provides detailed information for each HubSpot component.
Create Contact
Creates a new contact record in your HubSpot CRM.
Inputs
Field | Type | Required | Notes |
---|---|---|---|
email | string | Yes | The email address of the contact. |
firstName | string | Yes | The first name of the contact. |
lastName | string | Yes | The last name of the contact. |
phone | string | Optional | The phone number of the contact. |
company | string | Optional | The company the contact is associated with. |
website | string | Optional | The website URL for the contact or their company. |
Outputs
Field | Type | Description |
---|---|---|
id | string | The unique identifier of the newly created contact. |
Response | object | The full, raw JSON response from the HubSpot API. |
List Contacts
Retrieves a list of all contacts from your HubSpot CRM.
Inputs
Field | Type | Required | Notes |
---|---|---|---|
trigger | string | Yes | Any value to initiate the component's execution. |
limit | integer | Optional | The number of contact records to retrieve. Default: 10 . |
archived | boolean | Optional | Whether to include archived contacts. Default: false . |
Outputs
Field | Type | Description |
---|---|---|
results | array | A list of contact objects, each with detailed information. |
pagingNextAfter | string | An identifier used for pagination to fetch the next page of results. |
Response | object | The raw JSON response from the API. |
Get Contact
Retrieves detailed information about a specific contact by their ID.
Inputs
Field | Type | Required | Notes |
---|---|---|---|
contactId | string | Yes | The unique identifier for the contact you want to retrieve. |
Outputs
Field | Type | Description |
---|---|---|
id | string | Unique identifier for the contact. |
email | string | Email address of the contact. |
firstName | string | First name of the contact. |
lastName | string | Last name of the contact. |
phone | string | Phone number of the contact. |
company | string | Company associated with the contact. |
Response | object | The raw JSON response from the API. |
Create Deal
Creates a new deal (sales opportunity) in a specified pipeline.
Inputs
Field | Type | Required | Notes |
---|---|---|---|
dealname | string | Yes | The name of the deal (e.g., "ACME Corp - Website Redesign"). |
amount | string | Yes | The monetary value of the deal. |
dealstage | string | Yes | The ID of the deal stage (e.g., appointmentscheduled ). |
pipeline | string | Yes | The ID of the pipeline the deal belongs to (e.g., default ). |
Outputs
Field | Type | Description |
---|---|---|
id | string | The unique identifier of the newly created deal. |
Response | object | The raw JSON response from the API. |
List Deals
Retrieves a list of deals from your HubSpot account.
Inputs
Field | Type | Required | Notes |
---|---|---|---|
trigger | string | Yes | Any value to initiate the execution. |
limit | integer | Optional | The maximum number of deals to return. Default: 10 . |
archived | boolean | Optional | Whether to include archived deals. Default: false . |
Outputs
Field | Type | Description |
---|---|---|
results | array | A list of deal objects in a structured format. |
pagingNextAfter | string | A token to retrieve the next page of results if pagination is required. |
Response | object | The raw JSON response from the API. |
Get Deal
Retrieves detailed information about a specific deal by its ID.
Inputs
Field | Type | Required | Notes |
---|---|---|---|
deal_id | string | Yes | The unique identifier for the deal you want to retrieve. |
Outputs
Field | Type | Description |
---|---|---|
id | string | The unique identifier of the deal. |
amount | string | The monetary value of the deal. |
dealName | string | The name associated with the deal. |
dealStage | string | The current stage of the deal in the sales process. |
pipeline | string | The sales pipeline the deal is part of. |
Response | object | The raw JSON response from the API. |
Create Ticket
Creates a new support ticket in the HubSpot Service Hub.
Inputs
Field | Type | Required | Notes |
---|---|---|---|
subject | string | Yes | The title or subject line of the ticket. |
content | string | Optional | The detailed description of the issue. Default: NOT AVAILABLE . |
pipeline | string | Yes | The ID of the support pipeline. Default: 0 . |
pipeline_stage | string | Yes | The ID of the initial stage (e.g., 1 for "New"). |
ticket_priority | string | Optional | The priority of the ticket. Default: HIGH . |
Outputs
Field | Type | Description |
---|---|---|
id | string | The unique identifier of the newly created ticket. |
Response | object | The raw JSON response from the API. |
List Tickets
Retrieves a list of ticket records from HubSpot.
Inputs
Field | Type | Required | Notes |
---|---|---|---|
trigger | string | Yes | Any value to initiate the execution. |
limit | integer | Optional | Sets the maximum number of tickets to retrieve. Default: 10 . |
archived | boolean | Optional | Whether to include archived tickets. Default: false . |
Outputs
Field | Type | Description |
---|---|---|
results | array | A list of ticket objects with their details. |
pagingNextAfter | string | A token used to fetch the next page of results. |
Response | object | The raw JSON response from the API. |
Get Ticket
Retrieves detailed information about a specific support ticket.
Inputs
Field | Type | Required | Notes |
---|---|---|---|
ticket_id | string | Yes | The unique identifier for the ticket you want to fetch. |
Outputs
Field | Type | Description |
---|---|---|
id | string | The ticket's unique identifier. |
content | string | The detailed description of the ticket. |
subject | string | The subject line of the ticket. |
pipeline | string | The pipeline the ticket belongs to. |
pipelineStage | string | The stage of the ticket within the pipeline. |
ticketPriority | string | The priority level assigned to the ticket. |
Response | object | The raw JSON response from the API. |
Import File
Uploads a file to the HubSpot File Manager.
Component-Specific Settings
- Access: Define the file's privacy:
PUBLIC_INDEXABLE
,PUBLIC_NOT_INDEXABLE
,PRIVATE
, etc.
Inputs
Field | Type | Required | Notes |
---|---|---|---|
file_url | string | Yes | A public URL where the file is currently hosted. |
folderPath | string | Yes | The path within the HubSpot File Manager to store the file (e.g., /contracts ). |
name | string | Yes | The name to assign to the file in HubSpot. |
Outputs
Field | Type | Description |
---|---|---|
id | string | The unique identifier of the uploaded file in HubSpot. |
Response | object | The raw JSON response from the API. |
Best Practices & Advanced Tips
- Secure Your Access Token: Your HubSpot Access Token grants broad access to your CRM data. Always store it in the SmythOS
Vault
. - Use Minimal Scopes: When creating your private app in HubSpot, grant only the permissions your agent needs. If it only manages contacts, it doesn't need access to deals or tickets.
- Handle Pagination: For all
List
components, the API returns paginated results. To get all records, you must build a loop that uses the correspondingNext ... Page
component, passing thepagingNextAfter
token from the previous call until it is no longer returned. - Understand the HubSpot Object Model: To associate objects (e.g., linking a deal to a contact), you will typically need to create or get one object first to retrieve its ID, then use that ID when creating the second object. This may require advanced use of the component's
Body
setting if not available as a direct input.
Troubleshooting Common Issues
-
Error:
401 Unauthorized
- Cause: The Access Token is incorrect, has been revoked, or is missing.
- Solution: Verify that the Access Token in your SmythOS Vault is correct and active. Generate a new token in your HubSpot private app settings if necessary.
-
Error:
403 Forbidden
- Cause: The private app's Access Token does not have the required scopes for the action you are trying to perform (e.g., trying to create a contact without
crm.objects.contacts.write
scope). - Solution: Go to your private app's settings in HubSpot, navigate to the Scopes tab, and ensure all necessary permissions are checked.
- Cause: The private app's Access Token does not have the required scopes for the action you are trying to perform (e.g., trying to create a contact without
-
Error:
404 Not Found
- Cause: An incorrect ID was provided (e.g.,
contactId
,deal_id
). - Solution: Double-check all IDs for typos. Use a
List
orSearch
component to verify that the resource you are trying to access exists.
- Cause: An incorrect ID was provided (e.g.,
What's Next?
You are now ready to build powerful sales, marketing, and service automations with the SmythOS HubSpot Integration!
Consider these ideas:
-
Build an Agent That...
- Manages the entire lead lifecycle. It captures a lead from a form, creates a
Contact
in HubSpot, creates aDeal
, and then assigns aTask
to a sales rep to follow up. - Syncs data from your e-commerce platform. When a new customer makes a purchase on Shopify, the agent finds or creates a
Contact
in HubSpot and updates a custom property with their total order value. - Automates support. It receives an email, uses an LLM to determine if it's a bug report, and if so, creates a new
Ticket
in the Service Hub.
- Manages the entire lead lifecycle. It captures a lead from a form, creates a
-
Explore Other Integrations:
- When a new contact is created, trigger a workflow to add them to a specific marketing list in Mailchimp or Klaviyo.
- When a deal is marked "Closed-Won," trigger an agent to create a new client record in your accounting software and a new project in Asana.
- Use the Twilio Integration to send an SMS notification to a sales rep when a high-priority deal is created for them.