The information contained in this document is confidential, privileged, and only for the use of internal Birdeye users. This document may not be used, published or redistributed.
This integration is supported for both SMB & Enterprise businesses.
Integrating Birdeye with HubSpot
User Manual - SUPPORT ARTICLE
HubSpot is an inbound marketing and sales platform for organizations that helps them attract new customers, convert leads and close customers. Integrating HubSpot with Birdeye will automate the process of sending out review requests to clients on a daily basis. Once HubSpot is integrated with Birdeye, Birdeye will pull client information from HubSpot daily from the cases that were closed on the previous day. Birdeye collects the first name, last name, email address and phone number of your clients and automatically sends them review requests based on the preferences set within the Birdeye dashboard.
Table of Contents
Triggers Supported
Information required from the Business
Information from Birdeye dashboard
Login
Manage Triggers
Manage Properties
Manage Locations
Integration Requirements
Triggers Supported
Birdeye allows you to fetch data from your CRM using some predefined triggers. You can choose any combination from the list of available triggers and inform the support team about your selection. Here is the supported trigger for HubSpot:
Trigger Display Name |
Trigger Name/
Value
| Trigger Description |
HubSpot Custom Status Deals Trigger | Deal | This trigger is used to fetch contact data based on the closed/custom status deals. |
HubSpot Contact Trigger | Contact | This trigger is used to fetch contact data based on the contact trigger key from the custom properties group. |
HubSpot Ticket Status Tigger | Ticket Status | This trigger is used to fetch contacts from the tickets. |
Details required from the Birdeye client
Trigger details
Custom deal stage (for Custom Status Deals Trigger)
Contact trigger key (for Contact Trigger)
Custom Contact Properties(for Contact Trigger)
Contact trigger value(for Contact Trigger)
Custom properties group Name(for Contact Trigger)
Location Custom Field Name(for Enterprise)
HubSpot Location Name(s) per Birdeye location(for Enterprise)
Custom Pipeline Name (Optional, if other than the default Sales pipeline)
Steps to find location custom field name(for Enterprise setup only)
To ensure deals are mapped to the right business location, it is essential to create a custom deal property within your HubSpot account. To create a new custom deal property, click on the 'Create a property' button under the ‘Deal properties’ tab on the ‘Property settings’ page.
NOTE: A new property isn’t required if such a deal property already exists.
Enter the ‘Location Custom Field Name' under the ‘Label’ field (Eg: 'Location') and select 'Dropdown select' as the ‘Field type’. Now, enter the name of all your business locations under the drop-down menu and click on the 'Create' button to save your selection.
IMPORTANT: The 'Location' custom field will appear every time you are in the process of creating a deal. To map a deal to a particular location, select the right location from the drop-down menu.
IMPORTANT: In case the ‘Location’ property is not visible while creating a deal, the client can customize all the properties that are visible in the ‘Settings’ tab. To learn how to customize a property, refer to the steps detailed here.
NOTE: In the case of ticket service, it's mandatory to keep the location field name as "Location".
Steps to customize a property
To customize a property, click on the ‘customize the properties’ link at the bottom.
Then select the ‘Location’ option and save the settings.
Steps to find the internal name of any deal property
IMPORTANT: Ask for the ‘Internal name’ of the location’s ‘Custom deal property’ mentioned above. Follow the steps detailed below to find the ‘Internal name’ of any deal property in a Hubspot account:
Go to Sales > Deals > List View
On the new page, click on the ‘Actions’ drop-down menu, and select the ‘Edit properties’ option.
Search for the required property.
Click on the ‘Edit’ button, then go to the two arrow icon. Here you can access the internal name:
In the above case, the ‘hubspot.location.custom.field.name’ would be the ‘locationproperty’.
Steps to find location names(for Enterprise setup only)
Once the client has provided the location custom field name, location name(s) are requested for each Birdeye location. Make sure to ask for the ‘Internal value(s)’ of these locations.
Ask the client to follow the steps mentioned here and then refer to the ‘Internal values’ in the ‘Dropdown select’ as shown below:
Details required from the Birdeye dashboard
Enterprise ID for a multi-location account and Business ID for all locations
Business ID in case of an SMB Business
Information from Birdeye dashboard
For single location SMB account - Business ID
Login to your Birdeye account, go to Left Navigation Rail and click on ‘Settings’. Once the new page appears, click on ‘Integrations’ and select ‘API.’
You will find the ‘Business ID’ and ‘API key’ shown in the image.
For multi-location accounts - Enterprise ID and Business IDs of all locations
Enterprise ID
Business IDs of all locations
Login to your Birdeye account, go to Left Navigation Rail and click on ‘Settings’. Once the new page appears, click on ‘Profile’ and select ‘Business Profiles.’
To view Location ID, hover over the ‘Status’ of location.
Integration Process
Before you can integrate HubSpot with Birdeye, you will need to set up the following configurations on the integration support dashboard:
To set up native integration, we have an integration support dashboard, where we need to set up the integration and then follow these steps to complete the configuration.
Login
After successful login in the integration dashboard, you have to click on ‘BE integration’ and then click on ‘Add Integration’.
Search for the CRM in the search bar and select it. Click on ‘Next’.
Manage Triggers
Select the Trigger Name (Check Box) as per the client’s requirement and click ‘Next’.
Note: To fetch information for all the triggers available using curl commands, use this command. To replace triggers, use this curl command.
Manage Properties
Here; you can manage group-level properties, which will be applied to all locations under a CRM.
Is Refresh All: Set to true if no filteration is required based on the trigger filter key.
Custom Pipeline name: In this field, we set the pipeline name like a sales pipeline.
Custom Contact Properties: Enter the comma-separated properties' internal name, which you want to fetch.
Custom Deal Stage: In this field, we set the custom deal stage of the pipeline. Multiple deal stages can be configured as comma-separated.
HubSpot Ticket Stage: In this field we set the ticket current stage for which we need to send the check-In’s
Custom Ticket Pipeline name: In this field we set the Ticket pipeline name
Location Custom Field Name: This is the field name for the location.
Customer fetch delay: It is used if businesses want to send review requests with a delay (number of days).
Custom Deal Property: In this field, we set the property which is created in HubSpot.
Custom Contact Trigger Key: Enter the key based on which contact will be checked in.
Custom Group Property: Enter the custom group property name, which contains all properties.
Custom Contact Trigger Value: Enter the status value for which the review request needs to be sent.
Use Pipeline Dealstage mapping: If you set “True”, you will be able to use pipeline deal stage mapping. Otherwise, the integration uses a custom pipeline name and a custom deal stage property for fetching data.
Pipeline Dealstage Mapping: In this field, we set the json format, and before submitting it, you have to set the pipeline name and deal stage name. It supports multiple pipelines, and each one with its own set of DealStages.
[This property supports single and multiple pipeline and deal stage name.]
IMPORTANT: The json represents the configuration of two Pipelines(Pipeline1(with DealStages → Stage1, Stage2 and Stage3) and Pipeline2(with DealStages → Stage4, Stage2 and Stage6)). The Pipeline names and DealStages names should be entered with the exact spelling and upper/lowercase letters, else it will lead to errors.
Also, the json formatting should be correct.
[{"pipeline":"SalesPipeline","dealStages":["stage1","stage2","stage3"]},{"pipeline": "Sales Pipeline- Equipment","dealStages": ["stage4","stage2","stage6"]}]Customer checkin delay: This field is used when we want a delay (in Days) in sending the review request to the customer.
Hubspot Client V3 API: To get the customers from the V3 search API, select the dropdown as true. For false and NONE value, the customers will be fetched from the V1 search API.
Note: This step will create a group for our integration. Alternatively, you can do it via curl commands.
For SMB accounts, you can access the curl command.
For Enterprise accounts, you can access the curl command.
Manage Locations
For Single Location/Multi-Location Accounts, select the location from the drop-down menu and click on ‘Add.’
(In the case of Single Location accounts, it will give you only one option).
A drawer will appear on the right-hand side.
The Status, Frequency, and Next Runtime will be set by default. You can make the changes if required.
Status: It shows integration status (Active or Inactive).
Frequency: It is the number of times integration will sync with CRM (Days or Hours).
Next RunTime: It is the next scheduled time when the integrations will run.
Location Names: Enter location names in case of a multi-location business. When you add the location name in the field, provide the pipeline after every location.
For instance, Santico, TX |
NOTE: If you are configuring Hubspot Client V3 API as true, you have to provide the exact location name configured at the Hubspot end (Case Sensitive).Customer fetch delay: It is used if businesses want to send review requests with a delay (number of days).
Override Group Properties: With this, you can override the properties added at the group level, specific to each location.
Click on ‘Next’ and click on ‘Save.’
Once we set up the integration on the dashboard, we need to contact the customer and assist them in creating the custom Field on HubSpot CRM.
Note:
For SMB: You can use ‘manage the locations’ using this curl command.
For Enterprise: You can use ‘manage the locations’ using this curl command.
Completing the Integration Process
After the initial integration is set up by the Birdeye technical support team, you can log in to your Birdeye account to complete the integration process.
To complete the process, click on the 'Settings' tab located on the left navigation rail of your Birdeye dashboard. Click on the ‘Business Profile’ under the ‘Profile’ section.
Click on the specific location for which you have set up the integration.
Once you click on the particular location, it will redirect you to that location. Now, scroll down to the ‘CRM Integrations’, and click on the ‘Authorize’ button to authorize the business.
After you click on the authorization button, you will be redirected to the HubSpot website. Enter the email address and password associated with your HubSpot account and click on 'Log in.’
Once you have logged in to your HubSpot account, Birdeye will ask for certain permissions to obtain client data from your HubSpot account. Click on the 'Grant Access' button at the bottom to complete the integration process.
After the access has been granted, you will be redirected to the Birdeye dashboard, and an 'Authorized' message will appear right next to HubSpot.
Curl Commands
Before you can integrate HubSpot with Birdeye, you will need to set up the following configurations:
A business integration group is a configuration that supports the business hierarchy of individual businesses on the Birdeye platform. The properties that are common for all business integrations are entered at the group level. Setting up a business integration group allows you to associate multiple business locations with the Enterprise account. Below is the list of curl commands that you will need to run to set this up.
Create Integration Group- SMB Businesses (Curl Command)
Copy Curl Command
curl -X PUT https://common-services.Birdeye.com/integration/add/businessintegrationgroup -H 'cache-control: no-cache' -H 'content-type: application/json' -d '{ "parentBusinessNumber": 148493837951138, "integrationSourceId": 24, "integrationGroupProperties": [{ "propertyKey": "hubspot.contact.trigger.key", "propertyValue": “lead_status”},{ "propertyKey": "hubspot.contact.trigger.value", "propertyValue": “ACTV”} { "propertyKey": "customer.custom.group.property", "propertyValue": “Vitals”},{ "propertyKey": "customer.custom.properties", "propertyValue": “lead_status,location,name”},
{ "propertyKey": "custom.deal.stage", "propertyValue": "Deal Sold"}, { "propertyKey": "hubspot.custom.pipeline.name", "propertyValue": "Salesforce-Equipment"}], "integrationGroupTriggers":[{"triggerId":29,"triggerTypeId":1}]}'148493837951138- Business ID - This is Enterprise ID for multi-location account and Business ID for a single location SMB account.
Deal Sold - Custom deal stage - The value for this property will be shared by the client on the initial call. Multiple deal stages can be given as comma separated values.This property is used for custom status deal triggers.
lead_status- Contact trigger key - The value for this property will be shared by the client on the initial call for hubspot contact trigger. Based on this property the customer data will be filtered and review requests will be sent.Please enter the internal name of this property.
ACTV - Contact trigger Value - The value for this property will be shared by the client on the initial call for hubspot contact trigger. Based on this property the customer data will be filtered and review requests will be sent.In case of multiple status pass a comma separated value.Please enter the internal name of this property.
Vitals - Custom properties group name - This property is used to indicate the group for which the client wants properties as additional params.
lead_status,location,name - Custom properties name - This property is used to indicate the properties internal name list which is required by the client as additional params. Please pass this list in case of properties required from multiple groups or groups containing large properties but only limited properties data is required.
Salesforce-Equipment - Custom pipeline name - This property is optional. The client can enter the custom pipeline name if any other pipeline rather than the default pipeline i.e. Sales pipeline is required. This can not take multiple values.
29- Integration Trigger ID - Can be one or more triggers. Ask the client what trigger they would like to integrate with then run the curl command to fetch all possible triggers for HubSpot. Identify the trigger ID (s) and insert (use commas) in case of multiple trigger IDs.
Create Integration Group -Enterprise Businesses (Curl Command)
Copy Curl Command:
curl -X PUT https://common-services.Birdeye.com/integration/add/businessintegrationgroup -H 'cache-control: no-cache' -H 'content-type: application/json' -d '{ "parentBusinessNumber": 148493837951138, "integrationSourceId": 24, "integrationGroupProperties": [{ "propertyKey": "hubspot.contact.trigger.key", "propertyValue": “lead_status”},{ "propertyKey": "hubspot.contact.trigger.value", "propertyValue": “ACTV”} { "propertyKey": "customer.custom.group.property", "propertyValue": “Vitals”},{ "propertyKey": "customer.custom.properties", "propertyValue": “lead_status,location,name”},{ "propertyKey": "custom.deal.stage", "propertyValue": "Deal Sold"}, { "propertyKey": "hubspot.custom.pipeline.name", "propertyValue": "Salesforce-Equipment"},{"propertyKey": "hubspot.location.custom.field.name", "propertyValue": "community_mapping" }], "integrationGroupTriggers":[{"triggerId":29,"triggerTypeId":1}]}'148493837951138- Business ID - This is Enterprise ID for multi-location account and Business ID for a single location SMB account.
Deal Sold - Custom deal stage - The value for this property will be shared by the client on the initial call.Multiple deal stages can be given as comma separated values.
lead_status- Contact trigger key - The value for this property will be shared by the client on the initial call for hubspot contact trigger. Based on this property the customer data will be filtered and review requests will be sent.Please enter the internal name of this property.
ACTV - Contact trigger Value - The value for this property will be shared by the client on the initial call for hubspot contact trigger. Based on this property the customer data will be filtered and review requests will be sent.In case of multiple status pass a comma separated value.Please enter the internal name of this property.
Vitals - Custom properties group name - This property is used to indicate the group for which the client wants properties as additional params.
lead_status,location,name - Custom properties name - This property is used to indicate the properties internal name list which is required by the client as additional params. Please pass this list in case of properties required from multiple groups or groups containing large properties but only limited properties data is required.
Salesforce-Equipment - Custom pipeline name - This property is optional. The client can enter the custom pipeline name if any other pipeline rather than the default pipeline i.e. Sales pipeline is required. This can not take multiple values.
community_mapping -location.custom.field.name: Insert the "hubspot.location.custom.field.name" custom field property in the curl command as provided by the client during the initial setup call. (This should be the internal name of the deal property) Refer Steps to find location custom field name(for Enterprise setup only) and Steps to find internal name of any deal property
In case of hubspot contact trigger this property will contain the internal name of property under custom group which can be used as location identifier.29- Integration Trigger ID - Can be one or more triggers. Ask the client what trigger they would like to integrate with then run the curl command to fetch all possible triggers for HubSpot. Identify the trigger ID (s) and insert (use commas) in case of multiple trigger IDs.
Fetch information for all the triggers available for HubSpot (Curl Command)
Copy Curl Command:
curl -X GET https://common-services.Birdeye.com/integration/trigger/integrationtriggers/sourceid/24-H 'cache-control: no-cache' -H 'content-type: application/json'
Sample response: A sample response like this would appear after you run the curl command. The response will have the trigger name, description and the ID. This trigger Id will be utilized while creating the integration group. An integration can have one or more triggers. To use more than one trigger, enter comma separated values while creating the integration group.
[
{
"id": 29,
"integrationSourceId": 24,
"triggerService": "hubSpotCustomStatusDealsTriggerService",
"displayName": "HubSpot Custom Status Deals Trigger",
"description": "This trigger is used to fetch customer data based on the custom status deals.",
"active": true,
"integrationSourceName": "HubSpot",
"integrationTriggerType":[{"id":1,"name":"JOB"}]
}
]29- Trigger IDFind business integration group details (Curl Command)
Copy Curl Command:
curl -X GET https://common-services.Birdeye.com/integration/businessintegrationgroup/149451644517222 -H 'Cache-Control: no-cache'
149451644517222- Business ID: Enter the Business ID here to get the integration group details for a business.
Sample:
[
{
"groupId": 176,
"integrationSourceType": {
"id": 24,
"integrationSource": "HUBSPOT",
"sourceCategory": "Other",
"oauthEnabled": true
},
"integrationGroupTriggers": [
{
"triggerId": 29,
"triggerTypeId": 1
},
{
"triggerId": 119,
"triggerTypeId": 1
}
]
}
]176- Group ID: A group ID will be returned in the sample response with the details of the existing triggers for a business.
Update triggers in Integration Group (Curl Command)
Copy Curl Command:
curl -X POST 'https://common-services.Birdeye.com/integration/update/businessintegrationgroup?replaceTriggers=true' -H 'cache-control: no-cache' -H 'content-type: application/json' -d '{ "groupId": 176,"integrationGroupTriggers":[{"triggerId":29,"triggerTypeId":1}]}'replaceTriggers=true To replace existing trigger(s), enter the value for replaceTriggers as true. To add new trigger(s) to the existing list, the value for replaceTriggers should be false.
176- The Group ID which was returned in the previous step will be entered here.
29-Enter the Trigger ID (s) which need to be added or updated to the integration.
Integration Mapping (SMB Businesses)
Copy Curl Command:
curl -X PUT https://common-services.Birdeye.com/integration/add/businessintegrationmapping -H 'cache-control: no-cache' -H 'content-type: application/json' -d '{ "businessNumber": 151810587563907, "integrationGroupId" : 176, "active": true }'151810587563907- Business Number: Enter the Business number here.
176- Integration Group Id: Enter the Integration Group Id, which was returned when the Integration group was created.
Integration Mapping (Enterprise Businesses):
Copy Curl Command:
curl -X PUT https://common-services.Birdeye.com/integration/add/businessintegrationmapping -H 'cache-control: no-cache' -H 'content-type: application/json' -d '{"businessNumber": 152853169259760, "integrationGroupId" : 195, "active": true, "integrationProperties":[{ "propertyKey": "hubspot.location.names", "propertyValue": "Paisley FD Zero"}]}'151810587563907- Business Number: Enter the Business number here.
195- Integration Group Id: Enter the Integration Group Id, which was returned when the Integration group was created.
Paisley FD Zero - Location Name: Enter the Location names as per the names specified in the HubSpot account for the Location picklist corresponding to this business. These values should be internal values only. Refer to the steps to find location names(for Enterprise setup only).
Important Instructions for Email opt-in/ opt-out
How to request email opt-out
Select the ‘Contact.’
Click on the ‘Actions’ drop-down button and select ‘Opt out of email.’
How to request email opt-in
Click on the ‘View subscription.’
Hover over the ‘Unsubscribed’ and click on the ‘Resubscribe’ button.
A screen will pop up, select the legal basis for communicating with contact with the drop-down button. Write the explanation and click the ‘Save’ button.
NOTE: The status will change to subscribed.
How to request SMS opt-in/opt-out
We create the property for SMS opt-in and opt-out.
Search SMS in the search bar.
Click on the drop-down button to view the options.
Select ‘True’ for SMS opt-in and ‘False’ for SMS opt-out.
Fetch Deal stage ID and Pipeline ID for Campaign conditions.
These steps are used when the integration is complete, and you want to set up campaigns or automation based on a specific deal stage or pipeline. In check-in data, we get the deal stage id as a custom field. To use the deal stage ID for campaign conditions, you need to run the following API to get the deal stage ID and pipeline ID.
Step 1: Check the ‘refersh_token’ property for the business location in the Integration _properties table in the Integration database.
Step 2: Once you get the Refresh_token, decrypt it in the online decrypter.
Step 3: Enter the decrypted refresh token in their first API Body.
Copy this command - Generate Refresh Token
curl --location --request POST 'https://api.hubapi.com/oauth/v1/token' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=refresh_token' \ --data-urlencode 'client_id=406638d1-b137-4d36-b1b0-cf2ea685dd92' \ --data-urlencode 'client_secret=44a18f74-83aa-4818-a936-41480c6e7f73' \ --data-urlencode 'redirect_uri=https://birdeye.com/crm/callback.php' \ --data-urlencode 'refresh_token=8f6de1f3-c832-4a69-aa59-bac03a722644'
Step 4: Once you run the first API it will give the ‘access_token.’
Step 5: Once you get the access token, add it to the ‘Authorization’ field in the second API and run the API. You should have the response with the deals and pipeline ID.
Copy this command - Fetch Deals and Pipeline using access token
curl --location --request GET 'https://api.hubapi.com/deals/v1/pipelines' \ --header 'Authorization: Bearer CO3xyYjPMBIMAAEAQAAAAQIAAAA4GMzNAiCX3fsBKIHuCjIU4ZffmGoTJ4G-DV76OGuxSPp6UD46MAAAAEEAAAAAAAAAAAAAAAAAgAAAAAAAAAAAACAAAAAOAOABAAAAAAAA_AcAAADwA0IU9henzXdqM4G9KpHo7C86Gdt7wCZKA25hMVIAWgA'
Campaigns Tags
Campaign tags are used to set up campaigns within the Birdeye dashboard. These tags are either provided by the client or can be fetched from Kibana for already checked contacts.
HubSpot Campaign tags are
Custom.deal.property
Restriction Reason
Restriction reason is used to identify the contacts who have been opted-out(restricted) from sending a review request. This reason can be fetched from Kibana for contacts that are checked-in already.
Possible restriction reasons for Hubspot are:
The deal stage is not on the allowed list
Integration is beta
Description
The stage name does not match with the configured deal stage.