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 Birdeye with ServiceTitan
User Manual - SUPPORT ARTICLE
ServiceTitan is a Field Service Management (FSM) software that helps businesses enhance business servicing through an easily managed automated dashboard. It is generally used by businesses that provide home service management. ServiceTitan helps its clients to keep a keen eye on their business and constantly improve sales, streamline operations, and provide their customers with an exceptional experience over time.
Table of Contents
Trigger details
Enterprise ID
Business ID for single-location business
Login
Manage Triggers
Manage Properties
Manage Locations
Create Integration Group - Multi-Location Account (Curl Command)
Client authorisation for ServiceTitan
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 ServiceTitan:
Trigger Display Name | Trigger Name/Value | Trigger Description |
ServiceTitan Completed Jobs Trigger | Completed Job | This trigger is used to fetch all completed service jobs from ServiceTitan based on the date specified |
Details required from the Birdeye client
Trigger details
Details required from the 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 ServiceTitan 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.
ServiceTitan API key: It is required for the ServiceTitan V1 API integration setup.
Data fetch logic: It is required and applicable to only multi-location businesses for specifying location-tag or business-unit names for filtering completed ServiceTitan jobs. For single location accounts, this field should remain unselected.
Service Titan Custom Fields: ServiceTitan custom field names to be added in additional params (multiple values as comma-separated), information regarding the creation of custom fields is provided here.
Client on ServiceTitan V2 API: It is used to select between ServiceTitan deprecated (V1) and V2 API. It is recommended that V2 be used.
ServiceTitan Tenant ID, Client ID, Client secret: Required for ServiceTitan V2 API integration setup and is obtained from a client with a ServiceTitan admin role in Settings > Integration > API Application Access All information and its relevant access information are provided here.
ServiceTitan Appointment Status: It will fetch jobs for a particular configured appointment status for which the review request will be sent.
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 the status of Integration (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.
Business Unit Name: Add the ‘Business unit’ name(s) as mentioned by the client; this can be a comma-separated list of names, and click on ‘OK’.
Location Tag Name: Add the ‘Location tag’ name(s) as mentioned by the client; this can be a comma-separated list of names, and click on ‘OK’.
IMPORTANT: How to create tags and business units are mentioned here.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.
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.
Curl Command
Before integrating ServiceTitan 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 - Single Location Account (Curl Command)
Copy this 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" :152088024342873,
"integrationSourceId" : 9,"integrationGroupTriggers":[{"triggerId":9,"triggerTypeId":1}], "integrationGroupProperties" :[{ "propertyKey" :"servicetitan.is.new.version", "propertyValue" : "true"},{ "propertyKey" :"servicetitan.tenant.id", "propertyValue" : "987612579"},{ "propertyKey" :"servicetitan.client.id", "propertyValue" : "cid.r5t2atjj1yjzdnroopsnn8yl9"},{ "propertyKey" :"servicetitan.client.secret","propertyValue":"cs5.hf8mtzva5ev319ejyr2a72i4elkwq2x8ucxqcbh7cj16tmmbr7", "isSecure":true} ] }'152088024342873 - Business ID - This is Enterprise ID for a multi-location account and Business ID for a single location SMB account
9 - 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 ServiceTitan. Identify the trigger Id(s) and insert (use commas) in case of multiple trigger IDs.
servicetitan.is.new.version - Client on ServiceTitan V2 API - This will be true for setting up the integration with ServiceTitan V2 API. And false for setting up integration with deprecated (V1) API.
servicetitan.tenant.id - ServiceTitan Tenant ID - Required for ServiceTitan integration V2 setup. This can be found in ServiceTitan (logged in with admin role) Settings > Integration > API Application Access section.
servicetitan.client.id - ServiceTitan Client ID - Required for ServiceTitan V2 integration setup. This can be found in ServiceTitan (logged in with admin role and connected to Birdeye app) Settings > Integration > API Application Access section.
servicetitan.client.secret - ServiceTitan Client Secret - Required for ServiceTitan integration V2 setup. This can be generated in ServiceTitan (logged in with admin role and connected to Birdeye app) Settings > Integration > API Application Access section.
NOTE: We will get the group ID once we run the first curl (Integration Group) and make a note of the group ID as that will be required while we will be doing the integration mapping.
Create Integration Group - Multi Location Account (Curl Command)
Copy this 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" :152088024342873,
"integrationSourceId" : 9,"integrationGroupTriggers":[{"triggerId":9,"triggerTypeId":1}], "integrationGroupProperties" :[{ "propertyKey" :"servicetitan.is.new.version", "propertyValue" : "true"},{ "propertyKey" :"servicetitan.tenant.id", "propertyValue" : "987612579"},{ "propertyKey" :"servicetitan.client.id", "propertyValue" : "cid.r5t2atjj1yjzdnroopsnn8yl9"},{ "propertyKey" :"servicetitan.client.secret","propertyValue":"cs5.hf8mtzva5ev319ejyr2a72i4elkwq2x8ucxqcbh7cj16tmmbr7", "isSecure":true},{"propertyKey":"multi.location.data.fetch.logic","propertyValue": "tag_name"} ] }'152088024342873 - Business ID - This is Enterprise ID for multi-location account and Business ID for a single location SMB account
9 - 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 ServiceTitan. Identify the trigger ID(s) and insert (use commas) in case of multiple trigger IDs.
servicetitan.is.new.version - Client on ServiceTitan V2 API - This will be true for setting up the integration with ServiceTitan V2 API. And false for setting up integration with deprecated (V1) API.
servicetitan.tenant.id - ServiceTitan Tenant ID - Required for ServiceTitan V2 integration setup. This can be found in ServiceTitan (logged in with admin role) Settings > Integration > API Application Access section.
servicetitan.client.id - ServiceTitan Client ID - Required for ServiceTitan V2 integration setup. This can be found in ServiceTitan (logged in with admin role and connected to Birdeye app) Settings > Integration > API Application Access section.
servicetitan.client.secret - ServiceTitan Client Secret - Required for ServiceTitan V2 integration setup. This can be generated in ServiceTitan (logged in with admin role and connected to Birdeye app) Settings > Integration > API Application Access section.
tag_name - Data fetch logic - There are 2 types of logic supported - 1. Based on Tag name 2. Based on Business Unit. If the client is using a tag name for multi-location, then the value will be “tag_name”, and if a client is using a business unit, then the value will be “business_unit”.
Fetch information for all the triggers available for ServiceTitan Online (Curl Command)
Copy this Curl Command
curl -X GET https://common-services.Birdeye.com/integration/trigger/integrationtriggers/sourceid/9 -H 'cache-control: no-cache' -H 'content-type: application/json'
Sample response: A sample response like this (see below) will 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. (Currently, we only support one trigger for ServiceTitan)
[
{
"id": 9,
"integrationSourceId": 9,
"triggerService": "serviceTitanCompletedJobsTriggerService",
"displayName": "ServiceTitan Completed Jobs Trigger",
"description": "This trigger is used to fetch all completed service jobs from ServiceTitan based upon the date specified",
"active": true,
"integrationSourceName": "ServiceTitan",
"integrationTriggerType":[{"id":1,"name":"JOB"}]
}
]
9 - Trigger IDFind business integration group details (Curl Command)
Copy this Curl Command
curl -X GET https://common-services.Birdeye.com/integration/businessintegrationgroup/152088024342873 -H 'Cache-Control: no-cache'
152088024342873 - Business ID: Enter the Business ID here to get the integration group details for the business.
Sample Response:
[
{
"groupId": 36,
"integrationSourceType": {
"id": 9,
"integrationSource": "SERVICETITAN",
"sourceCategory": "Home Services",
"integrationType": "Birdeye API",
"oauthEnabled": false
},
"integrationGroupTriggers": [
{
"triggerId": 9,
"triggerTypeId": 1,
"actionIds": [
1
]
}
]
}
]
36 - Group ID: A group ID will be returned in the sample response with the details of the existing triggers for the business.Update Trigger Information (use only if business wants a change) (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": 36,"integrationGroupTriggers":[{"triggerId":9,"triggerTypeId":1}]}'replaceTriggers=true - To replace existing trigger(s), enter the value for replaceTriggers as To add a new trigger(s) to the existing list, the value for replaceTriggers should be false
36 - The Group ID that was returned in the previous step will be entered here.
9 - Enter the Trigger ID(s) that need to be added or updated to the integration.
Integration Location Mapping
This configuration is developed to create the actual business integration mapping. Each business integration mapping corresponds to an individual business location.
Integration Location Mapping (SMB Businesses)
Copy this 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": 152088024342873, "integrationGroupId" : 36, "active": true }'152088024342873 - Business ID- Enter the Business ID here.
36 - Group ID- Enter the Group ID that was returned when the Integration group was created.
Integration Mapping (Enterprise Business)
Copy this 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": 152088024342873, "integrationGroupId" : 36, "active": true,"integrationProperties":[{"propertyKey" : "location.tag.name","propertyValue": "palo alto,sacramento"}]}'152088024342873-Business ID- Enter the Business ID here.
36-Group ID- Enter the Group ID which was returned when the Integration group was created.
palo alto,sacramento - Location Tag/Business Unit Field Name: Add this property used by the client for location tag/business unit field. It can be a comma-separated list of names corresponding to each Birdeye location (will be provided by the client).
location.tag.name - Field Name Based on logic: If the client has selected tag name-based approach, then this value will be “location.tag.name”, and If the client has selected business unit-based approach, then this value will be “business.unit.name”
Client authorisation for ServiceTitan
The new process for getting client authorisation for ServiceTitan is as follows:
First login to a client's Servicetitan account. Clients with Administrator roles must share their Tenant ID via Settings > Integration > API Application Access. They need to share this tenant ID with Birdeye integration support (customers can email it).
Birdeye integration support needs to add the received Client Tenant ID to the ServiceTitan developer portal in the Birdeye production application created in the https://developer.servicetitan.io/signin/. Support staff can log in via creds provided on the credentials sheet.
After the integration support has successfully added the received client Tenant ID and saved the modified Birdeye app, the client can now find the Birdeye application in the Settings > Integration > API Application Access section after clicking on ‘Connect New App’ clicked. The client needs to connect to the Birdeye app and click the Allow access button in the following dialog.
After successfully connecting to the Birdeye application, the client will see its Client ID in the application details section for the integration. The client must generate a Client secret and share the Client ID and Client secret with integration support.
The Birdeye integration support, when setting up the integration, needs to input the received Tenant ID, Client ID and Client Secret from the client as dashboard property values. You must select Client on Service Titan V2 API as true to set the integration on the new V2 API.
Multi-location support
There are two methods by which multiple locations can be set up for a ServiceTitan account:
Creating and using ‘tags’
In the case of a multi-location account, you will need to create location 'Tags' within your ServiceTitan account to ensure service jobs are mapped to the right business location. To create a location tag, click on the 'Gear' icon on the top right corner of your ServiceTitan dashboard.
NOTE: During the initial setup call, inform the Birdeye support team about the 'Location Tag' names corresponding to different business locations within your Birdeye account.
Now, click on the 'Tag Types' icon which appears under the 'Operations' header on the left navigation rail.
On the 'Tag Types' page, click on the 'Add' button to add a new location tag.
Enter the name of the business location in the 'Name' field and click on the 'Save' button at the bottom.
The newly created location tag will now appear under the 'Tag Types' page with the status 'Active.’
NOTE: You can create multiple location tags corresponding to all your business locations.
Once you are in the process of creating a job, select the name of the location corresponding to the job from under the 'Tags' header.
After you have selected a location, click on the 'Book Job' button.
Creating and using ‘business units’
For a multi-location account, you can also create 'Business Units' within your ServiceTitan account to map jobs to the right location. To create a 'Business Unit', click on the 'Gear' icon on the top right corner of your ServiceTitan dashboard.
NOTE: During the initial setup call, inform the Birdeye support team about the 'Business Unit' names corresponding to different business locations within your Birdeye account.
Now, click on the 'Business Units' icon, which appears under the 'Operations' header on the left navigation rail. On the new page, click on the 'Add' button on the top.
Now, enter the 'Name', 'Official Name', 'Email' and 'Phone Number' in the given fields. Once you have entered all the details, click on the 'Save' button at the bottom.
Once you are in the process of creating a job, select the name of the 'Business Unit' corresponding to the job from under the Business Unit header. After you have selected a business unit, click on the 'Book Job' button.
Re-Authorise Business
Sometimes, it happens the credentials entered were wrong during setup or are expired, so we receive 401 Unauthorized Error while running the Integration, and as a result, Integration will be marked unauthorized. It will not run until the credentials are corrected, and the business is authorized again, which involves the steps given in the below document.
Important Instructions for Email opt-in/ opt-out.
If we need to opt-out from email, there is one field, ‘DO NOT EMAIL’ we need to check that field. The user will be opting out of email.
How to request email opt-out
Click on the job created.
Under Service Location, click the customer name.
Click the customer name again under the Location.
Click on the pencil icon to edit the field.
Check-in box against the ‘Do not mail’ field for opting out of the email.
Click on the ‘Save’ button to save your preferences.
How to request email opt-in
Repeat the above steps from steps 1 to 4. If you need to opt-in for email, do not check the field ‘Do not Mail.’
NOTE: We do not have an option to opt-out of SMS. By default, it is always true.
Creation of the Custom fields
To create the custom fields, follow the steps below.
Go to the ServiceTitan dashboard. Click on the ‘Settings’ icon.
Click on the ‘Operations’ tab on the left panel.
Navigate to custom fields, and you can view already created custom fields. To create a new field, click on the ‘Add’ button.
Enter the name of the field. Check the box against the option where you want it to appear, for example, Job Record. You can select the type of custom field from the drop-down button.
After providing the details, click the ‘Save’ button.
The custom field will be created and appear on the screen as shown in the image below.
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 ServiceTitan are:
Job detail status is not completed
The customer is inactive
Integration is beta
Description
Job detail status is not completed and hence restricted.
The customer present is not active.
The integration setup is currently set to beta.