HubSpot Integration Guide

Article Overview

Artisan seamlessly integrates with HubSpot to export your enriched leads as contacts. This guide explains how our HubSpot integration works, what data we sync, and the advanced features available to customize your workflow.

Getting Started

To connect your HubSpot account with Artisan:

1. Navigate to Settings → Integrations → HubSpot

2. Click Connect HubSpot

3. Authorize Artisan to access your HubSpot account

4. Configure your export preferences

Once connected, Artisan can automatically export leads as HubSpot contacts based on your preferences.

Contact Field Mapping

When Artisan exports a lead to HubSpot, we populate the following standard contact properties:

Contact Owner Assignment

When leads are exported, Artisan automatically assigns the HubSpot Owner (hubspot_owner_id) to the user who connected the HubSpot integration. This ensures proper lead routing and accountability in your CRM.

Lead Status & Sentiment Mapping

Artisan automatically sets the HubSpot lead status based on engagement and sentiment analysis.

Default Status Mapping

Custom Status Mapping

You can customize how Artisan maps lead statuses to match your HubSpot workflow. For example:

{ "not_engaged": "Cold Lead", "engaged": "Warm Lead", "3": "Hot Lead", "2": "Qualified", "1": "Not Interested"}

Sentiment values:

• 3 = Positive sentiment

• 2 = Neutral sentiment

• 1 = Negative sentiment

This allows you to automatically categorize leads based on their reply sentiment, enabling more granular lead qualification in HubSpot.

Advanced Features

Custom Field Name Mapping

If your HubSpot instance uses custom property names, you can map Artisan fields to your specific HubSpot properties.

Example Configuration:

{ "company": "account_name__c", "website": "company_website__c", "hs_lead_status": "custom_lead_status"}

This maps:

• Artisan’s company field → your custom account_name__c property

• Artisan’s website field → your custom company_website__c property

• Lead status → your custom custom_lead_status property

Tip: You can combine field name mapping with sentiment-based status mapping for maximum flexibility.

Overwrite Existing Contacts

By default, Artisan does NOT overwrite existing contacts in HubSpot.

If a contact with the same email already exists, we simply link it to your Artisan lead without modifying any data.

If you need Artisan to update specific fields on existing contacts, you must explicitly configure which fields to overwrite.

How to Enable Overwriting:

{ "overwrite_fields": [ "firstname", "lastname", "company", "jobtitle", "hs_lead_status"]}

Behavior:

• New contacts: All standard fields are populated normally

• Existing contacts: Only the fields listed in overwrite_fields are updated; all other fields remain unchanged

Available Fields for Overwrite:

• firstname, lastname, email

• jobtitle, company, website, industry

• Any custom HubSpot properties (use the internal property name)

Read-Only Fields (Cannot Be Overwritten):

• hs_object_source_detail_1 (HubSpot managed)

• hs_object_source_detail_2 (only set during contact creation)

Custom Attribution Property

Track which leads came from or were updated by Artisan using a custom attribution property.

Setup Steps:

1. Create a custom property in HubSpot:
    - Go to HubSpot Settings → Properties → Contact Properties
    - Create a new property (e.g., “Data Source” with internal name data_source)

2. Configure Artisan:

{ "custom_attribution_property": "data_source", "attribution_value": "Artisan AI"}

Result: Every contact created or updated by Artisan will have the data_source field set to “Artisan AI”.

Important: To update the attribution on existing contacts, include the custom property in your overwrite_fields list.

Do Not Contact (DNC) Settings

Artisan helps you avoid reaching out to leads that already exist in your CRM, protecting your customer relationships and preventing duplicate outreach.

How DNC Works

When you enable “Do Not Contact leads found in CRM” for a campaign:

1. Email-Based Matching:
    Artisan checks if the lead’s email address already exists as a contact in your HubSpot

2. Automatic Exclusion:
    Matching leads are automatically excluded from outreach sequences

3. Real-Time Checking:
    This check happens before any outreach is initiated

CRM Blocklist Filters

For more granular control, you can set up CRM blocklist filters that check specific conditions in HubSpot before reaching out. This allows you to:

• Only block leads matching certain criteria (e.g., lead status = “Customer”)

• Allow outreach to contacts that exist but meet certain conditions

• Create complex rules based on HubSpot properties

Active Deals Check

Domain-Level Deal Protection

Artisan automatically protects your existing business relationships by checking for active deals at the domain level.

How It Works:

1. When processing leads, Artisan extracts the email domain (e.g., example.com from [email protected])

2. We check if any contact at that domain has associated deals in HubSpot

3. If deals exist, the lead is blocked from outreach to protect your relationship

Key Features:

• Domain-wide protection: If [email protected] has an active deal, we won’t reach out to [email protected]

• Smart filtering: Free email domains (Gmail, Yahoo, Outlook, etc.) are excluded

• Fail-open design: If there’s an API error, leads are allowed through

Benefits:

• Protects existing customer relationships

• Prevents embarrassing outreach

• Maintains professionalism

Email Message Sync

Artisan syncs all communication history with your HubSpot contacts.

Email Sync:

• Outbound emails: Logged as EMAIL direction

• Inbound replies: Logged as INCOMING_EMAIL direction

• Full context: Subject, body, timestamps, sender/recipient

FAQs

Q: What happens if a contact already exists in HubSpot?
A: By default, Artisan will link the existing HubSpot contact to your Artisan lead without modifying any data. If you need to update existing contacts, you must configure the overwrite_fields setting.

Q: How do I know which contacts came from Artisan?
A: New contacts created by Artisan will have hs_object_source_detail_2 set to your campaign name. For existing contacts, we recommend setting up a customattribution property (see Custom Attribution Property).

Q: Can I use different field mappings for different campaigns?
A: Field mappings are configured at the account level and apply to all campaigns. Contact your Artisan representative if you need campaign-specific mappings

Q: What permissions does Artisan need in HubSpot?
A: Artisan requires the following scopes:

• Read/write contacts

• Read/write communications

• Read deals (for active deals check)

• Read lists (for CRM list imports)

Q: How often does Artisan sync with HubSpot?
A: Leads are synced based on your export configuration:

• Export All Leads: Syncs all leads from your campaigns

• Export Engaged Leads: Only syncs leads that have replied

Q: What if I disconnect and reconnect my HubSpot account?
A: Artisan will maintain the mapping between your leads and HubSpot contacts. When you reconnect, syncing will resume normally.

Need Assistance?
Contact our Support team if you have any questions or issues!