HubSpot | Smallest AI Docs

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.

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.

Integrations overview

Connecting, pinning fields and disconnecting

Salesforce

Leads, accounts and opportunities