Configure ServiceTitan Integration

1. Navigate to the settings tab within ServiceTitan by clicking the icon in the top right hand corner.
2. On the left hand side, expand the "Integrations" section and then select "API Application Access".
3. Take note of the "Tenant ID" and send that over to support@clearpathgps.com in an email.
   Note: Step 3 cannot be completed until a ClearPathGPS Support Representative has acknowledged we received your Tenant ID.
   
   
4. Next, go to Settings -> Integrations -> GPS
   
5. If there is already a GPS Provider listed as "ClearPathGPS" move onto Step 2, otherwise click Add at the top, and select "ClearPathGPS" for the Name, leave everything else blank, then click Save. You will come back and edit this later in Step 5.
   
6. You can now move onto Step 2.

1. Start by creating a group within your ClearPathGPS account called "ServiceTitan Vehicles". Steps on creating groups can be found here.
2. Add the tracking devices that you want to integrate with ServiceTitan to this group.
   Any devices ("CP#s") you have assigned to technicians within ServiceTitan must be in this group, see Step 5 for details on assigning technicians and tracking devices.
   
   
3. Next, you need to make a 'Custom Alert' by navigating to Alerts in your ClearPathGPS account.
   If you're working with a ClearPathGPS Support representative, they may have already setup this alert within your account, if so, move on to Step 3.
   
   
4. Select 'Create Alert' in the top right hand corner and scroll to the bottom until you see 'Custom Alert' 
   Note: If you are migrating from ServiceTitan's V1 to V2 API, this Alert is likely already created for you and just needs to be updated, not newly created- jump down to number 6. below where you updated the Notify - Email Message ("Enter Email Message").
   
   
5. Configure the Alert exactly as detailed below, starting with 'Alert Details':
   1. Alert Name: x-api-servicetitan
   2. Applies To: Group - ServiceTitan Vehicles
   3. Status Code: All Codes
   4. Cron Option: No
   5. Rule Selector: (true)
      
   6. Minimum Interval: Leave all fields (days, hours, minutes) on the default 0
   7. Trigger Action - Email: Uncheck this box
   8. Trigger Action - Queue: Check this box
      
      
      
6. Click 'Next' to go to the 'Notify' page and do the following:
   
   1. Notify - via Email: Leave this field blank
   2. Notify - Email Message ("Enter Email Subject"): Leave this field blank
   3. Notify - Email Message ("Enter Email Message"): Copy and paste everything in the block below 

      {
      "tenant_id":"ADD TENANT ID HERE", 
      "client_id":"ADD CLIENT ID HERE",
      "client_secret":"ADD CLIENT SECRET HERE",
      "ST-App-Key":"ClearPathGPS TO PROVIDE",
      "timestamp":"${timestamp}",
      "statusCode":"${statusCode}",
      "status":"${status}",
      "lat":"${latitude}",
      "lon":"${longitude}"
      }

   4. Notify - via Text: Leave this field blank
   5. Notify - Text Message: Leave this field blank
      
7. Click 'Next' to go to the 'Finalize' page:
   1. At the top of this page (you may need to scroll up), untoggle the 'Active' button, you will come back and activate this later on.
   2. Click 'Save' and move on to Step 3.
      

Note: This step cannot be completed until a ClearPathGPS support representative has confirmed your Tenant ID has been added on our end, detailed in Step 1.

1. Within ServiceTitan, navigate to Settings -> Integrations -> API Application Access
2. Select "Connect New App"
   
3. Select ClearPathGPS Integration and click Connect.
   
4. Scroll down on the page and do the following:
   1. For Restriction by "booking_provider" for Bookings select "No restriction"
   2. For Restriction by "gps_provider" for GPS Pings select "ClearPathGPS (gps_provider = ClearPathGPS)
   3. For Restriction "report_category" for Reports within the category select "No restriction"
5. Then click "Allow Access"
   
   
6. The page will reload and display the Tenant ID, Client ID and Client Secret. Keep this page or browser tab open.
   Note: the Client Secret will only be visible once (below where it says 'Generate' in the screen shot below, if you navigate off the page without copying you will need to generate a new Client Secret.
   
   
   
7. Open a new tab so that you still have access to your Tenant ID, Client ID and most importantly, Client Secret; navigate back to your ClearPathGPS account in the new tab and move onto Step 4.

1. Go to the Alerts page in ClearPathGPS and edit the x-api-servicetitan alert created in Step 2.
2. On the 'Notify' page, you will now need to edit the Notify - Email Message ("Enter Email Message"): field where  a JSON payload was added earlier.
3. In this field, copy over your Tenant ID, Client ID and Client Secret from ServiceTitan by removing the ADD CLIENT ID HERE parts. These IDs/Secrets must be enclosed by the quotation marks.
   
   
   
4. Click 'Next', until you get the finalize page, scroll the top and toggle the alert to be Active.
   
   
   
5. Data is now flowing over to ServiceTitan!

1. Within ServiceTitan navigate to Settings -> Integrations -> GPS
2. Click "Edit" for the "ClearPathGPS" provider
   
   
   
3. Click the "Devices" tab
4. Add and assign devices that are in your "ServiceTitan Vehicles" group in ClearPathGPS using the CP# and assign them to your technicians based on the vehicle they drive.
5. Click Save when complete
   
   
   
   
6. To verify data is flowing over, select the Pings tab at the top of this page. This page will show the last time data was received for a specific CP#-Technician pairing.
   Note: A "Recent ping history" will only show if vehicles are currently moving; if this is not the case, the next time an assigned device registers a GPS event then the table will update. A 'ping' corresponds with a location update on the ServiceTitan Dispatch map.
   
   
   
7. You have now configured the ClearPathGPS -> ServiceTitan Integration!