@xapp/stentor-service-servicetitan

Implementation of CrmService for Service Titan

Required Environment Variables

ST_API_Endpoint=api-integration.servicetitan.io ST_Auth_Endpoint=auth-integration.servicetitan.io/connect/token ST_Booking_Provider=[from the customer] ST_Tenant=[From the Customer] ST_Client_Id=[from the customer] ST_Client_Secret=[from the customer] ST_Application_Key=[name of XAPP App on Service Titan] GOOGLE_PLACES_KEY=[For Full Address. Service Titan requires a full address with all elements]

Documentation

• Service Titan Documentation
• Setup Notes

Onboarding a customer

To wire up a new ServiceTitan customer in stentor-api you need, in addition to their credentials, three IDs that must be selected from the customer's tenant: defaultBusinessUnitId, defaultJobTypeId, defaultCampaignId. These are not credentials — you have to list what exists in the tenant and pick the defaults.

1. List the IDs. Run the helper script (zero dependencies, credentials are kept in memory only — nothing is written to disk):

yarn st:list-ids
# or: node scripts/list-servicetitan-ids.js

It prompts for the environment, tenant id, ST App Key, client id, and client secret (masked), then prints every Job Type, Campaign, and Business Unit with its id.

2. Add the integration via the addServiceTitanIntegration mutation in stentor-api, supplying the credentials plus the three ids you chose.

⚠️ Environment must match everywhere (the #1 onboarding failure)

ServiceTitan has two isolated environments — production (api.servicetitan.io / auth.servicetitan.io) and integration/sandbox (api-integration.servicetitan.io / auth-integration.servicetitan.io). Credentials and the ST App Key are issued per environment and are not interchangeable. Every value must be from the same environment:

| Value | Production | | -------------------------------------- | ------------------------------------ | | apiEndpoint | api.servicetitan.io | | authEndpoint | auth.servicetitan.io/connect/token | | client id / secret, tenant, ST App Key | the customer's production values |

(Use the -integration hosts and the customer's integration credentials for sandbox.)

If the credentials are for one environment but the authEndpoint points at the other, authentication fails. In stentor-api this currently surfaces as OAuth Authentication failed (401: {"error":"invalid_client"}) from OAuthAuthenticationService. invalid_client almost always means an environment / app-key mismatch — confirm the endpoints match the credentials' environment. A quick way to prove which environment a set of credentials belongs to is to run yarn st:list-ids against each environment; the one that returns data is the correct one.