---
title: "HubSpot"
description: "Connect HubSpot, obtain the required access and configure permitted actions."
url: "https://documentation.verbatik.com/integrations/hubspot/"
---

# HubSpot

Connect HubSpot, obtain the required access and configure permitted actions.

The API adapter is implemented. Validate your own account and authorized actions before routing production calls.

## Before you start

Connect the account belonging to this business and workspace. Vendor subscriptions, API limits and role permissions still apply.

**API:** HubSpot CRM APIs (objects, properties, pipelines and activities)

**Authentication:** Service Key (recommended for one account); existing private-app token; or the existing Verbatik HubSpot OAuth connection

## Get access and connect

1. Sign in to the customer's HubSpot account at https://app.hubspot.com/ with Developer Tools access and permission to the CRM objects involved.
2. For a new token integration, open Settings → Integrations → Service Keys, or Development → Keys → Service Keys. Create a dedicated Verbatik key and grant only the required object scopes.
3. Copy the Service Key into the HubSpot integration's access-token credential in Verbatik. No API-origin setting is required. Service Keys and existing private-app tokens use the same Bearer authentication.
4. Alternatively, use the existing HubSpot OAuth connector and link that account to the native app so its access token is renewed by the connector. If granting more scopes than the original connection, reconnect and consent again.
5. Run Test connection, which reads contact property metadata. Select native actions for the agent, or configure a post-call automation to write a call outcome, task, note or deal update.
6. Use pipeline IDs and stage values returned from List deal pipelines. Property-based workflow triggers must be configured inside HubSpot; Verbatik updates records and does not invent or automatically enroll an arbitrary HubSpot workflow.

## Account requirements

- The scopes must be available to the creating user and the customer's HubSpot subscription. Choose only those needed by enabled actions; activity writes require the permissions documented for their related CRM objects.
- New legacy private-app creation was removed for new accounts on September 28, 2026 and existing accounts on October 26, 2026. Existing private-app tokens still work; new customers should create Service Keys or authorize an OAuth app.
- Service Keys do not provide webhooks. Cross-account OAuth distribution requires a registered HubSpot app and the appropriate HubSpot installation/distribution limits.
- The native adapter currently uses documented v3 CRM object endpoints. Tenant-required properties and validation rules still apply; future API/scope migrations must follow HubSpot's deprecation schedule.

## Permissions

- `crm.schemas.contacts.read`
- `crm.objects.contacts.read`
- `crm.objects.contacts.write`
- `crm.objects.companies.read`
- `crm.objects.companies.write`
- `crm.objects.deals.read`
- `crm.objects.deals.write`

Grant the subset needed for the actions you enable. API scopes do not override the connected user’s record permissions or vendor validation rules.

## Connection fields

- `accessToken` — HubSpot Service Key, existing private-app token or OAuth token (required). Secret fields are saved as workspace credentials.

## Available actions

- `test_connection` — **Read** · available for after-call automation. Read account or schema metadata to verify credentials without creating records.
- `find_contact` — **Read** · available for after-call automation. Find contacts by an exact email address.
- `get_record` — **Read** · available for after-call automation. Read a contact, company, deal, task, note or call by its known ID.
- `create_contact` — **Write** · available for after-call automation. Create a HubSpot contact. Use find contact first to avoid duplicates.
- `create_record` — **Write** · available for after-call automation. Create a contact, company, deal, task, note or call using documented HubSpot property names. Supply tenant-required fields and configured pipeline/stage IDs.
- `update_record` — **Write** · available for after-call automation. Update only the supplied HubSpot CRM properties. Property changes can trigger workflows configured in HubSpot.
- `list_pipelines` — **Read** · available for after-call automation. Read deal pipeline and stage IDs before assigning or moving a deal.
- `add_note` — **Write** · available for after-call automation. Create a note associated with a known contact, company or deal. Association type IDs are HubSpot-defined for that object pair.
- `create_task` — **Write** · available for after-call automation. Create a follow-up task with a due date.
- `log_call` — **Write** · available for after-call automation. Record a completed CRM call activity. Duration is milliseconds. Does not place a phone call.


## Verify before going live

Run Test connection and one read action against a known permitted record. Then test each intended write in an authorized sandbox. Check the provider’s own record and the Verbatik receipt. Publish the agent after assigning its tools. If a write has an unknown outcome, reconcile it with the vendor before trying again.

## Vendor documentation

- [Setup and API documentation](https://developers.hubspot.com/changelog/service-keys)
- [Additional provider reference](https://developers.hubspot.com/changelog/legacy-private-app-creation-sunset)
- [Additional provider reference](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/guide)
- [Additional provider reference](https://developers.hubspot.com/docs/api-reference/crm-properties-v3/guide)
- [Additional provider reference](https://developers.hubspot.com/docs/api-reference/legacy/crm/activities/calls/guide)
- [Additional provider reference](https://developers.hubspot.com/docs/api-reference/legacy/crm/activities/notes/guide)