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.
NOTE: If there is an enterprise business to be set up and there are unique sign-in required for every location, such integration should be set up as an SMB i.e an integration group should be created for every location.
Integrating Birdeyewith Housecall Pro
User Manual - SUPPORT ARTICLE
Housecall Pro is a cloud-based field service management program used by service professionals. It hosts various features, including scheduling, work order management, billing, etc. Birdeye can seamlessly integrate with your Housecall Pro account and helps you send review requests automatically.
Once the integration between Housecall Pro and Birdeyeis successful, Birdeye will pull customer information from Housecall Pro daily. Birdeyecollects the first name, last name, email address and phone number of your customers and automatically sends them to review requests based on the preferences set within the Birdeyedashboard.
Table of Contents
Triggers Supported
Information required from the Business
Information from Birdeyedashboard
Login
Manage Triggers
Manage Properties
Manage Locations
Integration Requirements
Triggers Supported
Birdeyeallows you to fetch data from your CRM using a predefined trigger. Here is the supported trigger for Housecall Pro:
Trigger Display Name | Trigger Name/ Value | Trigger Description |
Housecall Pro Webhook Trigger | Jobs | This trigger is used to fetch customer data based on the Jobs Events. |
Information required from the Business
Job events (By default, the event will be Paid)
NOTE: The job event is configurable as per business needs. If the job event is not configured, the default job event will be utilised.
Details required from the BirdeyeDashboard
Location ID for all locations in case of an enterprise business
Business ID in case of an SMB Business.
Information from BirdeyeDashboard
For single location SMB account - Business ID
Login to your Birdeyeaccount, 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 Birdeyeaccount, 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 HouseCall Pro 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
The trigger is automatically selected as only one trigger is supported.
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.
Customer fetch delay: It is used if businesses want to send review requests with a delay (number of days).
Don’t read notification flag: Select true to set subscription status as both-subscribed irrespective of the notification flag; otherwise, the status will be set according to the notification flag value.
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 will be set by default. You can make the changes if required.
Status: It shows integration status (Active or Inactive).
Job Events: You can provide the multiple comma-separated if we have multiple events.
Housecall Pro Job Tags: This field is used to get customers from Housecall Pro Jobs with configured tags.
Override Group Properties: With this, you can override the properties added at the group level, specific to each location.
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 need to log in to your Birdeye account to complete the rest of the integration process.
To complete the process, click on the 'Settings' tab on the left navigation rail of your Birdeyedashboard. 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 a particular location, it will redirect you to that location. Now, scroll down to the ‘CRM Integrations’, and click on the ‘Authorize Housecall Pro’ button to authorize the business.
After you click the authorization button, you will be redirected to the Housecall Pro website. Enter the username and password associated with your Housecall Pro and click on the 'Sign In' button.
Once you have signed in to your Housecall Pro account, Birdeye will ask for certain permissions to access patient data. Click on the 'Authorize' button to grant permission.
After the access has been granted, you will be redirected to the Birdeye dashboard, and an ‘Authorized' message will appear right next to Housecall Pro. Once you are disconnected, you will no longer be able to fetch customer information from HouseCall Pro CRM. The 'Disconnect HouseCall Pro' button will change to 'Connect to HouseCall Pro.’
Curl Commands
Before you can integrate Housecall Pro 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 Birdeyeplatform. The common properties 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 you will need to run to set this up.
Create Integration Group (Curl Command) - For SMB Account
Copy this Curl Command
curl--location --request PUT 'https://common-services.Birdeye.com/integration/add/businessintegrationgroup' \--header 'content-type: application/json' \--data-raw '{"integrationGroupTriggers": [{"actionIds": [1],"triggerId": 100,"triggerTypeId": 2}],"integrationSourceId": 73,"parentBusinessNumber": 158326943359269}'158326943359269 - Business ID - Enter the business ID for the SMB account
100 - Integration Trigger ID - In the case of Housecall Pro, there is only one available Trigger ID. Enter '100' as the Trigger ID and proceed.
Create Integration Group (Curl Command) - For Enterprise Account,
Copy this Curl Command (For Location 1)
curl --location --request PUT 'https://common-services.Birdeye.com/integration/add/businessintegrationgroup' \--header 'content-type: application/json' \--data-raw '{"integrationGroupTriggers": [{"actionIds": [1],"triggerId": 100,"triggerTypeId": 2}],"integrationSourceId": 73,"parentBusinessNumber": 158326943359268}'Copy this Curl Command (For Location 2)
curl --location --request PUT 'https://common-services.Birdeye.com/integration/add/businessintegrationgroup' \--header 'content-type: application/json' \--data-raw '{"integrationGroupTriggers": [{"actionIds": [1],"triggerId": 100,"triggerTypeId": 2}],"integrationSourceId": 73,"parentBusinessNumber": 158326943359267}'158326943359268, 158326943359267 - Business ID - Enter the ID for each location for the enterprise account.
100 - Integration Trigger ID - In the case of Housecall Pro, there is only one available Trigger ID. Enter '100' as the Trigger ID and proceed.
Fetch information for all the triggers available for Housecall Pro (Curl Command)
Copy this Curl Command
curl -X GET https://common-services.Birdeye.com/integration/trigger/integrationtriggers/sourceid/73 -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 ID. This trigger ID will be utilized while creating the integration group. Integration can have one or more triggers. To use more than one trigger, enter comma-separated values while creating the integration group.
[{"id": 100,"triggerService": "housecallProWebhookTriggerService","displayName": "Housecall Pro Webhook Trigger","description": "This trigger is used to fetch customer data based on the Jobs Events.","active": true,"integrationTriggerType": {"id": 2,"name": "WEBHOOK"},"caseCreationTriggerType": {"id": 2,"name": "WEBHOOK"},"actionGroupId": 1,"sourceIdsList": [73],"triggerName": "Jobs"}]100 - Trigger ID - This is the trigger ID available for Housecall Pro.
Find business integration group details (Curl Command)
Copy this Curl Command
curl -X GET https://common-services.Birdeye.com/integration/businessintegrationgroup/158326943359269 -H 'Cache-Control: no-cache'[{"groupId": 13500,"integrationSourceType": {"id": 73,"integrationSource": "HOUSECALLPRO","sourceCategory": "Home Services","integrationType": "BirdeyeAPI","integrationPlan": "Basic","oauthEnabled": true},"integrationGroupTriggers": [{"triggerId": 100,"triggerTypeId": 2,"actionIds": [1]}]}]158326943359269 - Business ID: Enter the Business ID here to get the integration group details for a business.
13500 - 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 this 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": 13500,"integrationGroupTriggers":[{"triggerId":100,"triggerTypeId":2}]}'replaceTriggers=true - To replace existing trigger(s), enter the value for replaceTriggers as true. To add a new trigger(s) to the existing list, the value for replaceTriggers should be false.
13500 - Group ID: The Group ID which was returned in the previous step will be entered here.
100 - Trigger ID: In the case of Housecall Pro, there is only one available Trigger ID. Enter 100 as the Trigger ID and proceed.
Integration Mapping (Single Location Businesses)
Copy this Curl Command
curl --location --request PUT 'https://common-services.Birdeye.com/integration/add/businessintegrationmapping' \--header 'content-type: application/json' \--data-raw '{"businessNumber": 158326943359269,"integrationGroupId": 13500,"active": true,"integrationProperties":[{"propertyKey" :"job.event","propertyValue" :"Completed,Scheduled"}]}'158326943359269Business ID: Enter the Business ID for the SMB account.
13500Group ID: Enter the Group ID, which was returned when the Integration group was created.
trueActive: Enter true for enabling the integration.
Completed, Scheduled - event: Job events are configurable as per business needs. If the event is not configured, the default job event will be utilised.
NOTE: By default, the Job event will be Paid.
Integration Mapping (Enterprise Businesses)
Once the Integration Group is created, the next step is to create the Integration Mapping.
Copy this Curl Command
curl --location --request PUT 'https://common-services.Birdeye.com/integration/add/businessintegrationmapping' \--header 'content-type: application/json' \--data-raw '{"businessNumber": 158326943359268,"integrationGroupId": 13501,"active": true}'curl --location --request PUT 'https://common-services.Birdeye.com/integration/add/businessintegrationmapping' \--header 'content-type: application/json' \--data-raw '{"businessNumber": 158326943359267,"integrationGroupId": 13502,"active": true,"integrationProperties":[{"propertyKey" :"job.event","propertyValue" :"Completed,Paid"},]}'158326943359268, 158326943359267 - Business ID: Enter the ID for each location for the enterprise account.
13501 , 13502 - Group ID: Enter the Group ID, which was returned when the Integration group was created. Make sure that for every Housecall Pro account in the case of enterprise business, you have used a different Integration Group.
true - Active: Enter true for enabling the integration.
Completed, Paid - event: Job events are configurable as per business needs. In case the event is not configured, the default job event will be utilised.
NOTE: By default, the Job event will be Paid.
Job Webhook Events
Below table describes the different job events in Housecall Pro
Event Name | Event | Description |
Job created | created | Job created |
Job cancelled | cancelled | Job cancelled |
Job completed | completed | Job completed |
Job deleted | deleted | Job deleted |
Job on my way | on_may_way | Job on my way |
Job paid | paid | Job paid |
Job scheduled | scheduled | Job scheduled |
Job started | started | Job started |
This table describes the events with respect to Housecall Pro UI. We have to configure the following events under the column Events to be configured on Birdeyewith respect to the job status we see on UI.
There are certain events which are not present on UI, but we still receive those events. So businesses can configure those events as well.
Event to be configured on Birdeye | UI |
created |
Scheduled
Unscheduled
|
canceled |
|
completed | Done |
deleted |
|
on_my_way |
|
paid |
|
scheduled | Scheduled |
started | In Progress |
Restriction Reason
Restriction reason is used to identify the contacts which 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 HouseCall Pro are:
Either Phone or Email should be valid for the creation of a customer. Email: null, Phone: null.
Integration is beta
Description
Either Phone or Email should be valid for the creation of a customer. Email: null, Phone: null.
Integration is beta.
Troubleshooting Steps
Either Phone or Email should be valid for the creation of a customer. Email: null, Phone: null.
Check the email address and phone number.Integration is beta.
Please look up the key beta in kibana to know whether the integration is beta or not.