ServiceTitan Integration

Documentation Index

Fetch the complete documentation index at: https://docs.usehatchapp.com/llms.txt

Use this file to discover all available pages before exploring further.

​

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

​

Setup Steps

Hatch now has an official ServiceTitan App! All users are required to utilize our official ServiceTitan application over a personal application (as per their API terms of use). The Hatch app automatically provides us with the permissions to read or update data in your ServiceTitan tenant. The scopes requested by our app cover all of the possible use cases in Hatch. For reference, the scopes are listed below in the FAQ section. The following is the set of steps required to activate the integration:

1. This first step is manual and will need to be completed in order to proceed with the rest of the setup steps. In order to make the Hatch app available for activation within your ServiceTitan instance, we will need to add your ServiceTitan Tenant ID to our ServiceTItan application. Please send your Tenant ID over to your onboarding representative to complete.
   1. _If you’re unsure where to find your Tenant ID, you can find it in ServiceTitan via Settings → Integrations → API Application Access
2. Once the Hatch app has been activated for your tenant, you may proceed with setup. In Hatch, open the App Marketplace.
3. Under the CRMs filter, click the Connect button for ServiceTitan.
4. Proceed through the setup until you reach the connection configuration screen.
5. Open the ServiceTitan instance that you want to connect to your Hatch workspace and navigate to Settings → Integrations → API Application Access.
6. Click the Connect New App button, accept the terms and conditions (if prompted), and select Hatch from the list of apps.
7. With Hatch selected, click Connect.
8. Scroll to the bottom of the screen that appears.
9. In the restriction by booking provider option, choose No Restriction.
   1. This simply allows Hatch to post Bookings in ServiceTitan without restriction to a specific booking provider id.
10. Click Allow Access.
11. On the resulting Application Details screen, copy/paste the Tenant ID and the Client ID into the associated fields on the Hatch configuration screen.
12. Click the Generate button next to Client Secret and then click Yes, Continue to generate the secret.
13. Copy/paste the Client Secret into the associated field on the Hatch setup screen.
14. You may now close any open ServiceTitan pages. All of the remaining steps are completed in Hatch.
15. Enable the opportunity models you would like to sync with Hatch
    1. additionally select which related objects to include in the data model
16. Configure your push communications preferences.
17. Make sure to complete the full setup and click Finish in order to officially activate your Hatch integration.
    1. If successfully activated, 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. 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 utilizing the object selector feature in the data 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.

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

​

Hatch → ServiceTitan

Automatically Book Jobs Users of Hatch AI can benefit from our calendar integration to automatically book jobs on your schedule. Learn more about how our ServiceTitan scheduler bot in our dedicated calendar integration article. Sync Communications 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).
• Inbound Call Opportunity — These opportunities are created when a inbound call is completed in ServiceTitan.

​

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. Each opportunity model has 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. The resources available with a Job opportunity are:

• Estimates — Necessary in order to utilize a sales follow-up strategy.
• Appointments — Useful for appointment confirmation or canceled-appointment campaigns.
• Appointment Assignments — Can only be enabled if Appointments is selected. Useful if you want technician information in your campaigns.
• Cancel Reasons — Useful for canceled-appointments campaigns.
• Tag Types — Useful for segmenting audiences based on existing ServiceTitan tags.
• Campaigns — Useful for segmenting audiences based on existing ServiceTitan campaign attribution.
• Zones — Useful for location-based targeting.
• Employees & Technicians (Sold By) — Necessary if you need the estimate or membership Sold By information.
• Invoices — Necessary for accounts-receivable campaigns or post-completion review/referral targeting. The resources available with a Membership opportunity are:
• Recurring Services & Events — Aggregates the latest, next, and full list of recurring service events plus an unused-services count.
• Tag Types — Same as above, applied to the membership’s customer.
• Zones — Adds zone metadata to the membership’s location and recurring location.
• Employees & Technicians (Sold By) — Adds the membership’s soldBy info.
• Payment Type — Adds payment type metadata.

​

Available Resource Fields

The following fields are available in the Job opportunity details: The following fields are available in the Membership opportunity details: The following fields are available in the Inbound Call opportunity details:

​

Standard Field Mapping

Hatch standard fields are mapped from ServiceTitan detail fields as detailed below. Job Opportunity In Job opportunities, the following Hatch standard fields are mapped from ServiceTitan detail fields: Membership Opportunity In Membership opportunities, the following Hatch standard fields are mapped from ServiceTitan detail fields: Inbound Call Opportunity

​

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

We have a template library to help get you started on building audiences. These are 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:

​

FAQ