HubSpot Integration Behaviors
Important: This feature is only available for the current version of the SaaSquatch platform. If your program was created before April 2019 and you're interested in this feature, reach out to our Success team to chat about upgrading.
Our native integration with HubSpot automatically shares data between SaaSquatch and your HubSpot Sales and Marketing Hubs. After set-up, HubSpot will be able to send referral tracking, contacts and deal stage information directly to SaaSquatch. Important SaaSquatch information like referral codes, share links, and more will be visible on contact records. You can also set up a HubSpot contact submission form that sends referral data to SaaSquatch.
This doc goes into detail about specific data sharing and event handling behaviors. If you’re looking for a general overview of the integration’s features, see our HubSpot integration doc. For setup instructions, check out Integrating SaaSquatch with HubSpot.
🔗 Data sharing
SaaSquatch and HubSpot share data through a combination of report-based syncs and webhooks.
Our report-based syncs from SaaSquatch to HubSpot run with 1-minute intervals in between. They transmit to HubSpot any created or updated participant information that occurred after the previous sync.
Data from HubSpot is shared to SaaSquatch with webhooks. When we receive a webhook that triggers the creation or mapping of a contact with a SaaSquatch participant, we immediately send SaaSquatch properties back to the contact in HubSpot. This means you’ll see SaaSquatch-specific properties, like referral code and share link, as soon as a contact is created or updated.
🔗 Sharing rules
By default, there are several situations in which we send data between platforms.
The Shared Fields table has a list of the specific fields that are shared between platforms during a creation or update.
Note: Your HubSpot account settings determine whether new contacts are marketing or non-marketing.
| Adjustable rule? | If | Then |
|---|---|---|
| Yes | A SaaSquatch participant is created | Create a contact in HubSpot |
| An existing, unmapped SaaSquatch participant is updated | ||
| A HubSpot contact is created | Create a new participant in SaaSquatch | |
| An existing, unmapped HubSpot contact is updated | ||
| No | A contact is deleted in HubSpot | Delete the mapped participant in SaaSquatch |
| A deal stage is updated in HubSpot | Send a matching event to the mapped participant in SaaSquatch | |
| An existing, mapped participant is updated in SaaSquatch | Update the mapped contact’s record in HubSpot | |
| An existing, mapped contact is updated in HubSpot | Update the mapped participant’s details in SaaSquatch | |
| A contact is restored in HubSpot |
Re-create the participant in SaaSquatch. Important: Participant data like referral history cannot be restored. See the Participant deletion section for more information. |
🔗 Shared fields
We share data between specific HubSpot and SaaSquatch fields when a creation or update is triggered. Check your integration’s data flow under Settings > Integrations to see which apply for your program.
Note: We consider a HubSpot contact’s record to be updated if one of these fields has changed values: email, referred-by code, referral cookies, user ID or account ID.
| If | Then send data from | From field | To field |
|---|---|---|---|
|
A SaaSquatch participant is created Example: Someone who isn’t a HubSpot contact signs up for your referral program. |
SaaSquatch to HubSpot | First name | First name |
| Last name | Last name | ||
| Program referral code | Referral code | ||
| Program share link | Share link | ||
| User ID | SaaSquatch user ID | ||
| Account ID | SaaSquatch account ID | ||
| Message links | Message links | ||
|
An existing SaaSquatch (mapped or unmapped) participant is updated Example: An existing program participant hasn’t yet been mapped to the matching HubSpot contact. |
SaaSquatch to HubSpot | Program referral code | Referral code |
| Program share link | Share link | ||
| User ID | SaaSquatch user ID | ||
| Account ID | SaaSquatch account ID | ||
| Message links | Message links | ||
|
A HubSpot contact is created Example: A new contact is added to HubSpot through your lead submission form. |
HubSpot to SaaSquatch | Referred-by code | Referred-by code |
| Referral cookie | Cookie | ||
| Contact ID | HubSpot contact ID | ||
|
An existing (mapped or unmapped) HubSpot contact is updated Example: We receive a contact property change webhook. |
HubSpot to SaaSquatch | First name | First name |
| Last name | Last name | ||
| User ID | |||
| Account ID | |||
| Referred-by code | Referred-by code | ||
| Referral cookie | Cookie | ||
| Contact ID | HubSpot contact ID |
Participant deletion
When a contact is deleted in HubSpot, their mapped SaaSquatch participant will also be deleted. Please note that participant deletion in SaaSquatch is irreversible and will impact your analytics and referral history information.
We support two types of participant deletion:
- Standard deletion, which allows a new participant to be created with the same email address
- GDPR-compliant deletion, which does not allow participant restoration or re-creation in SaaSquatch
🔗 Participant restoration
To a limited extent, restoring a HubSpot contact re-creates the mapped participant in SaaSquatch. However, the re-created participant’s profile won’t display their previous referral history and associated analytics.
Contacts who request a GDPR-compliant, permanent deletion are never re-created in SaaSquatch. We mark any permanently deleted participants with a do not track label that prevents another participant from being created with this email address.
🔗 Mass syncs
Mass syncs are an optional way of updating SaaSquatch information in HubSpot. You can trigger a mass sync when:
- Setting up the integration
- Changing connected programs
All participants on your tenant are updated or created in HubSpot when you run a mass sync. We follow your data sharing rules to determine the specific sync behavior. For example, if your integration is set up to create contacts when a new participant is detected, we’ll also match any existing but unmapped SaaSquatch participants during the mass sync.
🔗 Mapping behaviors
We don’t automatically share changes to participants’ or contacts’ personally identifying information (name and email address) between platforms. This approach helps to avoid unintentional impacts to your sales or marketing processes.
From a program standpoint, a mapped contact and participant don't need to have matching email addresses after the initial data sync. The contact and participant will always be linked based on the SaaSquatch user ID and account ID stored on the HubSpot contact. You can manually update the contact or participant record, but it’s not required for successful referral tracking.
🔗 Remapping contacts and participants
Contacts and participants can be manually remapped. We recommend doing so only in limited situations, such as if a business and personal contact need to be merged into the same participant. To map a contact with a different participant, change the user and account ID fields in HubSpot to match the participant you want to connect to.
🔗 Program changes
Important: Only one referral program can be connected with HubSpot at a time. While you may change the connected program later, it’s best to avoid doing so unless necessary.
The program you select acts as the source of three new contact properties: referral code, share links and message links. When you change connected programs, we:
- Delete all of the contact properties we previously created
- Re-create the properties using the newly-selected program
You have the option to run a mass sync when you change connected programs. The mass sync automatically updates all referral codes, share links and message links in HubSpot so that they reflect your current program. However, HubSpot forms, emails and other features that use SaaSquatch properties will need to be manually updated in order to continue working properly.
🔗 Event handling
This integration adds a new HubSpot-managed event: hubspot_deal_status_changed. Its properties can be viewed in the Admin Portal under Data > Events. Clicking the event name takes you to the event details page, which includes a full list of the event fields.
You can adjust your program to trigger whenever we receive this event and one of the dealProperties matches your selected criteria. The most common use case is rewarding a referrer or referred user when the dealProperties.dealstage field changes to closedwon.
🔗 Deals with multiple contacts
We can only credit one contact with dealProperties.dealstage change. If your deal has multiple contacts, then we run three checks to determine which contact receives the event data.
- Check 1: Is at least one contact mapped to a SaaSquatch participant? If no, then we don’t record any data.
- Check 2: Were any of the contacts referred through your program? If yes, then the event is added to the earliest referral.
- Check 3: When were the contacts created in HubSpot? If no contacts were referred, then the event is added to earliest contact.
Here’s how these checks play out in two examples where a deal has three contacts: Sam, Alex and Tom.
Example 1: Sam and Alex were previously referred through your program, but Tom wasn’t. Sam was referred in 2021 and Alex was referred in 2022. In this example, check 2 passes, so we add the event to the earliest referral: Sam. Sam’s participant record receives the status change event, and Sam is rewarded by your program.
Example 2: None of the contacts were previously referred through your program, but all are mapped with SaaSquatch participants. Tom was added as a contact in 2020, Sam in 2021, and Alex in 2022. In this example, check 3 passes, so we add the event to the oldest contact: Tom. Tom’s participant record receives the status change event, and Tom is rewarded by your program.
🔗 Ready to get started?
Check out our setup guide for more information about how to set up the integration and use it in your program.