Troubleshooting Your HubSpot Integration

Having trouble integrating Referral Factory with your HubSpot account? Try these troubleshooting tips.

 

In this guide 👇

1. Connection Problems

2. Problems Sending Referred Users (The Person Invited) to HubSpot 

3. Problems Sending Direct Users (The Person Referring) to HubSpot 

4. Problems Where HubSpot Properties Are Unavailable For Selection in Referral Factory

5. Qualification Problems 

6. Problems Syncing Your HubSpot Contacts

 

 

1. Connection Problems

🤔 Problem: You are trying to connect your HubSpot account with Referral Factory but get a permissions error or the connection fails

→ If you are a teammate, make sure you have the correct permissions to connect your HubSpot integration. If you don’t have the required permissions, the main account holder will need to update them for you. Learn more.

→ If you are the main account holder or a teammate with the required permissions inside Referral Factory, check that you are logged into your HubSpot account and have the required permissions inside HubSpot to connect an integration. 

 

2. Problems Sending Referred Users (The Person Invited) to HubSpot 

 

🤔 Problem: No referred users (the Person Invited) are being sent to HubSpot

→ Double check that you have mapped the HubSpot properties {First Name} and {Email}. These are required fields and must be selected for the contact to be created in HubSpot. 

→ Check whether you have mapped any unsupported property field types. Referral Factory currently does not support the following HubSpot property field types:

• Date picker
• Number
• Calculation
• Score
• File

🤔 Problem: Some but not all referred users (the Person Invited) are being sent into HubSpot

→ Verify if the user is already part of your campaign by searching from the Users tab in Referral Factory. If the user joined the campaign before the settings to send direct users were set up, a contact will not be generated in HubSpot. Essentially, the function does not work retroactively.

→ Verify if the contact already exists in HubSpot and check your settings in Referral Factory for how to handle duplicate users. 

→ Check whether any of the HubSpot properties you mapped to Referral Factory during your setup have data validation rules or character limits.

🤔 Problem: Referred users (the Person Invited) are being sent into HubSpot but one or more properties are not being updated

→ Check whether you have mapped any unsupported property field types. Referral Factory currently does not support the following HubSpot property field types:

• Date picker
• Number
• Calculation
• Score
• File

→ Check whether any of the HubSpot properties you mapped to Referral Factory during your setup have data validation rules or character limits.

🤔 Problem: Referred users (the Person Invited) are not updating in HubSpot

→ Make sure you have chosen the option to update contacts under the section "How To Handle Duplicate Users" in your HubSpot integration setup. Whatever fields you have mapped in the integration step will be updated for the contact inside HubSpot. Keep in mind that enabling this setting may result in existing HubSpot contact data being overwritten.

 

3. Problems Sending Direct Users (The Person Referring) to HubSpot 

🤔 Problem: No direct users (the Person Referring) are being sent into HubSpot

→ Double check that you have mapped the HubSpot properties {First Name} and {Email}. These are required fields and must be selected for the contact to be created in HubSpot.

→ Check whether you have mapped any unsupported property field types. Referral Factory currently does not support the following HubSpot property field types:

• Date picker
• Number
• Calculation
• Score
• File

🤔 Problem: Some but not all direct users (the Person Referring) are being sent into HubSpot 

→ Verify if the user is already part of your campaign by searching from the Users tab in Referral Factory. If the user joined the campaign before the settings to send direct users were set up, a contact will not be generated in HubSpot. Essentially, the function does not work retroactively.

→ Verify if the contact already exists in HubSpot and check your settings in Referral Factory for how to handle duplicate users. 

→ Check whether any of the HubSpot properties you mapped to Referral Factory during your setup have data validation rules or character limits.

🤔 Problem: Direct users (the Person Referring) are being sent into HubSpot but one or more properties are not being updated

→ Check whether you have mapped any unsupported property field types. Referral Factory currently does not support the following HubSpot property field types:

• Date picker
• Number
• Calculation
• Score
• File

→ Check whether any of the HubSpot properties you mapped to Referral Factory during your setup have data validation rules or character limits.

🤔 Problem: Direct users (the Person Referring) are not updating in HubSpot

→ Make sure you have chosen the option to update contacts under the section "How To Handle Duplicate Users" in your HubSpot integration setup. Whatever fields you have mapped in the integration step will be updated for the contact inside HubSpot. Keep in mind that enabling this setting may result in existing HubSpot contact data being overwritten.

4. Problems Where HubSpot Properties Are Unavailable For Selection in Referral Factory

🤔 Problem: A custom or default HubSpot property is not showing in Referral Factory 

→ Click the yellow refresh option in the top right hand corner of your screen.

→ Check if you have selected a CRM field for any pages in the campaign builder. If you have chosen to use a CRM field, then Referral Factory will automatically map the  field to HubSpot. Should you wish to map the property differently, rather use an input field or select field and map the field manually.

→ Check whether the property has already been mapped to another field. It is not possible to map a HubSpot property to multiple Referral Factory fields. 

→ Ensure that the HubSpot property is visible, i.e. it should be set to "Show in Forms". 

→ Try disconnecting your HubSpot integration and clearing your cache. After doing so, reconnect and attempt again to see if the property appears in the available options.

🤔 Problem: The property you have created to store users' referral links is not available for selection

→ Click the yellow refresh option in the top right hand corner of your screen.

→ If you are running multiple campaigns, remember to create a separate property for each campaign's referral link. For example, if you have three separate campaigns, say a referral program, an affiliate program, and an influencer program, then you could create three properties in HubSpot:

{Referral Link}
{Affiliate Link}
{Influencer Link}

 

5. Qualification Problems  

🤔 Problem: The referred user (person invited) has converted in HubSpot but the referral is not being qualified in the Referral Factory

→ Please note that qualification can happen at a delay of up to 12 hours. Referral Factory is busy syncing thousands of data points at any given time and your qualification could be in the queue.

→ Double check that the property or deal stage specified as the qualification trigger in the integration step of your campaign builder matches your desired conversion action in HubSpot.  

→ Double check that the initial value of the property or initial deal stage specified in the integration step of your campaign builder matches the initial value of the contact or deal in HubSpot that hasn't qualified.   

→ Please note that you can only qualify referred users (the person invited). 

 

6. Problems Syncing Your HubSpot Contacts

🤔 Problem: You cannot find a HubSpot list to sync

→ Click the yellow refresh option in the top right hand corner of your screen.

→ If you have many lists in HubSpot, keep scrolling to the bottom of the list options in Referral Factory multiple times. Note that only 100 lists load at once, so scrolling down will load more lists for selection.

→ Try disconnecting your HubSpot integration and clearing your cache. After doing so, reconnect and attempt again to see if the list appears in the available options.

→ Check that you've spelled the name of the list correctly

🤔 Problem: You've configured the sync but only some or no users have been added in Referral Factory

→ Wait up to 12 hours. Referral Factory is busy syncing thousands of data points at any given time. Your sync is probably in the queue and changes will reflect within 12 hours, depending on the number of contacts you have chosen to sync.

→ Check whether the sync will exceed your user limit in Referral Factory. 

→ Ensure that the information for your HubSpot contacts is filled out for the properties you linked to Referral Factory during the setup of your sync, including {First Name}, {Email}, and any other fields you mapped. If any one of these properties is blank, it could result in the contact not being synced.

→ Check whether the contacts you synced already exist as users in Referral Factory. 

🤔 Problem: You've configured the sync and users have been added to Referral Factory but no referral links have populated in HubSpot

→ Wait up to 12 hours. Referral Factory is busy syncing thousands of data points at any given time. Your sync is probably in the queue and changes will reflect within 12 hours, depending on the number of contacts you have chosen to sync.

→ Check that the HubSpot property you created to store the referral link is a single line text field type and that there are no character limits or validation rules that might prevent the data from syncing correctly.