> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcargo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# HubSpot

> This page outlines how to use the HubSpot integration to pull and manage CRM data in Cargo.

HubSpot is an all-in-one CRM platform that helps businesses manage marketing, sales, and customer service. Cargo's native integration with HubSpot allows you to both pull data from the CRM as part of data models, and write or delete data from all CRM objects to maintain it.

## How to set up HubSpot

Cargo supports two authentication methods for HubSpot:

1. **OAuth 2** – The default method. During connection, you'll be redirected to HubSpot to authorize Cargo.
2. **Private App** – Use a HubSpot Private App access token for more granular permission control.

Once the connector is created, you can:

* **Set up a HubSpot data model** — Create data models from your HubSpot objects to trigger Plays and power model search actions.
* **Use HubSpot in workflows** — Choose **HubSpot** from the node catalog within a **Play**, **Tool**, or **Agent**.

***

## HubSpot actions

<Tip>
  All HubSpot actions support Contacts, Companies, Deals, Tickets, and any
  custom objects you've created in your HubSpot account.
</Tip>

### Insert record

Insert a new record into HubSpot.

**Use cases**

* **Lead capture** – Create new contacts from various sources and channels
* **Company creation** – Add new companies from forms, events, or imports
* **Deal creation** – Create new deals to track opportunities through your pipeline

### Match records

Check if records exist in HubSpot based on matching criteria.

**Use cases**

* **Duplicate prevention** – Avoid creating duplicate records
* **Smart routing** – Route records based on existing data

<Info>
  Use **Match records** before **Insert record** to implement an upsert pattern
  for single records.
</Info>

### Find records

Find records matching the given criteria. Define multiple matching criteria—the action searches for records that match any of the provided values. Empty values are automatically skipped.

**Use cases**

* **Multi-identifier matching** – Search by domain, LinkedIn URL, or company name
* **Flexible lookups** – Find records using whichever identifiers are available
* **Data quality handling** – Provide multiple identifiers to maximize match rates

**Example configuration**

| Property                | Value                            |
| ----------------------- | -------------------------------- |
| `domain`                | `{{nodes.start.company_domain}}` |
| `linkedin_company_page` | `{{nodes.start.linkedin_url}}`   |
| `name`                  | `{{nodes.start.company_name}}`   |

<Tip>
  Empty values are automatically skipped, so you can provide all available
  identifiers without worrying about null checks.
</Tip>

### Search records

Retrieve multiple records from HubSpot based on search criteria.

**Use cases**

* **Advanced filtering** – Find records meeting specific criteria
* **Bulk operations** – Retrieve multiple records for processing inside a group node

### Update records

Update existing records in HubSpot.

**Use cases**

* **Data enrichment** – Keep record information current and accurate
* **Lifecycle management** – Update record stages, deal stages, and statuses
* **Lead scoring** – Update contact scores based on engagement signals

### Upsert records

Upsert multiple records into HubSpot (insert or update based on matching criteria).

**Use cases**

* **Bulk data operations** – Insert records in bulk while avoiding duplicates
* **Data synchronization** – Keep external systems synchronized with HubSpot

<Warning>
  Upsert operations will match on the fields you specify. Ensure your matching
  criteria is unique to avoid unintended updates.
</Warning>

### Merge records

Merge two records of the same object type into one.

**Use cases**

* **Deduplication** – Combine duplicate records into a single master record
* **Data consolidation** – Merge records when companies or contacts are identified as the same

### Delete records

Delete records from HubSpot.

**Use cases**

* **Data cleanup** – Remove outdated or incorrect records programmatically or in batches

### Count records

Count records matching specific criteria.

**Use cases**

* **Reporting** – Get counts for dashboards and metrics
* **Conditional logic** – Make workflow decisions based on record counts

### Add to list

Add a contact to a HubSpot list.

**Use cases**

* **Segmentation** – Add contacts to marketing lists based on workflow criteria
* **Campaign targeting** – Build audiences for email campaigns

### Delete from list

Remove a contact from a HubSpot list.

**Use cases**

* **List hygiene** – Remove contacts who no longer meet list criteria
* **Unsubscribe handling** – Remove contacts from specific campaign lists

### Create association

Create an association between two records in HubSpot.

**Use cases**

* **Relationship mapping** – Link contacts to companies or deals
* **Account hierarchies** – Connect parent and child companies

### Delete association

Remove an association between two records in HubSpot.

**Use cases**

* **Relationship cleanup** – Remove incorrect associations
* **Data restructuring** – Update record relationships

### Enroll to sequence

Enroll a contact in a HubSpot sequence.

**Use cases**

* **Sales outreach** – Automatically enroll leads in nurture sequences
* **Follow-up automation** – Trigger sequences based on workflow conditions

### Submit form

Submit data to a HubSpot form.

**Use cases**

* **Lead capture** – Submit form data from external sources
* **Data collection** – Capture information while respecting HubSpot form settings and workflows

### Unsubscribe contact

Unsubscribe a contact from all email subscriptions.

**Use cases**

* **GDPR compliance** – Honor unsubscribe requests
* **Preference management** – Respect contact communication preferences

***

## HubSpot data models

Cargo allows you to create data models on top of your HubSpot CRM data that can be used to trigger Plays and power model search actions.

### Creating HubSpot data models

| Field           | Description                                                                                               |
| --------------- | --------------------------------------------------------------------------------------------------------- |
| **Name**        | Choose a descriptive name for your data model (required)                                                  |
| **Slug**        | Set a unique identifier that cannot be changed once created (required)                                    |
| **Object Type** | Select the HubSpot object type you want to model (Contacts, Companies, Deals, Tickets, or custom objects) |

### Object types available

<AccordionGroup>
  <Accordion title="Contact models" icon="user">
    **Use cases** - Handle lead and contact information - Track individual
    engagement and communication history - Manage contact lifecycle stages and
    lead scoring
  </Accordion>

  <Accordion title="Company models" icon="building">
    **Use cases** - Manage company records with domains, industry, and size
    information - Track company relationships and hierarchies - Monitor account
    engagement and lifecycle stages
  </Accordion>

  <Accordion title="Deal models" icon="handshake">
    **Use cases** - Track opportunities, pipeline stages, and deal progression -
    Monitor deal velocity, conversion rates, and forecasting - Analyze win/loss
    patterns and sales performance
  </Accordion>

  <Accordion title="Ticket models" icon="ticket">
    **Use cases** - Track customer support requests and issues - Monitor ticket
    resolution times and SLA compliance - Analyze support patterns and team
    performance
  </Accordion>
</AccordionGroup>

<Tip>
  You can also model any **custom objects** you've created in HubSpot, giving
  you full flexibility to work with your unique data structures.
</Tip>