How to Connect HubSpot

Prerequisites#

A HubSpot account (free or paid)
Admin access in HubSpot
An active scoring profile in Zero Bad Leads

Connect HubSpot#

Access Outbound Integrations

In the sidebar, click Send Leads. Find the HubSpot card and click "Integrate".

Authorize via OAuth

You will be redirected to HubSpot to authorize the connection. Log in to your HubSpot account and select the portal you want to connect.

Zero Bad Leads requests permissions to create and update contacts and deals in your HubSpot. No bulk read permissions are requested.

Configure the integration

After authorizing, you will return to Zero Bad Leads. Configure:

Integration name: give it a descriptive name (e.g., "Main HubSpot")
Action: choose between creating a Contact, Deal, or both
Pipeline and Stage: if creating deals, select the pipeline and initial stage

Configure field mapping

Map Zero Bad Leads fields to HubSpot fields:

Zero Bad Leads	HubSpot
Email	email
Full name	firstname / lastname
Phone	phone
Company	company
Score	lead_score (custom field)

Activate and test

Activate the integration and send a test lead. Check in HubSpot that the contact was created correctly.

Dispatch filters#

You can configure filters to send only specific leads to HubSpot:

Minimum score: send only leads with a score above a threshold (e.g., 70)
List: send only leads from specific lists
Fields: filter by field values (e.g., company is not empty)

See more details at Dispatch filters.

Automatic retry#

If the dispatch fails (e.g., HubSpot is down), Zero Bad Leads automatically retries:

1st attempt: immediate
2nd attempt: after 1 minute
3rd attempt: after 5 minutes
4th attempt: after 15 minutes
5th attempt: after 30 minutes

After 5 unsuccessful attempts, the lead is marked as "error" and you can view it in the logs.

Troubleshooting#

"Token expired" or authentication error: Zero Bad Leads automatically renews OAuth tokens. If the error persists, disconnect and reconnect the integration.

Duplicate lead created in HubSpot: HubSpot identifies contacts by email. If the lead already exists, Zero Bad Leads updates the existing contact instead of creating a new one.