Prerequisites

Before you can use ServicePytan, you need to set up a ServiceTitan API application and obtain the necessary credentials. This guide walks you through the complete setup process.

Overview

To use ServicePytan, you’ll need:

ServiceTitan Account - Access to a ServiceTitan tenant (as customer or developer)
Developer Portal Access - Ability to create and manage API applications
API Application - A registered application in the ServiceTitan Developer Portal
Credentials - Client ID, Client Secret, App ID, App Key, and Tenant ID
Python Environment - Python 3.6+ with ServicePytan installed

Step 1: Request Developer Access

For ServiceTitan Customers

If you’re an existing ServiceTitan customer:

Email Integration Team
- Send request to: integrations@servicetitan.com
- Include your company name and ServiceTitan account details
- Specify that you want API access for your integration project
Provide Business Case
- Explain your integration requirements
- Describe the data you need to access
- Outline expected usage patterns

For External Developers

If you’re developing integrations for ServiceTitan customers:

Visit Developer Portal
- Go to: https://developer.servicetitan.io/request-access/
Complete Developer Registration
- Fill out the “Developer Registration Form”
- Provide your development company information
- Describe your intended integration
Wait for Approval
- ServiceTitan will review your application
- You’ll receive email confirmation once approved

Step 2: Access Developer Portal

Once approved, access the developer portal:

Navigate to Portal
- Go to: https://developer.servicetitan.io/signin/
Sign In
- Use your ServiceTitan credentials
- If you’re an external developer, use the credentials provided in your approval email
Verify Access
- Ensure you can see the developer dashboard
- Confirm your organization is listed correctly

Step 3: Create API Application

Application Creation

Start New Application
- Click “Create New App” or similar button
- This creates a new API application entry

Configure Application Details

Application Name: "My Integration" (descriptive name)
Organization: "Your Company Name"
Homepage: "https://yourcompany.com" (your organization's website)
Description: "Brief description of your integration's purpose"

Set Tenant Associations
- Add the Tenant IDs that will use this application
- For customers: Use your own Tenant ID
- For developers: Add customer Tenant IDs as needed

API Scope Configuration

Important Security Practice: Only request access to the endpoints you actually need.

Common scopes include:

jpm - Job management (jobs, appointments, estimates)
crm - Customer management (customers, locations, contacts)
accounting - Financial data (invoices, payments)
inventory - Equipment and materials
settings - Business units, technicians, job types
reporting - Custom reports access

Select Required Scopes
- Review available API scopes
- Check only the scopes your application requires
- Consider future needs but avoid over-requesting
Complete Application
- Click “Create App” or “Submit”
- Wait for the application to be created

Record Application Credentials

Note Application Details
- App ID: Found under the application title (e.g., “12345”)
- Application Key: Found in application details (e.g., “ak1.example123”)
⚠️ Important: Save these immediately as they may not be easily accessible later.

Step 4: Authorize Application in ServiceTitan

Now authorize your application within the ServiceTitan interface:

In ServiceTitan Desktop Application

Navigate to Integration Settings
- Log into ServiceTitan desktop application
- Go to: Settings > Integrations > API Application Access
Connect New Application
- Click “Connect New App” button
- Select your application from the list
- If your app doesn’t appear, ensure it was created properly in Step 3
Review and Accept Permissions
- Verify the requested permissions match your expectations
- Ensure only necessary scopes are requested
- Click “Allow Access” if everything looks correct

Record Authentication Credentials

Obtain Tenant ID and Client ID
- Tenant ID: Your ServiceTitan tenant identifier (e.g., “1234567890”)
- Client ID: OAuth client identifier (e.g., “cid.example123”)
Generate Client Secret
- Click “Generate Secret” or similar button
- ⚠️ CRITICAL: Copy the Client Secret immediately
- This is your only chance to see the full secret
- Store it securely (password manager, secure notes, etc.)

Client Secret Management

Important Notes:

Each application can have maximum 2 active client secrets
Secrets cannot be viewed again after initial generation
If lost, you must generate a new secret (old one remains valid until deleted)
Consider generating a backup secret for rotation purposes

Step 5: Environment Setup

Installation Requirements

Ensure you have the proper Python environment:

# Check Python version (3.6+ required)
python --version

# Install ServicePytan
pip install servicepytan

# For development/testing
pip install servicepytan[dev]

Environment Configuration

Choose your preferred configuration method:

Option A: JSON Configuration File (Recommended for Development)

Create servicepytan_config.json:

{
    "SERVICETITAN_CLIENT_ID": "cid.your_client_id_here",
    "SERVICETITAN_CLIENT_SECRET": "cs2.your_client_secret_here",
    "SERVICETITAN_APP_ID": "your_app_id_here",
    "SERVICETITAN_APP_KEY": "ak1.your_app_key_here", 
    "SERVICETITAN_TENANT_ID": "your_tenant_id_here",
    "SERVICETITAN_TIMEZONE": "America/New_York",
    "SERVICETITAN_API_ENVIRONMENT": "production"
}

Security: Add to .gitignore to prevent committing credentials.

Option B: Environment Variables (Recommended for Production)

# Set environment variables
export SERVICETITAN_CLIENT_ID="cid.your_client_id_here"
export SERVICETITAN_CLIENT_SECRET="cs2.your_client_secret_here"
export SERVICETITAN_APP_KEY="ak1.your_app_key_here"
export SERVICETITAN_TENANT_ID="your_tenant_id_here"
export SERVICETITAN_API_ENVIRONMENT="production"

Step 6: Test Your Setup

Basic Connection Test

Create a test script to verify your setup:

import servicepytan

try:
    # Test configuration loading
    conn = servicepytan.auth.servicepytan_connect(
        config_file="servicepytan_config.json"  # or omit for env vars
    )
    print("✅ Configuration loaded successfully")
    
    # Test authentication
    token = servicepytan.auth.get_auth_token(conn)
    print("✅ Authentication successful")
    
    # Test API access
    endpoint = servicepytan.Endpoint("settings", "business-units", conn=conn)
    business_units = endpoint.get_all({"pageSize": 1})
    print("✅ API access confirmed")
    
    print("🎉 Setup completed successfully!")
    
except Exception as e:
    print(f"❌ Setup failed: {e}")
    print("Please check your credentials and configuration")

Environment Testing

If available, test with the integration environment:

# Test integration environment
integration_conn = servicepytan.auth.servicepytan_connect(
    api_environment="integration",
    config_file="integration_config.json"
)

# Run same tests as above

Credential Management Best Practices

Security Guidelines

Never Commit Credentials
- Add config files to .gitignore
- Use environment variables in production
- Consider using secrets management systems
Principle of Least Privilege
- Request only necessary API scopes
- Regularly review application permissions
- Remove unused applications
Credential Rotation
- Generate backup client secrets
- Rotate secrets regularly (quarterly recommended)
- Monitor for unauthorized usage
Access Control
- Limit who has access to credentials
- Use role-based access for teams
- Audit credential usage regularly

Secrets Management

For production environments, consider:

AWS Secrets Manager
Azure Key Vault
HashiCorp Vault
Kubernetes Secrets

Troubleshooting Common Issues

Application Not Found

Verify application was created in Developer Portal
Check that application is associated with correct tenant
Ensure application is published/active

Permission Denied

Review API scopes in Developer Portal
Verify application authorization in ServiceTitan
Check that tenant ID matches your ServiceTitan instance

Authentication Failures

Verify all credentials are copied correctly
Check for extra spaces or characters
Ensure Client Secret hasn’t expired
Confirm you’re using the correct environment (production vs integration)

Network Issues

Verify internet connectivity
Check firewall settings for API endpoints:
- Production: https://api.servicetitan.io
- Integration: https://api-integration.servicetitan.io
- Auth: https://auth.servicetitan.io or https://auth-integration.servicetitan.io

Next Steps

Once your prerequisites are complete:

Review Configuration Guide: Configuration Documentation
Try Examples: Examples and Use Cases
Explore API Reference: ServicePytan API Reference

For deployment to production environments, see: Deployment Guide

Back to Getting Started | Next: Configuration