HubSpot
Overview
Section titled “Overview”Signals writes leads captured on an ad platform or a form straight into HubSpot, so they enter your existing lifecycle and workflows without a manual import.
Signals maps each lead form field to a HubSpot field and creates the record in the object you choose. The lead arrives with the platform lead ID attached, which is what lets you tie a HubSpot record back to the ad that produced it.
This is the reverse of the HubSpot source connector, which reads records out of HubSpot to send to an ad platform.
Supported sources
Section titled “Supported sources”Sources supported by HubSpot
| Category | Supported |
|---|---|
| Lead generation |
Prerequisites
Section titled “Prerequisites”Before connecting HubSpot, make sure you have:
- A HubSpot account, and access to the portal you intend to write to.
- A field in the target object to hold the lead ID from your source. Create it before you start.
- A Datahash Studio account with the target project selected.
- A lead generation source already connected in the same project.
Authentication
Section titled “Authentication”In Studio, open Destinations, find the CRM category, and click the HubSpot tile. This connector uses single sign-on only, so there is no private app token to create.
- Click Sign in with HubSpot.
- Choose the HubSpot account you want to connect and approve the requested permissions.
If you manage several portals, check which one you selected. The connection screen does not show the portal name again afterwards.
Configuration
Section titled “Configuration”Source and connection
Section titled “Source and connection”- Choose the source type, which is the lead platform or form the leads come from.
- Select the connection name created when that source was set up.
- Give this destination connection a name.
Then choose the HubSpot object the leads should be written to. Contacts is the usual choice; Deals is also available where a lead should open a deal directly.
The connector writes into one object per connection. If you need both a contact and a deal, set up two instances.
- Click Next.
Field mapping
Section titled “Field mapping”The mapping screen puts your lead form fields on the left and the HubSpot schema fields on the right.
Two rules apply to every mapping on this connector.
- The lead ID from your source must be mapped. It is named after the platform the lead came from, for example Meta Lead ID or TikTok Lead ID, and it is the only field that has no substitute.
- Every field your CRM marks as required, shown with an asterisk in the mapping screen, must be mapped as well. An unmapped required field fails the record rather than the connection, so the setup will look healthy while leads quietly do not arrive.
Map as many further fields as you need. Anything you leave unmapped is simply not written.
Test connection and response preview
Section titled “Test connection and response preview”Click Test Connection before finishing. This sends a sample record into HubSpot, so the test lead lands in your live CRM and someone will need to remove it afterwards. Once the test passes, click Finish.
Manage instance
Section titled “Manage instance”To add another, open Manage Connections and click Add Instance, then work through the same steps. A CRM can hold several instances, so one connection per lead source is a reasonable pattern where the mapping differs between them.
To change one, click the connection name in Manage Connections, then the edit icon in the top right. Update the fields, click Test Connection and then Finish. Clicking Cancel keeps the previous configuration running; updates apply only after you finish.
Data & identifiers
Section titled “Data & identifiers”Lead data is written into your own CRM, so nothing is hashed on the way. What arrives is what the lead form captured, in plain text, which means the CRM’s own access controls and retention rules are what govern it from that point on.
There is no fixed field specification for this destination. The fields available to map are whatever your lead form captured on one side and whatever your CRM schema exposes on the other, so the shape differs from one connection to the next.
Best practices
Section titled “Best practices”- Create the lead ID field in HubSpot before you begin, or the mapping step will stop you.
- Map every field marked with an asterisk. Records failing a required-field check are rejected without the connection changing state.
- Decide deliberately between Contacts and Deals. Writing every lead as a deal will distort your pipeline reporting.
- Remove the test record after Test Connection passes. It is a real record in your live portal.
- Check which portal you authenticated against if you manage more than one.
Troubleshooting & FAQ
Section titled “Troubleshooting & FAQ”No account appears at sign-in. The HubSpot user you signed in with does not have access to a portal, or the permissions were not approved. Sign in again and approve them.
Leads are not arriving. Confirm the source is connected in the same project and receiving leads, and that the connection was finished rather than left open.
Some leads arrive and others do not. The ones failing are missing a value for a HubSpot required field.
Leads landed in the wrong portal. The portal is fixed by the account you authenticated with. Reconnect with the right one and set up a new instance.
A test record is sitting in HubSpot. That is the sample sent by Test Connection. Delete it manually.
Delivery stopped. The sign-in grant may have been revoked. Reconnect through Sign in with HubSpot.