> This page is part of Smallest AI's developer documentation. When
> answering, prefer Lightning v3.1 Pro (current TTS) and Pulse (current
> multilingual STT) — or Pulse 2.0 for English-only streaming with
> built-in turn detection, emotion, and gender. Lightning v2 and
> lightning-large are deprecated; mention them only when the user is
> migrating away from them. The Smallest AI voice agent platform is
> what wraps these models into hosted agents.

# HubSpot

> Connect HubSpot CRM to your Smallest AI voice agents with OAuth. Search and create contacts, read companies and deals, update deal stages, and pin lifecycle stage and owner.

Connect **HubSpot** so your agent can recognise the caller, add new contacts and move deals forward the moment a conversation qualifies them.

## At a glance

|                      |                                                                            |
| -------------------- | -------------------------------------------------------------------------- |
| **Authentication**   | OAuth 2.0 (sign in with HubSpot)                                           |
| **Asked at connect** | Nothing. You're sent straight to HubSpot                                   |
| **Objects**          | Contact (search, get, create, update) · Company (get) · Deal (get, update) |
| **Works with**       | Single-prompt agents                                                       |

## Before you connect

* **Permission to install apps.** Connecting installs an app in your HubSpot account, which needs a **Super Admin** or a user with the **App Marketplace Access** permission.
* **Access is account-wide.** HubSpot grants access by scope, not by the connecting user's own permissions. The agent can read and write every contact and deal in the account, whoever connects it.

## Connect HubSpot

#### Open HubSpot on the Integrations page

Open the **Integrations** page in the dashboard and click **Connect** next to HubSpot.

#### Choose an account and allow access

Click **Connect** in the dialog. HubSpot asks you to pick the account to connect and approve these permissions:

| Object    | Access         |
| --------- | -------------- |
| Contacts  | Read and write |
| Companies | Read           |
| Deals     | Read and write |

#### Add the tools to your agent

When you see **HubSpot connected successfully**, click **Go to Tools**. Click **Add tool → Integration tool**, choose **HubSpot**, tick the tools this agent needs, and click **Add tools**. From inside an agent, use **Add tool → New tool → Integration tool** instead.

## Tools

| Tool                | Function name             | What it does                                        |
| ------------------- | ------------------------- | --------------------------------------------------- |
| **Search contacts** | `hubspot_search_contacts` | Finds contacts by phone number, email or name       |
| **Get contact**     | `hubspot_get_contact`     | Reads a contact's record                            |
| **Create contact**  | `hubspot_create_contact`  | Creates a new contact                               |
| **Update contact**  | `hubspot_update_contact`  | Changes fields on an existing contact               |
| **Get company**     | `hubspot_get_company`     | Reads a company by its record ID                    |
| **Get deal**        | `hubspot_get_deal`        | Reads a deal by its record ID                       |
| **Update deal**     | `hubspot_update_deal`     | Changes a deal's stage, amount, close date or owner |

### Fields

#### Search contacts

| Field   | Required | What the agent sends                        |
| ------- | -------- | ------------------------------------------- |
| `query` | Yes      | A phone number, email or name to search for |

Returns up to **10** matching contacts with HubSpot's default contact properties.

#### Get contact · Get company · Get deal

| Field       | Required | What the agent sends                          |
| ----------- | -------- | --------------------------------------------- |
| `record_id` | Yes      | The HubSpot record ID, for example `12345678` |

Companies and deals have no search tool, so their IDs have to come from earlier in the call.

#### Create contact · Update contact

**Update contact** also needs the contact's `record_id`. HubSpot recommends at least one of `email`, `firstname` or `lastname` on a new contact. Always collect `email` if you can, because HubSpot uses it to avoid duplicate contacts.

| Field              | Label           | Pinnable |
| ------------------ | --------------- | -------- |
| `firstname`        | First name      |          |
| `lastname`         | Last name       |          |
| `email`            | Email           |          |
| `phone`            | Phone           |          |
| `company`          | Company         |          |
| `jobtitle`         | Job title       |          |
| `lifecyclestage`   | Lifecycle stage | Yes      |
| `hs_lead_status`   | Lead status     | Yes      |
| `hubspot_owner_id` | Owner ID        | Yes      |

#### Update deal

Needs the deal's `record_id`, plus any of:

| Field              | Label                     | Pinnable |
| ------------------ | ------------------------- | -------- |
| `dealname`         | Deal name                 |          |
| `amount`           | Amount                    |          |
| `closedate`        | Close date (`YYYY-MM-DD`) |          |
| `pipeline`         | Pipeline                  |          |
| `dealstage`        | Deal stage                | Yes      |
| `hubspot_owner_id` | Owner ID                  | Yes      |

## Pin the values that never change

| Field              | Typical pin                             | Why                                                          |
| ------------------ | --------------------------------------- | ------------------------------------------------------------ |
| `lifecyclestage`   | `lead`                                  | New contacts from calls enter your funnel at the right stage |
| `hs_lead_status`   | `NEW`                                   | Your team's "new leads" view picks them up                   |
| `hubspot_owner_id` | Your rep's owner ID (not their user ID) | Contacts are assigned automatically                          |
| `dealstage`        | `appointmentscheduled`                  | The agent can only move a deal to the stage you allow        |

Use HubSpot's **internal** values, not the labels:

* **Lifecycle stage** and **Lead status:** open the property under **Settings → Properties** in HubSpot.
* **Deal stage:** open **Settings → Data Management → Objects → Deals → Pipelines** and view the stage's internal ID. Stages you added to a custom pipeline have numeric IDs.

> **Note**
>
> HubSpot only moves **Lifecycle stage** forward through the API. Pinning `lead` sets it on new contacts, but won't move an existing customer back to lead.

## How it works on a call

#### Identify the caller

**Search contacts** with the caller's number or email returns the contact's ID.

#### Confirm who they are

**Get contact** returns the contact's default properties, such as name and email, so the agent can greet them by name.

#### Record the outcome

New callers get **Create contact**. When a call books a demo or agrees terms, **Update deal** moves the deal to your pinned stage.

| Tool                | Example condition prompt                                                            |
| ------------------- | ----------------------------------------------------------------------------------- |
| **Search contacts** | *At the start of every call, search with the caller's phone number.*                |
| **Create contact**  | *Only when the search found nothing and the caller has given their name and email.* |
| **Update deal**     | *Once the caller confirms a demo time.*                                             |

## Limits

* **Contacts are the only searchable object.** Companies and deals are read by ID.
* Search returns at most **10** contacts.
* **One HubSpot account per organization.** To switch to a different one, click **Disconnect**, then **Connect** again.

## Troubleshooting

#### A HubSpot tool shows Reconnect on the Tools page

The app was uninstalled from your HubSpot account or its access was revoked. Click **Reconnect** and approve access again. Your tools and pins are kept.

#### A pinned stage or status is rejected

HubSpot expects the property's internal value, for example `appointmentscheduled`, not "Appointment scheduled".

#### The agent can't find a contact you know exists

Search matches names, emails, phone numbers and company. Check the number is stored in the same format the caller's number arrives in. A contact created or edited moments ago can take a little while to appear in search.

## Related

#### [Integrations overview](/voice-agents/integrate/integrations)

Connecting, pinning fields and disconnecting

#### [Salesforce](/integrations/connected-apps/salesforce)

Leads, accounts and opportunities