ServiceTitan Integration for Form Builder

Overview

The ServiceTitan integration allows your forms to automatically create customers and bookings in ServiceTitan when submitted. This powerful integration eliminates manual data entry and ensures all leads are immediately available in your ServiceTitan CRM with complete booking and customer information.

Prerequisites

Before setting up ServiceTitan integration, ensure you have:

1. Active ServiceTitan Account: A valid ServiceTitan subscription with API access
2. ServiceTitan API Credentials: Client ID, Client Secret, and API access configured
3. Connected Integration: ServiceTitan must be connected in your integrations settings
4. Required Permissions: Read and write access to customers, locations, and bookings in ServiceTitan
5. Business Categories: Properly configured business categories and booking types in ServiceTitan

Setup Instructions

1. Connect ServiceTitan Integration

1. Navigate to Integrations → ServiceTitan
2. Enter your ServiceTitan API credentials
3. Click Connect to ServiceTitan
4. Verify the connection shows as “Connected”
5. Configure business categories and booking types

2. Enable ServiceTitan for Forms

When creating or editing a form:

1. Expand the Integration Settings accordion
2. Toggle “Send Submissions to ServiceTitan” to ON
3. Configure field mappings (see Field Mapping section below)

Field Mapping

Required Fields

These fields must be mapped for ServiceTitan integration to work:

Field Type	ServiceTitan Mapping	Description
Text	customer_fname	Customer’s first name
Text	customer_lname	Customer’s last name
Text/Number	customer_phone	Customer’s phone number
Text	street	Street address
Text	city	City
Select	state	State
Text	zip	ZIP code

Optional Fields

Additional fields that can be mapped to enhance customer and booking data:

Field Type	ServiceTitan Mapping	Description
Email	customer_email	Customer’s email address
Text	country	Country (defaults to US)
Textarea	booking_reason	Reason for service request
Select	booking_type	Type of booking/service
Date	booking_date	Preferred service date
Select	booking_time	Preferred time slot
Radio	isFirstTimeClient	Whether customer is new
Select	customerType	Residential or Commercial

Setting Up Field Mappings

1. Add form fields using the form builder
2. For each field, expand the Advanced Options
3. Find the “ServiceTitan Key” dropdown
4. Select the appropriate ServiceTitan field mapping
5. Ensure all required mappings are configured

How It Works

Submission Process

When a form with ServiceTitan integration is submitted:

1. Validation: System validates all required ServiceTitan mappings are present
2. Data Preparation: Maps form fields to ServiceTitan customer and booking structure
3. Customer Creation: Creates customer record with location information
4. Booking Creation: Creates booking/job request associated with the customer
5. Response Handling: Processes ServiceTitan API response and logs results

Data Flow

Form Submission → Field Mapping → Customer & Location Creation → Booking Creation → ServiceTitan CRM

Address Handling

ServiceTitan requires complete address information:

• Street address is validated and formatted
• City, state, and ZIP are required for geocoding
• Locations are automatically created and linked to customers
• Invalid addresses are flagged and logged

API Integration Details

Authentication

The integration uses ServiceTitan’s OAuth 2.0 authentication:

• Client credentials are securely stored
• Access tokens are managed automatically
• API rate limits are respected
• Connection status is monitored continuously

ServiceTitan API Endpoints Used

• Customer Creation: /crm/v2/customers
• Location Management: /crm/v2/customers/{id}/locations
• Booking Creation: /bookings/v2/bookings
• Business Units: /settings/v2/business-units

Error Handling

The system includes comprehensive error handling:

• Invalid customer data is validated before submission
• API failures are logged with detailed error messages
• Duplicate customer handling based on phone number
• Booking conflicts are detected and reported
• Network timeouts are gracefully handled

Features

Advanced Capabilities

• Complete Customer Profiles: Full customer information with contact details
• Location Management: Automatic service location creation and management
• Booking Intelligence: Smart booking creation with preferred dates and times
• Business Category Mapping: Automatic categorization based on service type
• Customer Type Detection: Residential vs. Commercial customer classification

ZIP Code Validation

Optional ZIP code lookup feature:

• Real-time service area validation
• Prevents bookings outside service territories
• Provides immediate feedback to customers
• Configurable service area boundaries

Customer Lookup

Advanced customer lookup capabilities:

• Search existing customers by phone number
• Auto-populate customer information if found
• Prevent duplicate customer creation
• Link new bookings to existing customer records

Analytics Integration

Form submissions to ServiceTitan are tracked with:

• Lead source attribution
• Campaign tracking
• Conversion analytics
• ROI measurement
• Customer lifetime value tracking

Templates

Pre-built ServiceTitan Template

A comprehensive ServiceTitan form template is available with:

Step 1: Location Verification

• ZIP code lookup with service area validation
• Real-time territory verification

Step 2: Service Selection

• Service type dropdown
• Predefined service categories

Step 3: Service Description

• Detailed problem description
• Service urgency level

Step 4: Customer Information

• Complete contact information
• Customer lookup by phone
• Full address collection

Step 5: Customer Type

• New vs. returning customer
• Residential vs. commercial

Step 6: Scheduling

• Preferred service date
• Time slot selection
• Terms and conditions

Using the Template

1. Go to Form Builder → Create New Form
2. Select “ServiceTitan Scheduling Template”
3. Customize service types and categories
4. Configure ZIP code validation areas
5. All ServiceTitan mappings are pre-configured

Advanced Features

Service Area Management

• ZIP Code Validation: Real-time checking of service territories
• Territory Mapping: Visual service area configuration
• Custom Boundaries: Define specific service zones
• Exclusion Lists: Exclude specific areas or ZIP codes

Customer Intelligence

• Duplicate Prevention: Automatic detection of existing customers
• Data Enrichment: Enhance customer profiles with form data
• History Tracking: Link to existing service history
• Preference Management: Store customer preferences and notes

Booking Optimization

• Smart Scheduling: Intelligent time slot suggestions
• Capacity Management: Respect technician availability
• Priority Handling: Emergency vs. routine service classification
• Route Optimization: Consider geographic proximity for scheduling

Troubleshooting

Common Issues

“Missing required ServiceTitan mappings” Error

• Ensure all 7 required fields are mapped: customer_fname, customer_lname, customer_phone, street, city, state, zip
• Check that mapped fields are marked as required
• Verify field names match exactly

ServiceTitan API Connection Failed

• Check ServiceTitan integration connection status
• Verify API credentials are valid and active
• Ensure ServiceTitan account has API access enabled
• Check for expired authentication tokens

Customer Creation Failed

• Verify phone number format is correct (recommended: +1234567890)
• Check for special characters in customer data
• Ensure address information is complete and valid
• Verify ZIP code is within configured service area

Booking Creation Failed

• Verify customer was created successfully first
• Check booking date is in the future
• Ensure booking type is configured in ServiceTitan
• Verify business unit and category mappings

ZIP Code Lookup Issues

• Verify ZIP code service area configuration
• Check API endpoints for ZIP validation
• Ensure service territories are properly defined
• Test with known valid ZIP codes

Debug Information

Enable detailed logging by checking application logs for:

• 📤 Sending to ServiceTitan – Integration attempt started
• ✅ ServiceTitan API response received – Successful API call
• ❌ ServiceTitan API call failed – Failed API call with error details
• 🔍 ZIP lookup result – ZIP code validation results

Performance Monitoring

Monitor integration performance through:

• API response times
• Success/failure rates
• Customer creation statistics
• Booking completion rates
• Error frequency and types

Best Practices

Form Design

• Progressive Disclosure: Use multi-step forms for complex data collection
• Required Field Strategy: Mark all ServiceTitan-mapped fields as required
• ZIP Code First: Validate service area before collecting detailed information
• Customer Lookup: Implement phone-based customer lookup early in the form

Data Quality

• Phone Number Validation: Enforce proper phone number formatting
• Address Validation: Use address verification services
• Service Type Mapping: Align form options with ServiceTitan categories
• Date Constraints: Prevent past dates for booking scheduling

User Experience

• Real-time Validation: Provide immediate feedback on invalid data
• Progress Indicators: Show form completion progress
• Error Recovery: Provide clear instructions for correcting errors
• Mobile Optimization: Ensure forms work well on mobile devices

Integration Management

• Regular Testing: Periodically test the integration with sample data
• Monitor API Limits: Track API usage to prevent rate limiting
• Update Mappings: Keep field mappings current with ServiceTitan changes
• Backup Procedures: Maintain fallback processes for API failures

Security Considerations

• API credentials are encrypted and securely stored
• Customer data is transmitted using HTTPS encryption
• PII is handled according to privacy regulations
• Access logs are maintained for audit purposes
• Integration can be disabled immediately if needed
• Data retention policies are configurable

Limitations

• Maximum of 100 form submissions per hour to prevent API rate limiting
• Phone numbers must be in valid format for customer matching
• Addresses must be geocodable for location creation
• Booking dates must be within 365 days in the future
• Customer names are limited to 50 characters each
• Service descriptions are limited to 1000 characters

Compliance & Privacy

Data Handling

• GDPR Compliance: Customer data processing follows GDPR guidelines
• CCPA Compliance: California privacy rights are respected
• Data Minimization: Only necessary data is transmitted to ServiceTitan
• Consent Management: Customer consent is tracked and recorded

Audit Trail

• All API calls are logged with timestamps
• Customer data changes are tracked
• Integration status changes are recorded
• Error conditions are documented for review

Support & Maintenance

Regular Maintenance

• Monitor API credential expiration
• Update field mappings as needed
• Review error logs monthly
• Test integration quarterly
• Update service area boundaries as business expands

Getting Help

For integration support:

1. Check ServiceTitan connection status
2. Review form field mappings
3. Examine application logs for errors
4. Test with sample data
5. Contact support with specific error messages and form configuration