Connecting Voice Agents to HubSpot CRM

HubSpot is the CRM of choice for a large share of SMB and mid-market SaaS companies, and increasingly for mid-market customers in other verticals. Its API is cleaner than Salesforce's, its data model is simpler, and integrations are generally less painful. For voice AI deployments targeting HubSpot-using teams, the integration is a foundational piece — voice agents need to read deal context, contact history, and workflow state, and they need to write call logs, create deals, update properties, and route to the right owner. This piece walks through the HubSpot-specific patterns.

TL;DR

• HubSpot's REST API is well-documented and easier to integrate against than Salesforce.
• OAuth 2.0 or Private App auth; pick based on deployment model.
• Core objects: Contact, Company, Deal, Ticket, plus Engagements for call logs.
• Rate limits are reasonable but real; plan for them at scale.
• HubSpot's Marketplace and native integrations may already cover some use cases — check before building.

What you'll integrate with

HubSpot's data model:

• Contact. Individual person.
• Company. Organization (linked to Contacts).
• Deal. Sales opportunity (linked to Contacts and Companies).
• Ticket. Support case (linked to Contacts/Companies).
• Engagements. Calls, emails, meetings, notes — logged against records.
• Custom objects. For non-standard data.

Voice agents typically:

• Read Contact + Company + Deal for context.
• Write Engagements (calls) with transcripts.
• Create or update Deals based on call outcomes.
• Create Tickets from support calls.
• Update Contact/Company properties with captured info.

Authentication

Private App. Simplest for server-to-server. Create a Private App in HubSpot Settings, generate an API token, use it for Bearer auth.

OAuth 2.0. For multi-tenant apps where each customer has their own HubSpot. Required for Marketplace apps.

Developer API Keys. Deprecated. Don't use for new integrations.

For most voice AI deployments, Private App auth is the cleanest path.

The REST API basics

Base URL: https://api.hubapi.com/

Key endpoints:

• GET /crm/v3/objects/contacts/{id} — read a contact.
• POST /crm/v3/objects/contacts — create a contact.
• PATCH /crm/v3/objects/contacts/{id} — update a contact.
• POST /crm/v3/objects/contacts/search — search contacts.
• POST /crm/v3/objects/calls — create a call engagement.
• POST /crm/v3/objects/deals — create a deal.

The v3 API is current and well-structured.

Lookup by phone number

POST /crm/v3/objects/contacts/search
{
  "filterGroups": [{
    "filters": [
      {"propertyName": "phone", "operator": "EQ", "value": "+15551234567"},
      {"propertyName": "mobilephone", "operator": "EQ", "value": "+15551234567"}
    ]
  }],
  "properties": ["firstname", "lastname", "email", "hs_object_id", "lifecyclestage"],
  "limit": 1
}

Use OR logic by structuring filter groups separately if needed. Normalize phone to E.164 first.

Logging calls as engagements

HubSpot calls are first-class engagements:

POST /crm/v3/objects/calls
{
  "properties": {
    "hs_timestamp": "2026-04-16T14:23:00Z",
    "hs_call_body": "Call summary and transcript",
    "hs_call_direction": "INBOUND",
    "hs_call_duration": "243000",
    "hs_call_from_number": "+15551234567",
    "hs_call_to_number": "+15551112222",
    "hs_call_status": "COMPLETED",
    "hs_call_recording_url": "https://..."
  },
  "associations": [
    {
      "to": {"id": "{ContactId}"},
      "types": [{"associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 194}]
    }
  ]
}

Contact ID 194 is the standard "Call to Contact" association. Other association types for Deal, Ticket, Company.

Creating deals from qualified calls

POST /crm/v3/objects/deals
{
  "properties": {
    "dealname": "Inbound qualified call - {CompanyName}",
    "pipeline": "default",
    "dealstage": "qualifiedtobuy",
    "amount": "25000",
    "closedate": "2026-05-30"
  },
  "associations": [
    {"to": {"id": "{ContactId}"}, "types": [...]}
  ]
}

Deal stage depends on your pipeline. Confirm with the HubSpot admin.

Creating tickets from support calls

POST /crm/v3/objects/tickets
{
  "properties": {
    "subject": "Inbound support call",
    "content": "{Call summary}",
    "hs_pipeline": "0",
    "hs_pipeline_stage": "1",
    "hs_ticket_priority": "MEDIUM",
    "source_type": "PHONE"
  },
  "associations": [...]
}

Custom properties

HubSpot orgs usually have custom properties. Discover them:

GET /crm/v3/properties/contacts

Populate them when creating/updating. Mapping voice agent outputs to custom properties is often the admin's preferred approach.

Workflows and automations

HubSpot Workflows can trigger on Contact/Deal/Ticket changes. Voice agent writes can activate workflows:

• New qualified call creates a Contact → Workflow sends welcome email.
• Deal moves to a stage → Workflow alerts the sales rep.
• Ticket created → Workflow routes to a team.

Coordinate with the admin on what triggers exist so your writes don't cause unexpected automations.

Rate limits

HubSpot rate limits (2026):

• Standard: 100 requests/10 seconds per app.
• Higher tiers (Enterprise, Marketplace): higher limits.
• Burst: 150 requests/10 seconds peak.

Implement retry with backoff on 429 responses.

For very high-volume, batch operations via /crm/v3/objects/{object}/batch/create.

Engagements vs Activities

HubSpot's engagement model is cleaner than Salesforce's activity model:

• Calls are distinct objects with call-specific properties.
• Emails, Meetings, Notes, Tasks each have their own object.
• No unified "Activity" object.

Model voice calls as Call engagements.

Meeting creation

For agents that book meetings:

POST /crm/v3/objects/meetings
{
  "properties": {
    "hs_timestamp": "...",
    "hs_meeting_title": "Demo call",
    "hs_meeting_start_time": "2026-04-20T14:00:00Z",
    "hs_meeting_end_time": "2026-04-20T14:30:00Z",
    "hs_meeting_outcome": "SCHEDULED"
  },
  "associations": [...]
}

For calendar integration (Cal.com, Google, Outlook), see calendar integrations: Cal.com, Google, Outlook.

Webhooks

HubSpot can send webhooks on object changes:

• New Contact created.
• Deal stage changed.
• Property updated.
• Ticket created.

Useful for triggering outbound voice agent calls in response to CRM events (e.g., new inbound lead → trigger outbound qualification call).

HubSpot Marketplace

Check the Marketplace before building. Many voice AI integrations already exist:

• Generic CRM sync tools.
• Specific voice AI vendor integrations.
• Calling / phone integrations.

If a Marketplace app covers your use case, using it is often faster than custom building.

Common pitfalls

Timestamp format. HubSpot expects ISO 8601 with milliseconds for call timestamps: 2026-04-16T14:23:00.000Z.

Phone number formatting. HubSpot stores phone numbers in the format the user entered. Search with multiple formats (E.164, national, with/without formatting) for robustness.

Duplicate contacts. HubSpot has deduplication rules but they're not foolproof. Test with edge cases.

Property update permissions. Some properties are computed by HubSpot (lifecycle stage, scoring) and shouldn't be directly written.

Pipeline stage IDs. Hardcoded stage IDs break when admins rename stages. Look up by name when possible.

Testing

• HubSpot Developer Account — free sandbox.
• Test portal before deploying to customer portals.
• Integration user with limited scopes.
• Error scenario tests — rate limits, validation, missing contacts.

Related reading

• Connecting Voice Agents to Salesforce CRM
• Twilio + Voice Agents: A Complete Guide
• Connecting Voice Lead Qual to HubSpot
• How to Integrate Voice Agents with a Custom REST API
• Sending Voice Agent Transcripts to Slack

FAQ

Can we sync voice agent transcripts to HubSpot? Yes — store in call engagement's body or a custom property. Watch for character limits on properties.

What about HubSpot Service Hub specifically? Ticket-centric. Voice agents create/update Tickets and log against them.

Can we trigger HubSpot sequences from voice agents? Yes — via the API or via Workflow triggers responding to voice-agent writes.

What about outbound calling from HubSpot? HubSpot's calling feature is mainly for human reps. Outbound AI calling typically runs independently.

How do we handle multi-portal customers? Per-portal integration with separate auth. Private Apps are per-portal.