HubSpot Integration Setup Guide

This guide walks you through connecting VerdictFlow to your HubSpot CRM, configuring sync settings, and getting your first contacts flowing between both systems.

Prerequisites

Before you begin, make sure you have:

A VerdictFlow account on the Pro or Enterprise plan (HubSpot integration is not available on the Starter plan)
A HubSpot account with admin access to authorize third-party apps
At least one pipeline configured in HubSpot if you plan to use deal-based tracking

Connecting Your HubSpot Account

Navigate to Integrations

In VerdictFlow, go to Settings → Integrations → HubSpot and click Connect HubSpot.

Authorize VerdictFlow

You'll be redirected to HubSpot's OAuth authorization page. Review the permissions VerdictFlow is requesting and click Connect app.

VerdictFlow requests access to contacts, deals, companies, custom properties, and files in order to provide the full two-way sync experience.

Setup Wizard

After authorization, you'll be taken to the VerdictFlow setup wizard. This walks you through configuring how data flows between VerdictFlow and HubSpot.

Choosing a Tracking Method

VerdictFlow supports three methods for tracking cases in HubSpot:

Contact Statuses

Track case progress using HubSpot contact status properties (e.g., lead status, lifecycle stage). Best for firms that manage their pipeline primarily through contact records.

Deal Stages

Track case progress using deal pipeline stages. Best for firms that create a deal for each case and move it through pipeline stages.

Both

Use both contact statuses and deal stages. VerdictFlow will update both when status changes occur and listen for changes on both objects via webhooks.

Configuring Status Mappings

Status mappings define how HubSpot contact statuses correspond to VerdictFlow lead statuses. The setup wizard reads your actual HubSpot property values so you map to real statuses, not generic defaults.

From HubSpot to VerdictFlow

Map each HubSpot contact status (e.g., "New", "Open", "In Progress") to the corresponding VerdictFlow status (e.g., "new", "in_review", "qualified"). When a contact's status changes in HubSpot, VerdictFlow will update the lead status automatically.

From VerdictFlow to HubSpot

Map each VerdictFlow lead status to the corresponding HubSpot contact status. When a lead's status changes in VerdictFlow (e.g., via referral acceptance), the HubSpot contact will be updated.

Deal Stage Mapping

If you chose "Deals" or "Both" as your tracking method, you'll configure how VerdictFlow statuses map to your HubSpot deal pipeline stages.

Select a Pipeline

Choose which HubSpot deal pipeline VerdictFlow should use for creating and tracking deals.

Map Stages

For each VerdictFlow status in the referral lifecycle (new, in review, qualified, referred, retained, settled, dropped), select the corresponding deal stage in your pipeline.

Set a Default Stage

Choose which pipeline stage new deals should be created in when a lead is first exported to HubSpot.

Export Settings

Export settings control what happens when a lead is synced from VerdictFlow to HubSpot:

Create Deal on Export

When enabled, VerdictFlow automatically creates a deal in your configured pipeline whenever a contact is exported. The deal is linked to the contact and includes the case type and VerdictFlow tracking IDs.

Upload Documents on Export

When enabled, all documents attached to the lead (medical records, intake forms, police reports, etc.) are uploaded to HubSpot's File Manager and attached to the contact as notes. Your intake team can access case files directly from the HubSpot contact timeline.

Importing Contacts

During setup, you can import existing HubSpot contacts into VerdictFlow. The import process:

Reads all contacts from your HubSpot portal
Creates corresponding leads in VerdictFlow
Deduplicates by email address to avoid creating duplicates
Skips contacts that are missing required fields (first name, last name, or email)
Links each VerdictFlow lead to its HubSpot contact ID for ongoing sync

You can also import contacts later from the HubSpot integration management page.

How Ongoing Sync Works

Once connected, VerdictFlow maintains a two-way sync with HubSpot:

HubSpot to VerdictFlow (Webhooks)

VerdictFlow listens for HubSpot webhook events. When a contact's status changes or a deal moves to a new stage in HubSpot, VerdictFlow receives the update in real time and maps it to the corresponding lead status using your configured mappings. This powers automated referral routing — change a contact to "Ready for Referral" in HubSpot and VerdictFlow sends it to your partner firms automatically.

VerdictFlow to HubSpot (Automatic Export)

When a referral is accepted in VerdictFlow, the system automatically creates a contact (and optionally a deal) in the receiving firm's HubSpot with all case details. Status changes flow back to the sending firm's HubSpot contact record with timestamped activity notes at each milestone.

Token Refresh

VerdictFlow automatically refreshes your HubSpot OAuth token when it expires. If a token cannot be refreshed (e.g., it was revoked in HubSpot), you'll see a notification in VerdictFlow prompting you to reconnect.

Custom Properties Created

During the OAuth connection, VerdictFlow automatically creates custom properties on your HubSpot contacts and deals. These properties are used to track referral status and maintain the link between VerdictFlow and HubSpot records.

Contact Properties

Property	Description
verdictflow_lead_id	VerdictFlow lead record ID
verdictflow_contact_id	VerdictFlow contact record ID
verdictflow_source	Source of the contact (e.g., "VerdictFlow Referral")
verdictflow_case_type	Type of legal case
verdictflow_referring_firm	Firm that referred this contact
verdictflow_referral_status	Full timeline of referral status changes
verdictflow_referral_firm	Firm(s) that received the referral
verdictflow_referral_last_updated	Last update timestamp for referral status
verdictflow_referral_id	VerdictFlow referral record ID

Deal Properties

Property	Description
verdictflow_lead_id	VerdictFlow lead record ID
verdictflow_referral_id	VerdictFlow referral record ID
verdictflow_source	Source of this deal
verdictflow_case_type	Type of legal case from VerdictFlow

Troubleshooting

Connection expired or revoked

If your HubSpot connection stops working, go to Settings → Integrations → HubSpot and click Reconnect. This refreshes your OAuth tokens without losing your configuration.

Contacts not syncing

Ensure your status mappings are configured correctly. If a HubSpot status doesn't have a corresponding VerdictFlow mapping, changes to that status will be logged but not reflected as a lead status change.

Deals not being created

Verify that "Create Deal on Export" is enabled in your export settings and that you have a pipeline and default stage selected. If custom VerdictFlow deal properties don't exist in your portal, VerdictFlow will retry without them.

Documents not uploading

Make sure "Upload Documents on Export" is enabled. HubSpot has a 100MB file size limit per upload. Files exceeding this limit will be skipped.