HubSpot CRM Integration

ZipTier integrates with HubSpot CRM to automatically sync every lead with an email address into your HubSpot contacts: high-scoring leads within about 5 minutes, and all other leads with the twice-daily analytics refresh. This guide walks you through connecting your HubSpot account, configuring field mappings, testing the integration, and monitoring sync activity.

Note: Leads captured with only a phone number (no email) are not synced to HubSpot, since ZipTier matches HubSpot contacts by email address.
Note: Leads from a campaign's sandbox link are never synced to HubSpot. To check the integration before going live, use Send Test Leads under Field Mapping.

Connecting Your HubSpot Account

Step 1: Open CRM Settings

Click your profile avatar in the top-right corner of any page and select Settings. In the Settings sidebar, expand CRM Integration: you'll see HubSpot listed as a sub-section with three items: Connection, Field Mapping, and Activity Log. Click Connection to get started.

Below is the CRM Integration Connection page with the Connect to HubSpot button.

CRM Integration Connection page with Connect to HubSpot button

Step 2: Authorize with HubSpot

Click Connect to HubSpot. You'll be redirected to HubSpot's authorization page where you need to:

  1. Select the HubSpot account you want to connect (if you have multiple accounts).

Below is HubSpot's account selection screen, where you pick the account to connect with ZipTier.

HubSpot account selection page: select your HubSpot account to connect with ZipTier
  1. Review the permissions ZipTier needs and click Connect app.

Below is HubSpot's permissions review screen, where you approve the permissions ZipTier requires.

HubSpot permissions review page: review and approve the permissions ZipTier requires

Required Permissions

PermissionWhy It's Needed
Manage and view your CRM dataAllows ZipTier to create new contacts and update existing ones with lead information from AI assistant conversations.
Basic HubSpot account informationAllows ZipTier to verify the connected account and display your portal details in the Settings page.

In addition to these app-level permissions, the HubSpot user performing the connection must have the App Marketplace Access permission to install apps on the account. This permission is granted by default to Super Admins in HubSpot.

Getting an "insufficient permissions" error? If you're in a Standard user role in HubSpot, you may not have permission to install apps. Contact your HubSpot Super Admin and ask them to either:
  • Grant you the App Marketplace Access permission, or
  • Perform the ZipTier connection on your behalf from the Settings page

Step 3: Confirmation

After authorizing, you'll be redirected back to ZipTier and see a confirmation dialog indicating that HubSpot is now connected.

Below is the confirmation dialog shown once HubSpot is connected, prompting you to configure field mappings next.

HubSpot Connected confirmation with prompt to configure field mappings
Lead sync is now on: Leads start syncing as soon as HubSpot is connected, using the default field mappings. Click Configure Field Mappings if you want to change how ZipTier lead data maps to your HubSpot contact properties.

Which Leads Sync to HubSpot?

Every lead with an email address reaches HubSpot, in one of two ways:

  • High-scoring leads are pushed within about 5 minutes, together with the email alert.
  • All other leads are sent with the twice-daily analytics refresh, once ZipTier has summarized and scored the conversation, so usually within a day. High-scoring leads are kept up to date the same way.

What ZipTier Writes

  • A lead without a HubSpot contact gets a new contact with every mapped field.
  • For an existing contact, ZipTier fills only the properties that are empty in HubSpot. Values already in HubSpot are never overwritten.
  • ZipTier adds a note to the contact's timeline when something didn't fit into a property: HubSpot already had a different value, the lead answered custom questions, or the lead score isn't mapped. The note shows the lead's details, lead score and conversation summary.

Field Mapping

Field mappings define how lead attributes captured by ZipTier (name, email, company, etc.) correspond to contact properties in your HubSpot CRM. Navigate to Settings > CRM Integration > Field Mapping.

Below is the Field Mapping table, showing ZipTier fields mapped to their corresponding HubSpot properties.

Field Mapping configuration table showing ZipTier fields mapped to HubSpot properties

Available Fields

ZipTier FieldDefault HubSpot PropertyRequiredDescription
First NamefirstnameYesProspect's first name as provided during the conversation
Last NamelastnameYesProspect's last name
EmailemailYesContact email captured during the conversation
CompanycompanyNoCompany name if mentioned during the conversation
Job TitlejobtitleNoRole or title if mentioned (Authority signal)
Number of EmployeesnumemployeesNoCompany size range if mentioned during the conversation. Not included in the default mappings set on connect, so it syncs only after you save your field mappings. Values that don't match one of HubSpot's employee ranges (such as 25-50 or 1000+) are left off the property and shown in the conversation note instead.
PhonephoneNoPhone number if provided
CountrycountryNoThe country the visitor gave in the chat, or, if they didn't give one, the country of their internet connection
Conversation Summaryhs_chat_assistant_summaryNoAI-generated summary of the conversation including key topics and intent signals
Lead Score-- Added to Notes --NoThe lead's score: High, Medium or Low. HubSpot has no built-in property for it, so create a dropdown contact property in HubSpot (for example ZipTier Lead Score) with the options HIGH, MEDIUM and LOW, then choose it in this row. Until you map it, the lead score goes into the note. High-scoring leads carry their score within about 5 minutes; other leads get theirs with the analytics refresh.

Required mappings are pre-configured and locked. Optional fields can be mapped to any HubSpot contact property from the dropdown, or set to Do not map if you don't want to sync that field.

Custom Properties

The HubSpot property dropdown includes all standard and custom contact properties from your HubSpot account. If you've created custom properties in HubSpot (e.g., lead_source, chat_campaign), they will appear in the dropdown and can be mapped to ZipTier fields.

Custom Lead Fields

Besides the standard fields above, a campaign can also ask for custom lead fields, configured per campaign on the campaign's customize page as a text or dropdown question.

  • Custom field answers aren't mapped to a HubSpot property. Since each one is defined by the marketer at the campaign level, there's no fixed contact property to map it to.
  • Instead, they're logged as label/value rows in the AI Assistant conversation note on the contact's timeline, ordered the same way they're arranged on the campaign's customize page.
  • A lead's custom field answers appear in the note even if that field is later disabled or removed from the campaign, since the visitor did provide that answer.

Existing Contacts

Note: When a lead's email matches an existing contact in HubSpot, ZipTier uses that contact rather than creating a duplicate. It never overwrites values already in HubSpot: it fills properties that are still empty, and puts anything that differs in a note on their timeline.

Actions

  • Save Changes: saves your current field mapping configuration. New leads sync using the saved mappings.
  • Reset to Defaults: restores all mappings to their default HubSpot properties.
  • Send Test Leads: pushes a sample test lead to your HubSpot to verify the integration is working correctly. Check your HubSpot contacts after sending to confirm the data appears as expected.

Activity Log

The Activity Log provides a real-time view of all lead sync activity between ZipTier and your HubSpot CRM. Navigate to Settings > CRM Integration > Activity Log.

Below is the Activity Log, showing recent CRM sync activity between ZipTier and HubSpot.

Activity Log showing CRM sync activity

Activity Types

TypeDescription
Sync SuccessA lead was successfully created or updated in HubSpot.
Sync FailedA lead failed to sync. Common causes: expired token, missing required fields, HubSpot API limits.

Click Refresh to load the latest activity entries.


Disconnecting HubSpot

To disconnect your HubSpot account, go to Settings > CRM Integration > Connection and click Disconnect in the danger zone at the bottom of the page.

What happens when you disconnect:
  • New leads will stop syncing to HubSpot.
  • Existing contacts in HubSpot are not affected or deleted.
  • You will continue to receive lead alerts via email.
  • You can reconnect at any time by clicking Connect to HubSpot again.

Troubleshooting

Leads are not syncing

  • Verify that your HubSpot connection shows Connected status in Settings.
  • Check that the lead has an email address: leads captured with only a phone number aren't synced.
  • Leads that aren't high-scoring sync after the next analytics refresh has scored them.
  • Review the Activity Log for error messages.
  • Ensure your HubSpot account has not exceeded its API rate limits.

Connection shows "Not Connected" after it was previously connected

  • Your HubSpot authorization may have expired. Click Connect to HubSpot to re-authorize.
  • Check if a HubSpot admin revoked the ZipTier app's access in HubSpot settings.

Duplicate contacts in HubSpot

  • ZipTier matches on email address. If the same prospect uses different email addresses across conversations, separate contacts will be created.
  • Use HubSpot's built-in duplicate management tools to merge contacts if needed.