Skip to main content

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.

TL;DR

Securely link your HubSpot account to SmythOS using a private app Access Token. Then, use our suite of components to automate your entire customer lifecycle, from creating new contacts to managing support tickets.

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.

ComponentActionWhat it DoesInputsKey OutputsUse Case
Create ContactWriteCreates a new contact record in your CRM.required email
optional firstName, company
idAutomatically adding a new lead from a web form.
List ContactsReadRetrieves a list of all contacts from your HubSpot account.required trigger
optional limit
results, pagingNextAfterSyncing your contact list to another application.
Get ContactReadRetrieves the details of a single contact by their ID.required contactIdid, email, firstNameFetching a customer's details before a call.
Create DealWriteCreates a new deal in a specified pipeline.required dealname, dealstage, pipelineidCreating a new sales opportunity when a lead shows interest.
List DealsReadRetrieves a list of all deals from your HubSpot account.required trigger
optional limit
results, pagingNextAfterGenerating a weekly sales pipeline report.
Get DealReadRetrieves the details of a single deal by its ID.required deal_idid, dealNameChecking the stage and amount of a specific deal.
Create TicketWriteCreates a new customer support ticket.required subject
optional content, pipeline
idAutomatically creating a support ticket from an email.
List TicketsReadRetrieves a list of all support tickets.required trigger
optional limit
results, pagingNextAfterAuditing open support tickets.
Get TicketReadRetrieves the details of a single ticket by its ID.required ticket_idid, subject, contentGetting context on a support issue before responding.
Import FileWriteUploads a file to your HubSpot file manager.required file_url, folderPath, nameidAttaching a signed contract to a customer's record.
INFO
Why Integrate HubSpot with Your Agent?

HubSpot is a central CRM for managing the entire customer lifecycle. Integrating it with SmythOS allows you to build powerful agents that connect your sales, marketing, and service operations to all your other systems.

  • Automate Lead Management: Create agents that capture leads from website forms, social media, or other channels and automatically create new contact and deal records in HubSpot.
  • Streamline Sales Processes: Build an agent that, when a deal is moved to a new stage in HubSpot, automatically sends a follow-up email, schedules a meeting, and creates a task for the sales representative.
  • Enhance Customer Service: When a customer submits a support request via email or chat, an agent can automatically create a new ticket in the HubSpot Service Hub, assign it to the right team, and send an automated confirmation to the customer.
  • Data Synchronization: Keep your HubSpot data in sync with other platforms. An agent can update contact properties in HubSpot when they change in your e-commerce platform or billing system.

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

  1. Log in to your HubSpot account.
  2. Navigate to Settings (the gear icon in the top navigation).
  3. In the left menu, go to Integrations > Private Apps.
  4. Click Create a private app.
  5. On the Basic Info tab, give your app a name (e.g., "SmythOS Agent") and description.
  6. 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.
  7. Click Create app. A dialog will appear with your Access Token.
  8. 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.

  1. In your SmythOS dashboard, navigate to the Vault.
  2. Create a new secret and paste your HubSpot Access Token as the value. Give it a memorable name, like hubspot_access_token.
  3. For more details, see the Vault Documentation.

Step 3: Configure a HubSpot Component

  1. In your SmythOS agent graph, drag and drop any HubSpot component.
  2. Click the component to open its Settings panel.
  3. In the HubSpot Access Token field, select the secret you saved in the Vault.
  4. Your connection is now configured for that component.
Heads-up
You must add the Access Token from the Vault to each HubSpot component you use. This ensures all your API calls are properly authenticated.

Which HubSpot Component Should I Use?

If you need to…TargetUse this ComponentWhy this one?
Add a new sales lead to your CRMAn email, name, and companyCreate ContactThe standard method for creating a new contact record.
Start a new sales opportunityA deal name and pipeline stageCreate DealThe primary way to add a new deal to your sales pipeline.
Log a new customer issueA subject and descriptionCreate TicketThe correct way to create a new ticket in the Service Hub.
Get a list of all your customersYour entire contact databaseList ContactsRetrieves all contacts, perfect for syncing or bulk operations.
Find a specific contact by their emailAn email addressUse 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 pipelineYour entire deals databaseList DealsRetrieves 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.

INFO
This component requires an Access Token for authentication, as detailed in the Getting Started section.

Inputs

FieldTypeRequiredNotes
emailstringYesThe email address of the contact.
firstNamestringYesThe first name of the contact.
lastNamestringYesThe last name of the contact.
phonestringOptionalThe phone number of the contact.
companystringOptionalThe company the contact is associated with.
websitestringOptionalThe website URL for the contact or their company.

Outputs

FieldTypeDescription
idstringThe unique identifier of the newly created contact.
ResponseobjectThe full, raw JSON response from the HubSpot API.
Use Case

An agent is connected to a "Contact Us" form. When a new form is submitted, the agent uses this component to automatically create a new contact record in HubSpot and assign it to a sales representative.

List Contacts

Retrieves a list of all contacts from your HubSpot CRM.

INFO
This component requires an Access Token for authentication, as detailed in the Getting Started section.

Inputs

FieldTypeRequiredNotes
triggerstringYesAny value to initiate the component's execution.
limitintegerOptionalThe number of contact records to retrieve. Default: 10.
archivedbooleanOptionalWhether to include archived contacts. Default: false.

Outputs

FieldTypeDescription
resultsarrayA list of contact objects, each with detailed information.
pagingNextAfterstringAn identifier used for pagination to fetch the next page of results.
ResponseobjectThe raw JSON response from the API.
Use Case

A marketing agent runs weekly, uses this component to fetch all new contacts, and syncs them to a separate email marketing platform.

Get Contact

Retrieves detailed information about a specific contact by their ID.

INFO
This component requires an Access Token for authentication, as detailed in the Getting Started section.

Inputs

FieldTypeRequiredNotes
contactIdstringYesThe unique identifier for the contact you want to retrieve.

Outputs

FieldTypeDescription
idstringUnique identifier for the contact.
emailstringEmail address of the contact.
firstNamestringFirst name of the contact.
lastNamestringLast name of the contact.
phonestringPhone number of the contact.
companystringCompany associated with the contact.
ResponseobjectThe raw JSON response from the API.
Use Case

Before sending a personalized email, an agent uses this component to fetch the contact's firstName and company to include in the message.

Create Deal

Creates a new deal (sales opportunity) in a specified pipeline.

INFO
This component requires an Access Token for authentication, as detailed in the Getting Started section.

Inputs

FieldTypeRequiredNotes
dealnamestringYesThe name of the deal (e.g., "ACME Corp - Website Redesign").
amountstringYesThe monetary value of the deal.
dealstagestringYesThe ID of the deal stage (e.g., appointmentscheduled).
pipelinestringYesThe ID of the pipeline the deal belongs to (e.g., default).

Outputs

FieldTypeDescription
idstringThe unique identifier of the newly created deal.
ResponseobjectThe raw JSON response from the API.
Use Case

After an initial discovery call, an agent creates a new deal in the "Sales Pipeline" with the stage set to "Qualified to Buy," including the estimated deal amount.

List Deals

Retrieves a list of deals from your HubSpot account.

INFO
This component requires an Access Token for authentication, as detailed in the Getting Started section.

Inputs

FieldTypeRequiredNotes
triggerstringYesAny value to initiate the execution.
limitintegerOptionalThe maximum number of deals to return. Default: 10.
archivedbooleanOptionalWhether to include archived deals. Default: false.

Outputs

FieldTypeDescription
resultsarrayA list of deal objects in a structured format.
pagingNextAfterstringA token to retrieve the next page of results if pagination is required.
ResponseobjectThe raw JSON response from the API.
Use Case

A sales manager agent runs every Monday morning, uses List Deals to get all deals in the "Negotiation" stage, and sends a summary to a leadership channel in Microsoft Teams.

Get Deal

Retrieves detailed information about a specific deal by its ID.

INFO
This component requires an Access Token for authentication, as detailed in the Getting Started section.

Inputs

FieldTypeRequiredNotes
deal_idstringYesThe unique identifier for the deal you want to retrieve.

Outputs

FieldTypeDescription
idstringThe unique identifier of the deal.
amountstringThe monetary value of the deal.
dealNamestringThe name associated with the deal.
dealStagestringThe current stage of the deal in the sales process.
pipelinestringThe sales pipeline the deal is part of.
ResponseobjectThe raw JSON response from the API.
Use Case

When a deal is about to close, an agent fetches its details using this component to prepare a contract with the correct dealName and amount.

Create Ticket

Creates a new support ticket in the HubSpot Service Hub.

INFO
This component requires an Access Token for authentication, as detailed in the Getting Started section.

Inputs

FieldTypeRequiredNotes
subjectstringYesThe title or subject line of the ticket.
contentstringOptionalThe detailed description of the issue. Default: NOT AVAILABLE.
pipelinestringYesThe ID of the support pipeline. Default: 0.
pipeline_stagestringYesThe ID of the initial stage (e.g., 1 for "New").
ticket_prioritystringOptionalThe priority of the ticket. Default: HIGH.

Outputs

FieldTypeDescription
idstringThe unique identifier of the newly created ticket.
ResponseobjectThe raw JSON response from the API.
Use Case

An agent monitors a support email inbox. When a new email arrives, it parses the subject and body and uses this component to create a new ticket in the "Customer Support" pipeline.

List Tickets

Retrieves a list of ticket records from HubSpot.

INFO
This component requires an Access Token for authentication, as detailed in the Getting Started section.

Inputs

FieldTypeRequiredNotes
triggerstringYesAny value to initiate the execution.
limitintegerOptionalSets the maximum number of tickets to retrieve. Default: 10.
archivedbooleanOptionalWhether to include archived tickets. Default: false.

Outputs

FieldTypeDescription
resultsarrayA list of ticket objects with their details.
pagingNextAfterstringA token used to fetch the next page of results.
ResponseobjectThe raw JSON response from the API.
Use Case

A support manager agent runs daily to list all tickets with "High" priority that haven't been updated in 24 hours and sends a notification.

Get Ticket

Retrieves detailed information about a specific support ticket.

INFO
This component requires an Access Token for authentication, as detailed in the Getting Started section.

Inputs

FieldTypeRequiredNotes
ticket_idstringYesThe unique identifier for the ticket you want to fetch.

Outputs

FieldTypeDescription
idstringThe ticket's unique identifier.
contentstringThe detailed description of the ticket.
subjectstringThe subject line of the ticket.
pipelinestringThe pipeline the ticket belongs to.
pipelineStagestringThe stage of the ticket within the pipeline.
ticketPrioritystringThe priority level assigned to the ticket.
ResponseobjectThe raw JSON response from the API.
Use Case

When a customer replies to a support email, an agent uses the ticket ID to fetch the full context with this component before drafting a response.

Import File

Uploads a file to the HubSpot File Manager.

INFO
This component requires an Access Token for authentication, as detailed in the Getting Started section.

Component-Specific Settings

  • Access: Define the file's privacy: PUBLIC_INDEXABLE, PUBLIC_NOT_INDEXABLE, PRIVATE, etc.

Inputs

FieldTypeRequiredNotes
file_urlstringYesA public URL where the file is currently hosted.
folderPathstringYesThe path within the HubSpot File Manager to store the file (e.g., /contracts).
namestringYesThe name to assign to the file in HubSpot.

Outputs

FieldTypeDescription
idstringThe unique identifier of the uploaded file in HubSpot.
ResponseobjectThe raw JSON response from the API.
Use Case

After a contract is signed via an e-signature platform, an agent takes the URL of the signed PDF and uses this component to upload and attach it to the corresponding contact's record in HubSpot.

Public URL Required

The file_url must be publicly accessible for HubSpot's servers to be able to download it.

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 corresponding Next ... Page component, passing the pagingNextAfter 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.
  • 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 or Search component to verify that the resource you are trying to access exists.

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 a Deal, and then assigns a Task 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.
  • 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.