ServiceTitan Integration

What Hatch's ServiceTitan integration is, how it works, and where to begin.

Table of Contents

There's a lot to navigate here! If you're looking for an answer to something specific, this table of contents will take you where you need to go. 

• What does the ServiceTitan integration do?
• How do you set up the integration?
  • Requirements
  • Setup Steps
  • Upgrading the App
  • Configuration Options
  • Best Practices
• When does Hatch sync data to/from ServiceTitan?
• How is ServiceTitan data stored in Hatch?
  • Opportunity Models
  • Opportunity Creation & Update

• What ServiceTitan data is available in Hatch?
  • Resource Selection
  • Available Resource Fields
• What are the limitations of the integration?
• Recommended Targeting for Audiences

---

What does the ServiceTitan integration do?

Hatch offers a native integration with ServiceTitan that you can activate within the App Marketplace (located in your Hatch workspace). This integration syncs contact data from ServiceTitan to Hatch, and can also sync Hatch events to ServiceTitan.

While active, the ServiceTitan integration will sync new and updated ServiceTitan data every 15 minutes. It will also sync Hatch events back to ServiceTitan as soon as they occur (if you have enabled this feature).

To get started, open the App Marketplace in your Hatch workspace and follow the setup instructions below.

---

How do you set up the integration?

Requirements

You will need the following to set up the integration:

• Hatch account with manager privileges
• ServiceTitan account with admin privileges on your tenant
  • This account must be able to access the ServiceTitan My Apps developer page (https://developer.servicetitan.io/custom/my-apps/)

Setup Steps

Before you begin, consider reviewing ServiceTitan's documentation around creating apps and managing client IDs and secrets. However, all of the necessary information is included in the instructions below.

Additionally, the Hatch integration requires specific API scopes (listed below). These provide Hatch with the necessary permissions to read and update data in your ServiceTitan tenant. The scopes below are only the bare minimum required by our integration.

The following is the set of steps required to activate the integration:

1. In Hatch, open the App Marketplace.
2. Under the CRMs tab, click the ServiceTitan Connect button.
3. Proceed through the setup until you reach the connection configuration screen.
4. Open the login page for ServiceTitan’s My Apps tool at https://developer.servicetitan.io/signin.
5. Click Login as Production Environment User and log in using your ServiceTitan credentials.
6. Review and accept ServiceTitan’s API terms of use (if prompted).
7. Click the New App button in the top right.
8. For both Application Name and Organization, enter: Hatch
9. For Homepage, enter: https://www.usehatchapp.com
10. You should see your tenant ID pre-populated under Tenant(s).
    1. If you only have one ServiceTitan tenant (or are unfamiliar with this concept), do not modify this section.
    2. If you have multiple ServiceTitan tenants, add the IDs for any tenants that you want to grant access to Hatch. However, we recommend configuring one tenant per app.
11. Under API Scopes, click All next to each section so that every box on the page is checked.
    1. Optionally — if you do not want to provide all scopes — you can only select the scopes that are required by the integration:
       1. The following Read scopes are required:
          1. Accounting: Payment Types, Tax Zones
          2. CRM: Booking Provider Tags, Bookings, Customers, Leads, Locations, Tags
          3. Dispatch: Appointment Assignments, Non-Job Appointments, Zones
          4. Job Planning and Management: Appointments, Job Cancel Reasons, Job Hold Reasons, Jobs, Job Types
          5. Memberships: Customer Memberships, Membership Types, Recurring Service Events, Recurring Services, Recurring Service Types
          6. Marketing: Campaigns, Campaign Categories
          7. Sales & Estimates: Estimates
          8. Settings: Business Units, Employees, Tag Types, Technicians, User Roles
       2. The following Read scopes are optional, only necessary if you choose to configure your integration to pull the Invoices with your Job opps: 
          1. Accounting: Invoices, Invoice Items
       3. The following Write scopes are required:
          1. CRM: Customers, Leads, Locations
          2. Job Planning and Management: Jobs
12. Click Create App at the bottom.
13. Click Edit next to the new app that is now listed.
14. Copy/paste the Application Key into the associated field on the Hatch setup screen.
15. You may now close the My Apps tool.
16. Open the ServiceTitan instance that you want to connect to your Hatch workspace.
17. Navigate to Settings → Integrations → API Application Access.
18. Click the Connect New App button, accept the terms and conditions (if prompted), and select Hatch from the list of apps.
19. With Hatch selected, click Connect.
20. Scroll to the bottom of the screen that appears.
21. For any select boxes listed, choose No restriction if it is available (if not, select the first available option).
22. Click Allow Access.
23. On the resulting Application Details screen, copy/paste the Tenant ID and the Client ID into the associated fields on the Hatch setup screen.
24. Click the Generate button next to Client Secret and then click Yes, Continue to generate the secret.
25. Copy/paste the Client Secret into the associated field on the Hatch setup screen.
26. You may now close any open ServiceTitan pages. All of the remaining steps are completed in Hatch.
27. In the Hatch setup screen, select which opportunity models you would like to enable.
    1. We recommend only enabling one opportunity model per integration.
28. Complete any remaining setup steps, connecting Hatch and activating your integration.
    1. Once complete, the integration will begin syncing your last 90 days of data.

How to upgrade the ServiceTitan app

If an application is configured with incorrect scopes or an upgrade to the scopes is required to access new information, you will need to first edit the application in the ServiceTitan dev portal, and then upgrade the connected app within ServiceTitan.

Edit your Hatch app:

1.  Visit the Developer Portal  "My Apps" section: https://developer.servicetitan.io/custom/my-apps/
2. Click "Edit" on the Hatch app you previously setup
3. Click on the “Change API Scopes” button:
4. Add your missing scopes and "save"
5. You’ll be redirected to the my apps list again, select the Hatch App once again and you should see the API scopes section. Every time you perform a change in the scopes, Service Titan generates a new API scopes version. It should automatically select the latest scope change in the drop-down:

Upgrade the connected Hatch app to the new version:

1. Login to your Service Titan account
2. Manage API Application Access page: https://go.servicetitan.com/#/Settings/Api-Apps
3. In the Hatch App, you should see a message informing about the scope update.
   
4. Click the "upgrade version" button and confirm.

Configuration Options

These options can be set during the integration setup:

Choose the ServiceTitan data that syncs to Hatch:

• Choose which opportunity models the integration should sync from ServiceTitan, and subsequently which data objects to include with the model. We will go into further detail regarding the data objects further down in this article in the section "What ServiceTitan data is available in Hatch?"
• Configure a filter for placeholder emails: if your org utilizes placeholder emails within your ServiceTitan, this filter will prevent contacts from merging in Hatch based on the shared information

Push Events and Communications:

• Choose where outgoing campaign messages should sync — if/where Hatch should create ServiceTitan notes for outgoing campaign message events
• Sync message content for outgoing campaign messages — if the message content should be included in notes created for outgoing campaign message events
• Choose where incoming messages & calls should sync — if/where Hatch should create ServiceTitan notes for incoming messages & calls
• Sync message content for incoming messages & calls — if the message content should be included in notes created for incoming messages & calls
• Choose where outgoing manual messages & calls should sync — if/where Hatch should create ServiceTitan notes for outgoing manual messages & calls
• Sync message content for outgoing manual messages & calls — if the message content should be included in notes created for outgoing manual messages & calls

Configuration Best Practices

• We recommend using one ServiceTitan app per tenant, creating additional app instances in My Apps for any additional tenants (following the steps here). This is due to ServiceTitan API rate limits. As of August 2023, configured apps may not exceed 60 requests per second. Therefore, if too many tenants are using the same app (and, by extension, sending too much data), the API will begin blocking requests and the Hatch integration will not work as expected. You can read more about ServiceTitan API limitations here.
• We recommend enabling only one opportunity model in your integration configuration. If you enable multiple, be aware that you may see multiple ServiceTitan opportunities on the same contact (e.g. a job and a membership on the same person's Hatch contact). If you need multiple types of ServiceTitan data, we recommend configuring separate integration instances across multiple Hatch departments. Your CS representative can assist with this configuration.
• We recommend utilizing the object selector feature in the data model configuration to select only the information necessary for your campaigns. While the integration can sync a wide range of information that might seem relevant, it can also make it more difficult to pick out the pieces that are truly important and useable with your campaign strategies. Now you can customize what you want to sync. Read more about this feature here.

---

When does Hatch sync data to/from ServiceTitan?

ServiceTitan → Hatch

ServiceTitan data can be sync’d to Hatch in the following scenarios. These options are configured during the integration setup. 

• If a Job record is created or updated in ServiceTitan, Hatch syncs the Job record along with any associated data (see below for specific fields)
• If a Membership record is created or updated in ServiceTitan, Hatch syncs the Membership record along with any associated data (see below for specific fields)

Hatch → ServiceTitan

Hatch events and/or communications can be sync’d to ServiceTitan in the following scenarios. These options are configured during the integration setup. 

• When a Hatch campaign sends a text/email/voicemail to a contact, Hatch creates a Note for the event on the associated Job, Customer, or Location
• When a contact calls or sends a text/email/voicemail to a Hatch workspace, Hatch creates a Note for the event on the associated Job, Customer, or Location
• When a Hatch user calls or sends a text/email to a contact, Hatch creates a Note for the event on the associated Job, Customer, or Location
• When events occur within a Hatch campaign, Hatch creates a Note for the event on the associated Job, Customer, or Location
  • A contact is launched (added) to a Hatch campaign
  • A contact is sent the first message of a Hatch campaign
  • A contact is removed from a Hatch campaign before it has ended
  • A contact completed a Hatch campaign

Below is an example of push communications and push events sent to ServiceTitan Job Notes:

---

How is ServiceTitan data stored in Hatch?

Opportunity Models

There are two types of Hatch opportunities that the ServiceTitan integration creates:

• Job Opportunity — Created from ServiceTitan Job records, this is the primary opportunity type in our ServiceTitan integration. Additional related data is also included (see below).
• Membership Opportunity — These opportunities are created from ServiceTitan Membership records. Additional related data is also included (see below).

Opportunity Creation & Update

The integration will replace an existing Hatch opportunity when:

• The sync’d Hatch External ID matches the existing opportunity’s Hatch External ID (see below for how the External ID is mapped)

The integration will create an additional (new) Hatch opportunity when:

• The sync’d Hatch External ID does not match the existing opportunity’s Hatch External ID (see below for how the External ID is mapped)

---

What ServiceTitan data is available in Hatch?

Selecting Object Resources

The latest version of our integration allows you to select the resources that are most relevant to your campaigns, instead of syncing all possible data by default. This customizability allows you (and your integration) to operate more efficiently. 

Both opportunity models have a certain set of required objects that are needed in order for some aspect of Hatch to function. The additional resources are optional. We have defaulted the configuration with the most commonly used optional resources, but users can select or deselect as needed.

What resources will I need? 

Good question! We can generalize some use-cases for the optional resources that might give you a better idea.

Estimates - This will be necessary in order to utilize a sales follow-up strategy. 

Appointments - For the most part, the common use cases can be covered using a combination of the Jobs and Estimates resources. The Appointments resource will be primarily useful if using an appointment confirmation or canceled appointments campaign.

Appointment Assignments - Can only be enabled if Appointments is selected. Primarily useful if you are looking to include technician information in one of your campaigns.

Cancel Reasons - Primarily useful if running a canceled appointments campaign (to get these leads back on the schedule).

Tag Types - May be useful for segmenting audiences based on existing ServiceTitan segments

Campaigns - May be useful for segmenting audiences based on existing ServiceTitan segments

Zones - May be useful for location-based targeting, if for some reason your Business Units don't provide enough specificity. 

Employees & Technicians - This is only necessary if you are looking to utilize the estimate or membership Sold By information in one of your campaigns. 

Invoices - This will be necessary in order to utilize an accounts receivable related campaign. Also useful for targeting contacts for reviews/referrals once work is completed. 

Available Resource Fields

In the this section, we will provide a list of the available fields and what object resources those are found on in order to help guide your integration configuration. These fields will become the "details" fields of the Hatch Opportunity. 

 

The following fields are available in the Job opportunity details:

 

The following fields are available in the Membership opportunity details:

Standard Field Mapping

Hatch standard fields are mapped from ServiceTitan detail fields as detailed below.

Job Opportunity

In Membership opportunities, the following Hatch standard fields are mapped from ServiceTitan detail fields:

---

What are the limitations of the integration?

• The ServiceTitan API does not provide information related to the Job's "Opportunity", so Hatch is unable to target audiences based on the follow-up date or status.

---

Recommended targeting for audiences

Here's what we've found works best to accomplish common use cases. Feel free to use these as a starting point for your own campaigns, but it's always wise to evaluate what targeting strategy works best with your internal processes. 

Speed to Lead (Removal Rules) 

The goal in mind here is to remove contacts from the STL campaign when a job (appointment) has been scheduled in ServiceTitan. There are a couple ways to achieve this:

Rehash (Sales Follow-up)

The goal here is to follow up on recently created estimates that have not been sold or dismissed.